/ 
Pgreet-0.9.5
River stage zero No dependents
/ Pgreet::CGIUtils

NAME

Pgreet::CGIUtils - Penguin Greetings shared routines for CGI functions.

SYNOPSIS

# Constructor:
$Pg_cgi = new Pgreet::CGIUtils($Pg_default_config, $cgi_script,
                               $query, $SpeedyCGI, $Invocations,
                               $StartTime
                              );

# Set card site specific configuration
$Pg_cgi->set_site_conf($Pg_config, $card_conf, $BackVarStr,
                       $BackHiddenFields
                      );

# Assign a value to be passed on to Embperl
$Pg_cgi->set_value('error_hash', $error_hash);

# Create Transfer hash for Embperl
my $Transfer = $Pg_cgi->ChangeVars();

DESCRIPTION

The module Pgreet::CGIUtils is the Penguin Greetings module for any routines that must be shared between the CGI application and other modules. The first task thus shared is the creation of a hash of values to be transferred from Penguin Greetings to Embperl for processing of templates.

Like the other modules associated with Penguin Greetings, there is a certain bit of bootstrapping involved. The constructor is used as soon as the other main objects associated with Penguin Greetings are created. However, that information may not be up-to-date once secondary ecard sites have been selected. So the state of the CGIUtils object is updated once an ecard site is definitely selected.

For the matter of setting up the Transfer hash to Embperl the method ChangeVars is used in two settings. It is used within the main CGI Application itself and used with Pgreet::Error to allow for error templates to have access to all of the state variables that content developers would have access to in a normal (non-error) situation.

CONSTRUCTING A CGIUTILS OBJECT

The Pgreet::CGIUtils constructor should be called after a query object has been obtained from the CGI module and a Penguin Greetings Configuration object has been created. In addition, Pgreet::CGIUtils requires one additional argument and has three other arguments related to the SpeedyCGI version of Penguin Greetings. The required argument is the name of the script creating the object (usually the basename of $0.) The three optional arguments are a boolean which if true indicates that this script is running as a SpeedyCGI process, the number of SpeedyCGI innovcations, and the UNIX time when this SpeedyCGI process was started. The calling syntax is illustrated below:

$Pg_cgi = new Pgreet::CGIUtils($Pg_default_config, $cgi_script,
                               $query, $SpeedyCGI, $Invocations,
                               $StartTime
                               );

Because the Penguin Greetings error object needs a reference to the Pgreet::CGIUtils object, you should use the add_cgi_obj method of Pgreet::Error to attach that reference as soon as you have created the new CGIUtils object:

# Attach new CGIUtils object to Error obj.
$Pg_error->add_cgi_obj($Pg_cgi);

$Pg_error = new Pgreet::Error($Pg_default_config, 'CGIApp');

From that point on, this error object can be used to report errors in the application with all state variables available for error template.

METHODS TO UPDATE STATE

Once the Pgreet::CGIUtils object has been created, you may need to update some of the settings with which it was created. There is a very particular point when this must be done, when the choice of ecard sites has been made and the object needs to now reflect those configuration settings. There is a specific method for the post ecard site adjustment and a general method for all other cases.

Once an ecard site is selected, use the set_site_conf method to update the essential parameters. It expects 4 parameters: the Penguin Greetings configuration object (for that site,) the card configuration object, and the URL get parameter and URL post hidden fields needed to "back up" via a new CGI request. The call look like:

# Set card site specific configuration
$Pg_cgi->set_site_conf($Pg_config, $card_conf, $BackVarStr,
                       $BackHiddenFields
                      );

As the CGI Application is run, it may create other values that must be passed to Embperl. To set these values generally, use the set_value method. It takes two parameters: the name of the value to set and the value to assign to it. These values are simply added to the hash associated with the Pgreet::CGIUtils object. So it is possible to reset anything. Thus documented, it becomes a feature and programmers are thus warned. An example call is provided below:

$Pg_cgi->set_value('error_hash', $error_hash);

CGI UTILITY METHODS

The utility functions that can be used from Pgreet::CGIUtils are listed below.

ChangeVars()

This is the method that creates a transfer hash to pass on to Embperl. It takes no parameters and instead provides a "snapshot" of the current state of the CGI application at the time of its invocation. A sample call is provided below:

# Create Transfer hash for Embperl
my $Transfer = $Pg_cgi->ChangeVars();

COPYRIGHT

Copyright (c) 2003, 2004 Edouard Lagache

This software is released under the GNU General Public License, Version 2. For more information, see the COPYING file included with this software or visit: http://www.gnu.org/copyleft/gpl.html

BUGS

No known bugs at this time.

AUTHOR

Edouard Lagache <pgreetdev@canebas.org>

VERSION

0.9.5

SEE ALSO

syslog, Pgreet, Pgreet::Config, Pgreet::Error, Log::Dispatch, Log::Dispatch::File, Log::Dispatch::Syslog, CGI::Carp