Add README and README.cvs.
[matthijs/upstream/blosxom-plugins.git] / general / cookies
1 # Blosxom Plugin: cookies
2 # Author(s): Rael Dornfest <rael@oreilly.com> 
3 # Version: 2003-03-20
4 # Documentation: See the bottom of this file or type: perldoc cookies
5
6 package cookies;
7
8 # --- Configurable variables -----
9
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.
12 $domain = '';
13
14 # What path should I assign to cookies?
15 $path = '/';
16
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
20 $expires = '+10y';
21
22 # --------------------------------
23
24 use CGI qw/:standard/;
25
26 my %cookies = ();
27
28 sub start {
29   foreach ( cookie() ) {
30     my %hash = cookie($_);
31     $cookies{$_} = \%hash;
32   }
33   1;
34 }
35
36 sub foot {
37   my @cookies = values %cookies;
38   $blosxom::header->{'-cookie'} = \@cookies;
39
40   1;
41 }
42
43 sub add {
44   foreach ( @_ ) {
45     my($name) = $_ =~ /^(.+?)=/;
46     $cookies{$name} = $_;
47   }
48   1;
49 }
50
51 sub remove {
52   foreach ( @_ ) {
53     delete $cookies{$_};
54   }
55   1;
56 }
57
58 sub clear {
59   foreach ( @_ ) {
60     $cookies{$_} = '';
61   }
62   1;
63 }
64
65 sub get {
66   my($name) = @_;
67   return $name ? $cookies{$name} : \%cookies;
68 }
69
70 sub list {
71   return keys %cookies;
72 }
73
74
75 1;
76
77 __END__
78
79 =head1 NAME
80
81 Blosxom Plug-in: cookies
82
83 =head1 SYNOPSIS
84
85 Provides basic cookie functionality for use by any number of Blosxom plug-ins.
86
87 =head1 INSTALLATION & CONFIGURATION
88
89 Drop the cookies plug-in into your Blosxom plugins directory. 
90
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.
95
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.
98
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).
101
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
106 from now.
107
108 =head1 USAGE
109
110 As an end-user, once you have the cookies plug-in installed and configured, 
111 you're done.
112
113 =head1 DEVELOPMENT
114
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 
118 comment.
119
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.
123
124 You have the following methods at your disposal:
125
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.
127
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
130 set.
131
132 usage:
133
134 &cookies::add(
135   cookie(
136     -name=>'plugin cookie 1'
137     -value=>{ 'some key' => 'some value' }
138     -path=>$cookies::path,
139     -domain=>$cookies::domain
140   )
141   cookie(
142     -name=>'plugin cookie 2', 
143     -value=>{ 'first key' => 'first value', 'second key' => 'second value' }
144     -path=>$cookies::path,
145     -domain=>$cookies::domain
146   )
147 );
148
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 
151 browser.
152
153 usage:
154
155 &cookies::remove('plugin cookie 1');
156
157 =item * clear('cookie name') sets a blank value for the 'cookie name' cookie,
158 thereby clearing it in the client browser.
159
160 usage:
161
162 &cookies::clear('plugin cookie 2');
163
164 =item * list() lists the names of all cookies on the stack.
165
166 usage:
167
168 my @cookie_names = &cookies::list();
169
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.
172
173 usage:
174
175 my $cookies = &cookies::get();
176 my @cookie_names = keys %$cookies;
177
178 my $particular_cookie = &cookies::get('cookie name');
179 my $values = values %$particular_cookie;
180
181 =head1 VERSION
182
183 2003-03-20
184
185 =head1 AUTHOR
186
187 Rael Dornfest  <rael@oreilly.com>, http://www.raelity.org/
188
189 =head1 SEE ALSO
190
191 Blosxom Home/Docs/Licensing: http://www.raelity.org/apps/blosxom/
192
193 Blosxom Plugin Docs: http://www.raelity.org/apps/blosxom/plugin.shtml
194
195 =head1 BUGS
196
197 Address bug reports and comments to the Blosxom mailing list 
198 [http://www.yahoogroups.com/group/blosxom].
199
200 =head1 LICENSE
201
202 Blosxom and this Blosxom Plug-in
203 Copyright 2003, Rael Dornfest 
204
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:
211
212 The above copyright notice and this permission notice shall be included
213 in all copies or substantial portions of the Software.
214
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.