/ 
CGI-Builder-Session-1.23
River stage zero No dependents
/ CGI::Builder::Session

NAME

CGI::Builder::Session - CGI::Builder and CGI::Session integration

VERSION 1.23

The latest versions changes are reported in the Changes file in this distribution. To have the complete list of all the extensions of the CBF, see "Extensions List" in CGI::Builder

INSTALLATION

Prerequisites
CGI::Builder >= 1.2
CGI::Session >= 3.95
File::Spec   >  0
CPAN
perl -MCPAN -e 'install CGI::Builder::Session'

You have also the possibility to use the Bundle to install all the extensions and prerequisites of the CBF in just one step. Please, notice that the Bundle will install A LOT of modules that you might not need, so use it specially if you want to extensively try the CBF.

perl -MCPAN -e 'install Bundle::CGI::Builder::Complete'
Standard installation

From the directory where this file is located, type:

perl Makefile.PL
make
make test
make install

SYNOPSIS

use CGI::Builder
qw| CGI::Builder::Session
    ...
  |;

DESCRIPTION

This module transparently integrates CGI::Builder and CGI::Session in a very handy and flexible framework that can save you some coding. It provides you a mostly automatic and ready to use CGI::Session object (cs property) useful to maintain the state of your application between requests. Please refer to CGI::Session for more documentation about sessions.

How it works

This extension creates a CGI::Session object automatically, using the old session id if it is found as a cookie or as a query param. If no session id is found, it creates a new session and automatically adds a session id cookie and a session id param that will be automatically used to send the id to the client

In simple cases you can avoid to init, update and flush the session: just use it and it will work as expected; if you need more customization you can override every single argument, property or even method.

Note: When you include in your CBB the CGI::Builde::Magic extension, you will have magically available a label that will be substituted with the current session id.

PROPERTY and GROUP ACCESSORS

This module adds some session properties (all those prefixed with 'cs_') to the standard CBF properties. The default of these properties are usually smart enough to do the right job for you, but you can fine-tune the behaviour of your CBB by setting them to the value you need.

cs

This property returns the internal CGI::Session object that is automatically created just before you use it. It is already initialized with the existing session or with a new session if there are no existing session yet. Anyway, you can directly use it in your code without any other initialization.

# check some flag
sub OH_pre_process {
    my $s = shift;
    $s->cs->param('logged')
       || switch_to('login');
}

# saves cgi parameter for later use
sub PH_myPage1 {
    my $s = shift;
    $s->cs->save_param($s->cgi, "category");
}

# retrieve a session parameter saved in a previous request
sub PH_myPage2 {
    my $s = shift;
    my $categ = $s->cs->param("category");
}

Note: You can change the default arguments that are internally used to create the object by using the cs_new_args group accessor, or you can completely override the creation of the internal object by overriding the cs_new() method.

cs_new_args( arguments )

This property group accessor handles the CGI::Session constructor arguments that are used in the creation of the internal CGI::Session object. Use it to change the argument you need to the creation of the new object. Note: use it BEFORE using the cs object or your arguments will be ignored.

It uses the following defaults:

  • DSN

    Data Source Name: this argument is set to the undef value by default (i.e. DSN equal to File).

  • SID

    Session ID: this argument is set by default to the cookie, or to the query param named $CGI::Session::NAME (usually 'CGISESSID'), or to the undef value if neither the cookie nor the param are found.

  • DSN_param

    Data Source Name param This argument is referring to the File DSN, and is set by default to:

    { Directory => File::Spec->tmpdir }

These defaults produce the most compatible and multiplatform CGI::Session object which is equal to:

CGI::Session->new( undef,    # DNS equal to File
                   $s->cgi , # SID equal to cookie or param $CGI::Session::NAME
                   { Directory => File::Spec->tmpdir } # DSN_param for File
                 );

Note: You should change just the argument that you need to customize, i.e. usually just DSN and DSN_param.

METHODS

cs_new()

This method is not intended to be used directly in your CBB. It is used internally to initialize and return the CGI::Session object. You usually don't need even to override it since you can customize the cs object by using the cs_new_args group accessor, or eventually override the cs_init method.

cs_init

This method is internally called by the cs_new() method, so you don't need to use it unless you need to override it. The purpose of this method is setting automatically the session id that has to be sent to the client. It does so by adding the session id cookie to the headers, and by adding also the session id query param to the query.

Note: these operations are done only if the session is new and using the $CGI::Session::NAME as the name of the cookie and query param, so you can set that variable as usual to set a different session id name.

You can override this method if you need to execute some code when the cs object is created or if you need to pass the new session id by any other means (in this case you should also accordingly update the 'SID' argument of the cs_new_args).

Overriding Note: At the moment this method is executed, the cs property is not set yet, but the CGI::Session object is already created and available as $_[1].

SUPPORT

Support for all the modules of the CBF is via the mailing list. The list is used for general support on the use of the CBF, announcements, bug reports, patches, suggestions for improvements or new features. The API to the CBF is stable, but if you use the CBF in a production environment, it's probably a good idea to keep a watch on the list.

You can join the CBF mailing list at this url:

http://lists.sourceforge.net/lists/listinfo/cgi-builder-users

AUTHOR and COPYRIGHT

© 2004 by Domizio Demichelis (http://perl.4pro.net)

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 224:

Non-ASCII character seen before =encoding in '©'. Assuming CP1252