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.