/ 
Pgreet-1.0.0
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();

# Test if file $Embperl_file is excluded from object-oriented
# Embperl interpretation:
if ( $Pg_cgi->is_bypass($Embperl_file,
                        $Embperl_Object->{'bypass_object'})
   ) { }

# Execute the Embperl template file: $file in an object-oriented
# environment
$result_str = $Pg_cgi->Embperl_Execute($templatedir, $file,
                                       $Transfer,
                                       $Embperl_Object
                                       );

# Execute the Mason template file: $file
$result_str = $Pg_cgi->Mason_Execute($templatedir, $file,
                                     $Transfer,
                                     $Mason_Object,
                                    );

DESCRIPTION

The module Pgreet::CGIUtils is the Penguin Greetings module for any routines that must be shared between the CGI application and other modules. This includes the creation of a hash of values to be transferred from Penguin Greetings to Embperl for processing of templates and providing a uniform interface between Penguin Greetngs and Embedded Perl Enviroments (Embperl and HTML::Mason.)

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/Mason, 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();
is_bypass()

This method tests if a template file is on a list of templates to be excluded from object-oriented processing (typically text-only email messages.) It is used in the methods that prep calls to either Embperl or Mason but could be of use outside. A sample call would be as follows (assuming an Embperl Object configuration setting:)

# Test if file $Embperl_file is excluded from object-oriented
# Embperl interpretation:
if ( $Pg_cgi->is_bypass($Embperl_file,
                        $Embperl_Object->{'bypass_object'})
   ) { }
Embperl_Execute()

This function provides a uniform interface for Penguin Greetings to the Embperl Perl within HTML environment. The same function is used within PgTemplateTest and pgreet.pl.cgi. It also provides the abstraction that allows for Embperl to be 'autoused' as needed at runtime. It requires 3 to 4 arguments: the directory where templates are stored, the filename of the template to execute, a $Transfer styled hash-ref of parameters to the template and if appropriate the Embperl_Object configuration hash-ref. The method call returns a string containing the rendered HTML from the template.A sample call is shown below:

# Execute the Embperl template file: $file in an object-oriented
# environment
$result_str = $Pg_cgi->Embperl_Execute($templatedir, $file,
                                       $Transfer,
                                       $Embperl_Object
                                      );
Mason_Execute()

This function provides for the HTML::Mason environment the same uniform interface that Embperl_Execute provides for Embperl. It takes the same arguments and returns the rendered HTML as a string. A sample call is shown below:

# Execute the Mason template file: $file
$result_str = $Pg_cgi->Mason_Execute($templatedir, $file,
                                     $Transfer,
                                     $Mason_Object,
                                    );

COPYRIGHT

Copyright (c) 2003-2005 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

1.0.0

SEE ALSO

Pgreet, Pgreet::Config, Pgreet::Error, Pgreet::ExecEmbperl, Pgreet::ExecMason, CGI::Carp