The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CGI-Session-Submitted-1.07
River stage zero No dependents
++
/ CGI::Session::Submitted

NAME

CGI::Session::Submitted - Automatic session and persistence of query data.

SYNOPSIS

        use CGI::Session::Submitted;    
        
        my $s = new CGI::Session::Submitted;
        $s->run( { theme=> 'light', help_on=> 1 } );

DESCRIPTION

This module is a wrap around CGI::Session. It offers a standard way in which you may want to use a session object in regards to incoming query data.

This is how one may normally use a session object:

  • First, you would want to create a new session if one is not loaded.

  • Then you want to make sure that the client can keep track of the session.

  • Thirdly you may have certain query data that the user client may submit that you want them to be able to change at any time.

  • Last, you want those specific parameters you specified to be readily available to your code via a cgi object.

This module keeps track of all those things for you.

        my $s = new CGI::Session::Submitted;

        my $cgi = $s->run({ theme=> 'light', help_on => 1 }); 

        $cgi->param('theme');   # returns 'light'
        $s->param('theme');             # also returns 'light'

In this example, param 'theme' will return light always - unless the user has at any point submitted a different value for it via GET or POST.

Any data you want the client to be able to change at any moment, you should place as an argument to run(), with default values. Imagine you are taking address information, you may want to do this:

        my $s = new CGI::Session::Submitted;

        my $cgi = $s->run({ 
                address_name => undef,
                address_line_1 => undef,
                address_line_2 => undef,
                address_city => undef,
                address_state => undef,
                address_zip => undef,
                address_country => US,
        });

If at any moment POST or GET contain these params (form fields), then they are automatically saved to the session object. Your presets will not override a user submission. Also, these objects are readily available parms in the $cgi object returned. You do not *have* to use the cgi query object returned via the session object. You may choose to simply query the session object for this.

This module inherits CGI::Session and all its methods.

PUBLIC METHODS

Don't forget this module inherits CGI::Session and all its wonderful and useful methods.

run()

Argument is a hash ref. Each key is a param name you want to keep track of. The values are the defaults to set. Returns cgi object with params loaded into it.

If session is new: sets presets, makes cookie, redirects and exits This is so you do not have to track the session id.

All params in the query object (cgi) that match the arguments, are automatically saved to the session.

All the params we declared will be automatically loaded into the query object (cgi object, if you will).

Returns cgi query object with params from session loaded into itself.

session_to_tmpl()

If you have an existing HTML::Template object and you want to load it with all the params in session object.

        $s->session_to_tmpl($tmpl);

If the value is undef, sets to 0.

Returns HTML::Template object you provided as argument.

query_to_tmpl()

If you have an existing HTML::Template object and you want to load it with all the params in the cgi query object. If value is undef, sets to 0.

        $s->query_to_tmpl($tmpl)

Returns HTML::Template object you provided as argument.

get_presets()

Returns array ref of presets you defined via run(). This is just a list with the names of the params you predefined via run().

INTERNAL METHODS

_assure_cookie()

If the session is new (the client did not already have one) then this prints a header with a cookie and redirects to itself ( environment variable SCRIPT_NAME ).

BUGS

Please inform developer of any bugs or issues concerning this module. If there's a feature you would like to see added, please suggest. I will go the distance.

TODO

Should allow specifying a different cookie, a timeout for it, etc. Present cookie does not have an expiry specified. The idea is if these are user options, then Why do you want to get rid of them? I can see a lot of reasons why. But for now this should do.

COPYRIGHT

Copyright (C) Leo Charre <leo@leocharre.com>. All rights reserved. This library is free software. You can modify and or distribute it under the same terms as Perl itself.

AUTHOR

Leo Charre <leo@leocharre.com>, http://leocharre.com

SEE ALSO