NAME

Template::Plugin::Session - Template Toolkit interface to Apache::Session

SYNOPSIS

   [% USE my_sess = Session (undef,
            { Store => 'File' 
              Generate => 'MD5',
              Lock => 'Null',
              Serialize => 'Storable',
              Directory => '/tmp/session_data/' } %]

   # Getting single session value
   SID = [% my_sess.get('_session_id') %]

   # Getting multiple session values
   [% FOREACH s = my_sess.get('_session_id','foo','bar') %]
   * [% s %]
   [% END %]
   # same as
   [% keys = ['_session_id','foo','bar'];
      FOREACH s = my_sess.get(keys) %]
   * [% s %]
   [% END %]

   # Getting all session values
   [% FOREACH s = my_sess.get %]
   * [% s %]
   [% END %]

   # Setting session values:
   [% my_sess.set('foo' => 10, 'bar' => 20, ...) %]

   # Deleting session value(s)
   [% my_sess.delete('foo', 'bar') %]
   # same as
   [% keys = ['foo', 'bar'];
      my_sess.delete(keys) %]

   # Destroying session
   [% my_sess.destroy %]

DESCRIPTION

This Template Toolkit plugin provides an interface to Apache::Session module wich provides a persistence framework for session data.

A Session plugin object can be created as follows:

   [% options = { 
         Store => 'File' 
         Generate => 'MD5',
         Lock => 'Null',
         Serialize => 'Storable',
         Directory => '/tmp/session_data/'
        } %] 
   # for a first time session generation
   [% USE my_sess = Session ( undef, options ) %]

   # to retrieve session by id
   [% USE my_sess = Session ( 'b7cc652e2944b8f77651d1a122cdc5f2', options ) %]

The options keys are identical to Apache::Session::Flex.

With this hash you must provide the store, serializer, id generator and whatever arguments are expected by the backing store and lock manager that you've chosen.

Please see the documentation for Apache::Session::Flex and for store/lock modules in order to pass right arguments.

If the constructor cannot create a session instance using the arguments passed, a Session Exception is thrown, which will need to be caught appropriately:

   [% TRY %]
      [% USE my_sess = Session ( 'a2414cb819502fa78e0e9187e95f53e8', options ) %]
   [% CATCH Session %]
      Can't create/restore session id
   [% CATCH %]
      Unexpected exception: [% error %]
   [% END %]

You can then use the plugin methods.

METHODS

get([array])

Reads a session value(s) and returns an array containing the keys values:

   Session id is [% my_sess.get('_session_id') %]

   [% FOREACH s = my_sess.get('foo', 'bar') %]
   * [% s %]
   [% END %]

Also it is possible to call get method:

   [% keys = [ 'foo', 'bar' ];
      FOREACH s = my_sess.get(keys) %]
   * [% s %]
   [% END %]

Called with no args, returns all keys values.

set(hash)

Set session values

   [% my_sess.set('foo' => 10, 'bar' => 20, ...) %]

Called with no args, has no effects.

delete(array)

Delete session values

   [% my_sess.delete('foo', 'bar', ...) %]

Also it is possible to call delete method:

   [% keys = [ 'foo', 'bar' ];
      my_sess.delete(keys) %]

Called with no args, has no effects.

destroy

Destroy current session

   [% my_sess.destroy %]

AUTHORS

Enrico Sorcinelli <enrico@sorcinelli.it>

BUGS

This library has been tested by the author with Perl versions 5.005, 5.6.0 and 5.6.1 on different platforms: Linux 2.2 and 2.4, Solaris 2.6 and 2.7.

Send bug reports and comments to: enrico@sorcinelli.it. In each report please include the version module, the Perl version, the Apache, the mod_perl version and your SO. If the problem is browser dependent please include also browser name and version. Patches are welcome and I'll update the module if any problems will be found.

VERSION

Version 0.01

SEE ALSO

Apache::Session, Apache::Session::Flex, Template, Apache, perl

COPYRIGHT AND LICENSE

Copyright (C) 2001-2003 Enrico Sorcinelli. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Template::Plugin::Session

perl -MCPAN -e shell
install Template::Plugin::Session