PgTemplateTest - Test Penguin Greetings Embperl templates
PgTemplateTest [-b] \
[-c .../pgreet.conf] \
[-d] \
[-p .../cards.conf] \
[-s Secondary_site_name] \
[-t .../PgTemplateTest.conf] \
[-x]
template.tpl.html var1=value1 var2=value2 ...
PgTemplateTest is a utility for development of
Embperl or HTML::Mason based templates for the Penguin
Greetings web-based greeting cards system. It can be used to
test a template page for correct Embperl or Mason syntax and
for correct appearance given particular parameters. It can
launch your favorite browser so that the page under development
can be viewed under realistic conditions. It can also be used
to dump the state of transfer variables to a given template
page.
PgTemplateTest requires the standard Penguin
Greeting environment in order to function. In order to take
advantage of the lookup features of the
Pgreet::Config module that is used by
PgTemplateTest. While this chore is now handled by
Install.PL, You may have to adjust the global variable:
$pgreet_conf_file to point to the configuration
file of your primary Penguin Greetings installation.
PgTemplateTest can then locate the configuration
files of secondary site using the built-in strategies.
PgTemplateTest now uses a configuration file
based on the same Config::General format used
elsewhere in Penguin Greetings. There are two sorts of
configuration items. There are a few items required for
PgTemplateTest itself. Those are:
browser = the path to the browser you wish to use
to display pages, prefix = the prefix needed to
view a file in that browser, suffix = the suffix
needed to view a file (if a more complex browser startup
procedure is needed), tmp_path = the path where
temporary files should be stored by
PgTemplateTest, and purge_after the
number of days after which a temporary file created
PgTemplateTest will be purged by the -x
command.
Then there is a secondary list of dummy CGI state variables
to populate the pages being rendered. This can contain any CGI
state variables that your template may encounter. See the
sample PgTemplateTest.conf file included with
Penguin Greetings for more details.
PgTemplateTest performs three tasks. When used
with the -d option it can be used to display all
the state variables passed to a template page. The main
application is that it can be used to process a given template
with Embperl or Mason and view the resulting pure HTML. In
order to allow the developer to set the value of state
variables that are unique to their pages, variable, value pairs
can be passed to the program separated by an equals sign
=. So for example, to process the file
MyTemplate.tpl.html with the variable
penguin equal to 5 and the variable
camel equal to 2_hump the command
would be:
PgTemplateTest MyTemplate.tpl.html penguin=5 camel=2_hump
Variables or values should be quotes as necessary to avoid
being misinterpreted by your command shell. Normally,
PgTemplateTest displays the dumped variables or
the resulting HTML to standard out. If you use the
-b option, it will instead save the rendered HTML
to a temporary file and launch a browser so that you may view
the resulting page. The final housekeeping role of
PgTemplateTest is to remove the temporary HTML
files created by the -b option. This can be done
with -x option. There are 6 command line options
explained below:
-b = Render the template into an HTML page,
save as a temporary file, and launch a browser to view the
resulting page. In order for this to work you must set the
configuation file variables: browser,
prefix, tmp_path, and
suffix to appropriate values for your system.
Unfortunately, it can be difficult to find a single set of
browsing launching configuration parameters that will provide
the desired results. Penguin Greetings is shipped with settings
to connect to an existing Mozilla process and create a new tab
for the resulting page. This appears to be a ``comfortable''
compromise, but requires that a version of Mozilla be already
launched before PgTemplateTest is used.
-c path_to/cards.conf = Use the specified file
instead of the default file for the Penguin Greetings
cards.conf card configuration file.
-d = Do not render any template page, just dump
what the state variables for this arrangement would be. The -d
option will ignore any template filename and process only
command line arguments with embedded equals signs as additional
state variables.
-p path_to/pgreet.conf = Use the specified file
instead of the default file for the Penguin Greetings
pgreet.conf general configuration file.
-s secondary_site_name = render the page using
the default configuration files for the site
secondary_site_name.
-t path_to/PgTemplateTest.conf = use the
specified file instead of the default file stored in the same
directory as the other primary configuration files for Penguin
Greetings.
-x = Purge any temporary HTML files that are
older than the configuration variable purge_after.
Nothing else is done if -x and it provides no
output whatsoever,so it can be placed in a cron job to remove
files from all users. When not used as root, it will silently
only remove files that you have permission to delete.
The PgTemplateTest utility uses the
configuration information of a site under development to
determine if Object-oriented features are being employed (and
for that matter if this an Embperl or HTML::Mason site being
tested.) Testing an sort of complex site will require that you
provide a testing environment that includes the configuration
files and autohandlers or Embperl Equivalents.
PgTemplateTest uses a shared interface to
Embperl and HTML::Mason as the CGI application (found in
Pgreet::CGIUtils and related modules,) so that resulting
rendering of the Embedded Perl templates should be identical to
what the CGI application produces for the same set of state
variables.
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
There is no systemic mechanism to clean up the temp files
created in the -b option. Users must either
explicitly use the -x option, or a cron job should
be set up using -x. The latter is probably
advisable on systems with many users and/or limited disk
resources.
When using the -d option, no template file
should be specified. This is because there is no rendering
needed when dumping the state variables. While this is a user
interface inconsistency, it seemed more prudent to respect the
programmers need for laziness than consistency! :-)
Edouard Lagache <pgreetdev@canebas.org>
1.0.0