Pgreet::CGIUtils - Penguin Greetings shared routines for CGI functions.
# 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,
);
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.
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.
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);
The utility functions that can be used from
Pgreet::CGIUtils are listed below.
ChangeVars()# Create Transfer hash for Embperl my $Transfer = $Pg_cgi->ChangeVars();
is_bypass()
# 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()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()
# Execute the Mason template file: $file
$result_str = $Pg_cgi->Mason_Execute($templatedir, $file,
$Transfer,
$Mason_Object,
);
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
No known bugs at this time.
Edouard Lagache <pgreetdev@canebas.org>
1.0.0
Pgreet, the Pgreet::Config manpage, the Pgreet::Error manpage, the Pgreet::ExecEmbperl manpage, the Pgreet::ExecMason manpage, the CGI::Carp manpage