MasonX::Request::WithMultiSession(3pm)			User Contributed Perl Documentation		    MasonX::Request::WithMultiSession(3pm)

NAME

       MasonX::Request::WithMultiSession - Multiple sub-sessions within one "parent" session

SYNOPSIS

	 PerlSetVar  MasonRequestClass	MasonX::Request::WithMultiSession

DESCRIPTION

       This module subclasses "MasonX::Request::WithApacheSession" in order to allow multiple "sub-sessions" to exist within one parent session.

       This can be quite useful for a web app where you want to allow the user to open multiple windows, each with a different session, but
       session ids are stored in a cookie.

       Like "MasonX::Request::WithApacheSession", sub-sessions are shared between a request and any subrequests it creates.

METHODS

       This class has an interface quite similar to that of "MasonX::Request::WithApacheSession".

       o   session

	   The primary interface to this class is through the "session()" method.  When this method is called without any parameters, the module
	   looks for an existing sub-session specified by the sub-session id argument parameter (which can be in a query string or POST).  This
	   value can be overridden by explicitly passing a "sub_session_id" parameter.

	   If this parameter is found, an existing sub-session is returned.  If this parameter is not found, a new sub-session is created.

	   If the "session()" method is called as "session( clone => 1 )" then a new sub-session will be created, and its contents will be the
	   same as that of the current sub-session.  This is a shallow copy of the old session hash, so objects and references are shared between
	   them.

	   If "session( new => 1 )" is called, then a new, empty, sub-session is created.

	   You can specify the main session id to use via the "session_id" parameter.

       o   sub_session_id

	   This method returns the currently active sub-session's id.  Use this method to put this id into URL parameters, forms, etc. as needed.

	   If given a "sub_session_id" parameter, it will set the current sub-session id.

       o   delete_sub_session

	   By default, this simply defaults the current sub-session.  You can pass a "sub_session_id" parameter to delete a specific session.

   Parameters
       This module takes two parameters besides those inherited from "MasonX::Request::WithApacheSession":

       o   multi_session_args_param / MultiSessionArgsParam

	   This parameter can be used to specify which parameter contains the sub-session id.  By default, the module will look for a parameter
	   called "sub_session_id".

       o   multi_session_expire / MultiSessionExpire

	   This parameter specifies the number of seconds after a sub-session is accessed until it is purged.  If not specified, then sub-sessions
	   are never purged.

	   Sub-sessions expiration is checked when the request object goes out of scope.

USAGE

       You will need to manually set the sub-session id argument parameter for each request.  The easiest way to do this is to make sure that all
       URLs contain the sub-session id.  This can be done by using a "<%filter>" block in a top-level autohandler (although this won't catch
       redirects), or by making sure all URLs are generated by a single component/function.

SUPPORT

       Bug reports and requests for help should be sent to the mason-users list.  See http://www.masonhq.com/resources/mailing_lists.html for more
       details.

AUTHOR

       Dave Rolsky, <autarch@urth.org>

       Development funded by Marigold Technologies.

SEE ALSO

       HTML::Mason

perl v5.14.2							    2012-12-01				    MasonX::Request::WithMultiSession(3pm)