Initial addition of storytitle plugin
[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 This plugin is now maintained by the Blosxom Sourceforge Team,
190 <blosxom-devel@lists.sourceforge.net>.
191
192 =head1 SEE ALSO
193
194 Blosxom Home/Docs/Licensing: http://blosxom.sourceforge.net/
195
196 Blosxom Plugin Docs: http://blosxom.sourceforge.net/documentation/users/plugins.html
197
198 =head1 BUGS
199
200 None known; please send bug reports and feedback to the Blosxom
201 development mailing list <blosxom-devel@lists.sourceforge.net>.
202
203 =head1 LICENSE
204
205 Blosxom and this Blosxom Plug-in
206 Copyright 2003, Rael Dornfest 
207
208 Permission is hereby granted, free of charge, to any person obtaining a
209 copy of this software and associated documentation files (the "Software"),
210 to deal in the Software without restriction, including without limitation
211 the rights to use, copy, modify, merge, publish, distribute, sublicense,
212 and/or sell copies of the Software, and to permit persons to whom the
213 Software is furnished to do so, subject to the following conditions:
214
215 The above copyright notice and this permission notice shall be included
216 in all copies or substantial portions of the Software.
217
218 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
219 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
220 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
221 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
222 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
223 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
224 OTHER DEALINGS IN THE SOFTWARE.