NAME

Bric::App::Session - A class to handle user sessions

VERSION

$Revision: 1.9 $

DATE

$Date: 2001/12/04 18:17:43 $

SYNOPSIS

use Bric::App::Session;

#- Methods called from the apache perl handler -#

setup_user_session($r);

sync_user_session();

handle_callbacks($interp);

#- Methods called from widgets -#

[$new_state_name, $new_state_data] = init_state($widget, $state, $data);

$state_name = state_name($widget, $name);

$state_data = state_data($widget, ($data_hash || $name, $value));

[$state_name, $state_data] = state($widget, $state_name, $state_data);

DESCRIPTION

This module provides all the necessary functions for maintaining state within widgets. This includes setting a global state variable $session as well as accessor methods for setting the state name of a widget and state data of a widget.

setup_user_session($r)

This function takes an Apache request object and sets up the persistant user session hash. This hash is tied to an Apache::Session::File object.

Throws:

Side Effects:

Notes:

NONE

sync_user_session()

Syncronizes changes to the user session back to the file system.

Throws:

Side Effects:

Notes:

NONE

expire_session()

Expires the user session, deleting it from the disk.

Throws:

Side Effects:

Notes:

NONE

handle_callbacks($interp, $parameter_hash)

This function takes an HTML::Mason::Request ($m) object and an anonymous hash of GET and/or POST data as its arguments. It scans anonymous hash looking for specially marked up field names. If it finds them, it executes the proper Mason callback element. Ideally, it should be called from an autohandler, so that it executes before any dhandlers:

<%perl>;
unless ($ARGS{__CB_DONE}) {
    # Setup the global session variable.
    Bric::App::Session::setup_user_session($r);

    # Execute an callbacks set for this request.
    Bric::App::Session::handle_callbacks($m, \%ARGS);
}
$m->call_next(%ARGS);
</%perl>

The handle_callbacks() function adds the __CB_DONE key to %ARGS so that when it calls callback element, the autohandler can avoid calling handle_callbacks() again.

Throws:

Side Effects: Executes one or more callback mason elements.

Notes: The format for field names that will be handled by this function is:

<widget_name>|<field_name>_cb

If any request sends a field element of this format, this callback function will look in the widget directory, within the folder named <widget_name> and look for a mason element called 'callback.mc'. This element will be called with the widget name, the field name that cause the callback and the query string (and/or form field) parameters:

$m->comp($callback_comp, widget => $widget_name,
         field => $field_name, param => $parameter_hash);
[$new_state_name, $new_state_data] = init_state($widget, $state, $data)
$cur_name = init_state_name($widget, $name);
$cur_val = init_state_data($widget, $name, $value);
$key_val = reset_state($widget, $reset_key);

If a widget has not yet been called and this function is called, it will set some default values for that widgets state name and state data.

Throws:

NONE

Side Effects:

Notes:

NONE

$state_name = set_state_name($widget, $name)
$state_name = get_state_name($widget)

Set or get the current widget state name. A state name cannot be set to undef since it is bad style to rely on a state that you do not set explicitly. If you want to clear the state entirely, use clear_state.

Throws:

NONE

Side Effects:

Notes:

NONE

$state_data = set_state_data($widget, ($data_hash || $name, $value))
$state_data = get_state_data($widget, $name)

Get or set the state data. The set function takes either a hash or a key/value. Given a hash the set function will overwrite the state data. Given a key/value pair, it will set that key in the state data to that value.

The get function will return the whole state data hash if given just a widget. If passed a name it will return the value for the state data with that name.

Throws:

NONE

Side Effects:

Notes:

NONE

[$state_name, $state_data] = set_state($widget, $state_name, $state_data)
[$state_name, $state_data] = get_state($widget)

The set function takes a widget name, $widget, a state name, $state_name, and a hash ref, $state_data, containing state data. Both $state_name and $state_data are optional. If $state_name is undef, the state name will not be set, but if it does have a value it will be used to update the widget $widget state name. The same holds true for $state_data; undef will leave the state data untouched while a hash value will be used to overwrite the state data.

The get function returns both the state name and the state data..

Throws:

NONE

Side Effects:

Notes:

NONE

clear_state($widget)

Completely clears the state information for the given widget.

Throws:

NONE

Side Effects:

Notes:

NONE

(0 || 1) = set_user($user);
($login || undef) = get_user_login;
($uid || undef) = get_user_id;
($user || undef) = get_user_object;

Get/set logged in user information.

Throws: NONE

Side Effects:

Notes: NONE

INTERFACE

Constructors

Destructors

Public Class Methods

Public Instance Methods

Private Methods

Private Class Methods

NONE

Private Instance Methods

NONE

NOTES

NONE

AUTHOR

"Garth Webb" <garth@perijove.com>
Bricolage Engineering

SEE ALSO

perl, Bric, Apache::Session::File

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 172:

'=item' outside of any '=over'

Around line 806:

You forgot a '=back' before '=head1'

Around line 817:

You forgot a '=back' before '=head2'

Around line 863:

=back without =over