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 command line options
are as follows:
Option
|
Description
|
-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 variables:
$browser, $prefix, $suffix, and
$tmp_path to appropriate values for your
system. |
-c
|
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
|
Use the specified
file instead of the default file for the Penguin
Greetings pgreet.conf general configuration
file. |
-s
|
Load the
configuration information of the secondary site SiteName instead
of the primary site. This can be used to test a
secondary site using the same configuration file
conventions used by the application itself.
|
-t
|
Use the specified
file instead of the default file for the PgTemplateTest
configuration file.
|
-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. |
PgTemplateTest can be used in multiple ways. To
simply test the syntax of the Embperl, standard output can
be sent to /dev/null:
PgTemplateTest MyTemplate.tpl.html > /dev/null
Embperl will send error messages to standard error with
line numbers for the offending statements (if any.)
To actually look at the resulting HTML, pipe the output
into a file for your inspection. If you want to
actually look at the resulting page, use the
-b option:
PgTemplateTest -b MyTemplate.tpl.html penguin=5 camel=2_hump
This will create a temporary file in
$tmp_path and then launch
your browser to render the page. There is one
unfortunate "bad habit" in the browser rendering
mode. Since there is no obvious way of knowing when
you will be finished with a given temporary file, there is
no strategy for deleting them. Therefore you must
"clean up" your
$tmp_path directory from
time to time (by using the
-x option or manually) to
avoid clutter.
Since
PgTemplateTest uses the
identical configuration files that
Penguin Greetings uses,
you should see your template in the same configuration as
it would be seen by a user. By changing the variables
passed to
PgTemplateTest as command
line arguments, you can simulate any condition your
template would encounter on the "live site." This
tool can be used to validate all aspects of a template from
raw syntax to the aesthetics of the resulting web
page. For more information on
PgTemplateTest, see the
PgTemplateTest man
page.
Unfortunately, Mozilla version 1.5 no longer automatically
finds any existing processes when you attempt to launch
another copy. Version 0.9.2 of Penguin
Greetings uses instead the
-remote feature of Mozilla
to connect to an existing process. This requires
however that Mozilla be already running. So if you
intend to use the
-b option of
PgTemplateTest with
Mozilla, make sure to first launch Mozilla before
proceeding. The default configuration creates the
page in a new tab of Mozilla. If you would prefer
something else, edit the prefix and suffix configuration
variables accordingly. For more information on the
Mozilla
remote
feature see the
Mozilla
documentation page on remote.
Consistent with version 0.9.7 of
Penguin Greetings,
PgTemplateTest can
be used to test templates used in an object-oriented web
site. Simply specify the site of the web site being
tested, if necessary, using the
-s option. There is
a shared Perl module (
Pgreet::CGIUtils) that
provides the interface between both
PgTemplateTest and CGI
application and Embperl. So you will get the same
rendering using
PgTemplateTest as will
occur when your web site is
live. As one would
expect, as of version 0.9.9 of
Penguin Greetings, you can
use
PgTemplateTest to render
templates in
HTML::Mason just as the
CGI application does (see below.)
Creating secondary ecard
sites
New to version 0.8.8 is the ability to have secondary
ecard sites that are serviced by the same
CGI-Application/daemon pair. Secondary ecard sites
are handled identically as almost all respects so that
there is nothing special to be done in creating a secondary
site that is different from a primary site. As noted
in the
Penguin Greetings Installation
Guide, secondary ecard sites need the same organization
as a primary site. They need a configuration, data,
and HTML directory. They could be put together or
separately.
It is probably best to try to set up the organization and
rough out at least a prototype card configuration file so
that you can use
PgTemplateTest to test
templates easily and in as realistic conditions as
possible. Secondary ecard sites must be added to the
primary
pgreet.conf file (in the
field
User_Pgreets) before
PgTemplateTest will
be able to find the configuration information for the
secondary sites.
Note that secondary ecard sites need to have their own
templates to handle general errors and CGI field errors (
see above.) If users wish
to use the same error handling templates as come with the
primary site, they should create symbolic links in the
templates directory of the secondary site. See the
section above on
object-oriented
ecard sites for example secondary ecard site templates
or examine any of the six secondary ecard sites that come
with Penguin Greetings for more information. The one
site that illustrates a secondary site features without
localization issues is the
Camel Collection (
PgCamel.)
Localizing ecard sites in Penguin
Greetings
New to version 0.9.5 of
Penguin Greetings is
support for localization/Internationalization.
Penguin Greetings
does this by providing a separate site for each language
and nation to be supported. These sites, like all
secondary ecard sites, need have nothing in common.
However, it is recommended that links be provided to the
ecard sites in other languages. An example below is
provided from the
PgSaint!en-us site:
[#
######################################################
#]
[#
Penguin Greetings Holy ecard
website
#]
[#
#]
[# For more
information on Penguin Greetings project go:
#]
[#
http://pgreet.sourceforge.net/
#]
[#
#]
[# File:
default.tpl.html - Template for display of card
#]
[#
image
thumbnails.
#]
[#
######################################################
#]
<html>
<head>
<title>Penguin Greetings - Holy ecard
collection</title>
</head>
[*
$ENV{'optRawInput'} = 16; *]
[*
$escmode = 0; *]
[$ var
$trans $script_URL %card_hash @cards_list $card
$sample_URL
$text_URL %card_data $lang_URL
$]
[-
#
Retrieve parameters from Penguin Greetings script
(pgreet.pl.cgi)
$trans = shift(@param);
%card_hash = %{$trans->{'card_hash'}};
%card_data = %{$card_hash{'card'}};
@cards_list = @{$card_hash{'cards'}};
#
Build up pieces of URLs to simplify
represention.
$script_URL = join('', $trans->{'cgiurl'},
"/",
$trans->{'cgi_script'},
"?action=build&",
$trans->{'varstring'}, '&'
);
$lang_URL = join('', $trans->{'cgiurl'},
"/",
$trans->{'cgi_script'}, "?site="
);
$sample_URL = $script_URL .
"next_template=sample_view";
$text_URL = $script_URL .
"next_template=text";
-]
<body
style="background-image:
url([+
$trans->{'imageurl'}
+]/PgSaints_wallpaper.jpg);">
<center>
<table
cellpadding="0" cellspacing="0" border="0"
style="text-align:
left; width: 630px;">
<tbody>
<tr>
<td style="vertical-align: top; text-align:
center;" colspan="3"><img
src="[+ $trans->{'imageurl'}
+]/PgSaints_upper_banner.gif" title=""
alt=""
style="width: 642px;
height: 38px;"><br>
<img src="[+
$trans->{'imageurl'}
+]/PgSaints_middle_banner.gif" title=""
alt=""
style="width: 641px;
height: 73px;"> </td>
</tr>
<tr>
<td
style="vertical-align:
top; background-color: rgb(0, 0, 0); width: 2px;">
<br>
</td>
<td style="vertical-align: top;">
<div style="text-align: center;">
</div>
<table cellpadding="2" cellspacing="2"
border="0"
style="text-align:
left; width: 100%;">
<tbody>
<tr>
<td style="vertical-align: top; text-align:
center;">
<!-- Links to alternative language site
-->
<a href="[+
$lang_URL +]PgSaint!en-us">
<img
src="[+
$trans->{'imageurl'}
+]/US_flag.jpg"
title="[English-US site]"
alt="[English-US site]" align="left"
style="width: 39px; height: 24px;"
border="0">
</a>
<a href="[+
$lang_URL +]PgSaint!fr-fr">
<img
src="[+
$trans->{'imageurl'}
+]/French_flag.jpg"
title="[French-France Site]"
alt="[French-France Site]" align="right"
style="width: 39px; height: 24px;"
border="0">
</a>
|
Note that in the above example the links are to the
complete alternative site (e.g.
PgSaint!fr-fr.) This
insures that localization information is bypassed.
The option to switch sites should only be provided at the
start of an ecard site to avoid confusion. Users
cannot start an ecard in one language and finish it in
another (obviously.) For more information on
configuring Penguin Greetings to support multiple languages
see the
Penguin Greetings
Administrators' guide.
Simple websites with only only a small number of
translations may find it simplest to "hand code" the text
for each language in separate template files. An
example of this is provided in the
Holy ecard collection (
PgSaint.) So
long as there are not multiple sites or many languages to
support, the overhead of additional software management of
localization may not be worth it. Beyond such simple
arrangements, explicit software support of localization has
clear benefits.
Penguin Greetings does not
provide any internal support for any particular
localization management scheme since the very nature of an
Embedded Perl environment allows developers to easily
include one of their own choosing. As an example of
one possible choice, version 0.9.9 of Penguin Greetings
uses the module
Locale::Maketext
module which is now standard with recent versions of Perl
5.8.x. Four of the five localized sites now use
Locale::Maketext.
What follows is a brief description of how to use this
particular scheme for localization, but it will be of
interest to anyone that needs to localize ecard sites.
The
Locale::Maketext
localization scheme relies on Perl object
inheritance. For the Penguin Greetings demonstration
sites, a new instance of the module
Locale::Maketext was
created in Penguin Greetings library module:
Pgreet::I18N and
associated translation files. One of the great
advantages of the
Locale::Maketext approach
to localization is that it makes available the full power
of Perl in the presentation of the translation
information. For the sake of simplicity and
transparency, Penguin Greetings leaves the translated
strings in a simple hash. Anyone seeking to use
Locale::Maketext for
localization will need to create their own equivalents of
Pgreet::I18N. Please
see the
Locale::Maketext
module documentation and the sample application using that
translation scheme
File::Findgrep.
The
Locale::Maketext module is
implemented based on an idea that the project uses one
default language. This has the powerful advantage
that the text strings in one language can be used as the
keys for the translated strings in other languages.
When used in Penguin Greetings, it means that the templates
in the project language (English) will work correctly in
any other language, so the templates in alternative
language(s) (in this case French) have been replaced with
symbolic links to the English templates. Any template
using this localization scheme needs to include the
translation modules and use the translation method
maketext. An
example of this is shown in the snippet from the California
Poppy site (
PgPoppy)
Text_email.tpl.html
template seen below:
.
.
.
[#
Embperl Variables #]
[$ var
$trans $LN $]
[-
#
Retrieve parameters from Penguin Greetings script
(pgreet.pl.cgi)
$trans = shift(@param);
use Pgreet::I18N;
$LN =
Pgreet::I18N->get_handle($trans->{'lang_code'});
-]
[+
$LN->maketext("Dear
[_1],",$trans->{'recipient_name'}) +]
.
.
.
|
The
Locale::Maketext module
uses a concept of language handles (
$LN) that incorporates the
normal process of object construction. So once one
uses the particular instance of
Locale::Maketext (in this
case
Pgreet::I18N,) then one
creates the language handle. This requires an
argument which is the language code for the site at the
moment of calling. As noted above, this is included
in the transfer hash under the key
lang_code. Once one
has a language handle, one can go ahead and display text
using the
maketext method. The
snippet above is a case where the translated text takes an
argument (in this case the recipient's name.) See the
Locale::Maketext
documentation for details on this feature. Since
there are some idiosyncrasies associated with using
Locale::Maketext
with Mason (versus Embperl) and in HTML templates versus
plain text templates (as above,) Please see any of the four
secondary ecard sites using
Locale::Maketext (
PgXmas,
PgPoppy,
Pg4Seasons, or
PgSeattle) for
details on how to implement
internationalization/localization using this Perl
facility.
). However, even the most
un-artistic sys-admin will sooner or later want to add some
cards of their own to their system. Those with more
ambitious plans will find a simple example a good point of
departure.
