1 # Blosxom Plugin: cookies
2 # Author(s): Rael Dornfest <rael@oreilly.com>
4 # Documentation: See the bottom of this file or type: perldoc cookies
8 # --- Configurable variables -----
10 # What domain should I assign to cookies (e.g. .example.com, www.example.com)?
11 # REQUIRED; if you don't fill in a domain, the plug-in won't work properly.
14 # What path should I assign to cookies?
17 # How soon should cookies expire?
18 # (e.g. +1d is 1 day, +3m is 3 months, and +10y is 10 years from now)
19 # Leave this blank and the cookie will expire when the browser is closed
22 # --------------------------------
24 use CGI qw/:standard/;
29 foreach ( cookie() ) {
30 my %hash = cookie($_);
31 $cookies{$_} = \%hash;
37 my @cookies = values %cookies;
38 $blosxom::header->{'-cookie'} = \@cookies;
45 my($name) = $_ =~ /^(.+?)=/;
67 return $name ? $cookies{$name} : \%cookies;
81 Blosxom Plug-in: cookies
85 Provides basic cookie functionality for use by any number of Blosxom plug-ins.
87 =head1 INSTALLATION & CONFIGURATION
89 Drop the cookies plug-in into your Blosxom plugins directory.
91 Be sure cookies is called last, giving all other plugins a chance to
92 add, remove, and clear cookies before the the cookies plug-in returns the
93 header to the browser. The easiest way to do this is to rename the plug-in
94 9999cookies or the like, assuring that is sorted last, alphanumerically.
96 Set a $domain for your cookies. I recommend using any host in your domain,
97 e.g. .example.com, instead of just limiting to www, e.g. www.yourdomain.
99 Assign a $path for your cookies. This should be the base path of your weblog.
100 Use / if your weblog lives at the root of your domain (e.g. http://www.example.com/) or /weblog, for example, if it lives at a /weblog subpath (e.g. http://www.example.com/weblog).
102 Set a time-out period for cookies. While there are various allowed forms
103 for this expires piece (see perldoc CGI.pm), I like using +n(d,m,y) for
104 n days, months, or years from now. For example: +1d is 1 day,
105 +3m is 3 months, and +10y is 10 years from now. The default is 10 years
110 As an end-user, once you have the cookies plug-in installed and configured,
115 Plug-in developers may use the cookies module as a base for cookie-usage
116 by your own Blosxom plug-in. An example may be found in the writeback
117 plug-in's use of cookies to remember the name and url of a person leaving a
120 All cookies are kept on a stack (in a %cookies hash, actually). Incoming
121 cookies sent by the browser are automagically added to the %cookies stack
122 in the start() subroutine.
124 You have the following methods at your disposal:
126 =item * add($cookie1, $cookie2, ...) adds a cookie to the stack to be sent to the client browser. Cookies should be well-formed; I suggest using the Perl CGI.pm module's cookie() subroutine to create each cookie.
128 So that cookies can all be handled in the same manner by the cookies plug-in,
129 you must use a hash as your cookie value, even if you only have one value to
136 -name=>'plugin cookie 1'
137 -value=>{ 'some key' => 'some value' }
138 -path=>$cookies::path,
139 -domain=>$cookies::domain
142 -name=>'plugin cookie 2',
143 -value=>{ 'first key' => 'first value', 'second key' => 'second value' }
144 -path=>$cookies::path,
145 -domain=>$cookies::domain
149 =item * remove('cookie name') removes a previously added cookie named 'cookie
150 name' from the stack. Note, this does not unset the cookie in the client
155 &cookies::remove('plugin cookie 1');
157 =item * clear('cookie name') sets a blank value for the 'cookie name' cookie,
158 thereby clearing it in the client browser.
162 &cookies::clear('plugin cookie 2');
164 =item * list() lists the names of all cookies on the stack.
168 my @cookie_names = &cookies::list();
170 =item * get() gets a reference to a hash {cookie name => cookie value} of all
171 cookies on the stack. get('cookie name') gets a hash reference for the 'cookie name' cookie.
175 my $cookies = &cookies::get();
176 my @cookie_names = keys %$cookies;
178 my $particular_cookie = &cookies::get('cookie name');
179 my $values = values %$particular_cookie;
187 Rael Dornfest <rael@oreilly.com>, http://www.raelity.org/
191 Blosxom Home/Docs/Licensing: http://www.raelity.org/apps/blosxom/
193 Blosxom Plugin Docs: http://www.raelity.org/apps/blosxom/plugin.shtml
197 Address bug reports and comments to the Blosxom mailing list
198 [http://www.yahoogroups.com/group/blosxom].
202 Blosxom and this Blosxom Plug-in
203 Copyright 2003, Rael Dornfest
205 Permission is hereby granted, free of charge, to any person obtaining a
206 copy of this software and associated documentation files (the "Software"),
207 to deal in the Software without restriction, including without limitation
208 the rights to use, copy, modify, merge, publish, distribute, sublicense,
209 and/or sell copies of the Software, and to permit persons to whom the
210 Software is furnished to do so, subject to the following conditions:
212 The above copyright notice and this permission notice shall be included
213 in all copies or substantial portions of the Software.
215 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
216 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
217 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
218 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
219 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
220 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
221 OTHER DEALINGS IN THE SOFTWARE.