.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Petal 3pm"
.TH Petal 3pm "2011-08-29" "perl v5.12.4" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Petal \- Perl Template Attribute Language \- TAL for Perl!
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
in your Perl code:
.PP
.Vb 3
\& use Petal;
\& my $template = new Petal (\*(Aqfoo.xhtml\*(Aq);
\& print $template\->process (bar => \*(AqBAZ\*(Aq);
.Ve
.PP
in foo.xhtml
.PP
.Vb 3
\&
\&
Dummy Content
\&
.Ve
.PP
and you get something like:
.PP
.Vb 3
\&
\& BAZ
\&
.Ve
.SH "SUMMARY"
.IX Header "SUMMARY"
Petal is a \s-1XML\s0 based templating engine that is able to process any
kind of \s-1XML\s0, \s-1XHTML\s0 and \s-1HTML\s0.
.PP
Petal borrows a lot of good ideas from the Zope Page Templates \s-1TAL\s0
specification, it is very well suited for the creation of \s-1WYSIWYG\s0 \s-1XHTML\s0
editable templates.
.PP
The idea is to further enforce the separation of logic from presentation. With
Petal, graphic designers can use their favorite \s-1WYSIWYG\s0 editor to easily edit
templates without having to worry about the loops and ifs which happen behind
the scene.
.SH "NAMESPACE"
.IX Header "NAMESPACE"
Although this is not mandatory, Petal templates should include use the namespace
. Example:
.PP
.Vb 4
\&
\&
\& Blah blah blah...
\& Content of the file
\& More blah blah...
\&
.Ve
.PP
If you do not specify the namespace, Petal will by default try to use the
\&\f(CW\*(C`petal:\*(C'\fR prefix. However, in all the examples of this \s-1POD\s0 we'll use the
\&\f(CW\*(C`tal:\*(C'\fR prefix to avoid too much typing.
.SH "KICKSTART"
.IX Header "KICKSTART"
Let's say you have the following Perl code:
.PP
.Vb 2
\& use Petal;
\& local $Petal::OUTPUT = \*(AqXHTML\*(Aq;
\&
\& my $template = new Petal (\*(Aqfoo.xhtml\*(Aq);
\& $template\->process ( my_var => some_object() );
.Ve
.PP
\&\fIsome_object()\fR is a subroutine that returns some kind of object, may it be a scalar,
object, array referebce or hash reference. Let's see what we can do...
.SS "Version 1: \s-1WYSIWYG\s0 friendly prototype."
.IX Subsection "Version 1: WYSIWYG friendly prototype."
Using \s-1TAL\s0 you can do:
.PP
.Vb 2
\& This is the variable \*(Aqmy_var\*(Aq :
\& Hola, Mundo!
.Ve
.PP
Now you can open your template in any \s-1WYSIWYG\s0 tool (mozilla composer,
frontpage, dreamweaver, adobe golive...) and work with less risk of damaging
your petal commands.
.SS "Version 2: Object-oriented version"
.IX Subsection "Version 2: Object-oriented version"
Let's now say that \f(CW\*(C`my_var\*(C'\fR is actually an object with a method \fIhello_world()\fR
that returns \fIHello World\fR. To output the same result, your line, which was:
.PP
.Vb 1
\& Hola, Mundo!
.Ve
.PP
Would need to be... \s-1EXACTLY\s0 the same. Petal lets you access hashes and objects
in an entirely transparent way and tries to automagically do The Right Thing
for you.
.PP
This high level of polymorphism means that in most cases you can maintain your
code, swap hashes for objects, and not change a single line of your template
code.
.SS "Version 3: Personalizable"
.IX Subsection "Version 3: Personalizable"
Now let's say that your method \fIhello_world()\fR can take an optional
argument so that \f(CW\*(C`$some_object\->hello_world (\*(AqJack\*(Aq)\*(C'\fR returns \fIHello Jack\fR.
.PP
You would write:
.PP
.Vb 1
\& Hola, Mundo!
.Ve
.PP
Optionally, you can get rid of the quotes by using two dashes, a la \s-1GNU\s0
command-line option:
.PP
.Vb 1
\& Hola, Mundo!
.Ve
.PP
So you can pass parameters to methods using double dashes or quotes.
Now let us say that your \f(CW\*(C`my_var\*(C'\fR object also has a method \fIcurrent_user()\fR
that returns the current user real name. You can do:
.PP
.Vb 1
\& Hola, Mundo!
.Ve
.PP
\&\s-1TRAP:\s0
.PP
You cannot write nested expressions such as:
.PP
.Vb 1
\& ${my_var/hello_world ${my_var/current_user}}
.Ve
.PP
This will \s-1NOT\s0 work. At least, not yet.
.SS "Version 4: Internationalized"
.IX Subsection "Version 4: Internationalized"
Let's say that you have a directory called \f(CW\*(C`hello_world\*(C'\fR with the following
files:
.PP
.Vb 3
\& hello_world/en.xhtml
\& hello_world/fr.xhtml
\& hello_world/es.xhtml
.Ve
.PP
You can use Petal as follows in your Perl code:
.PP
.Vb 2
\& use Petal;
\& local $Petal::OUTPUT = \*(AqXHTML\*(Aq;
\&
\& my $template = new Petal ( file => \*(Aqhello_world\*(Aq, lang => \*(Aqfr\-CA\*(Aq );
\& print $template\->process ( my_var => some_object() );
.Ve
.PP
What will happen is that the \f(CW$template\fR object will look in the
\&\f(CW\*(C`hello_world\*(C'\fR directory and try to find a file named \f(CW\*(C`fr\-CA.xhtml\*(C'\fR, then
\&\f(CW\*(C`fr.xhtml\*(C'\fR, then will default to \f(CW\*(C`en.xhtml\*(C'\fR. It works fine for includes, too!
.PP
These internationalized templates can have whatever file-extension you like,
Petal searches on the first part of the filename. So you can call them
\&\f(CW\*(C`fr.html\*(C'\fR, \f(CW\*(C`fr.xml\*(C'\fR, \f(CW\*(C`fr.xhtml\*(C'\fR or use whatever convention suits you.
.PP
\&\s-1NOTE:\s0 There is now support for ZPT-like i18n attributes, which should
provide a much nicer framework. See Petal::I18N for details.
.PP
\&\s-1TIP:\s0
.PP
If you feel that 'en' should not be the default language, you can specify a
different default:
.PP
.Vb 5
\& my $template = new Petal (
\& file => \*(Aqhello_world\*(Aq,
\& language => \*(Aqzh\*(Aq,
\& default_language => \*(Aqfr\*(Aq # vive la France!
\& );
.Ve
.PP
\&\s-1TRAP:\s0
.PP
If you do specify the \f(CW\*(C`lang\*(C'\fR option, you \s-1MUST\s0 use a path to a template
directory, not a file directory.
.PP
Conversely, if you do not specify a \f(CW\*(C`lang\*(C'\fR option, you \s-1MUST\s0 use a path to a
template file, not a directory.
.SH "OPTIONS"
.IX Header "OPTIONS"
When you create a Petal template object you can specify various options using
name => value pairs as arguments to the constructor. For example:
.PP
.Vb 6
\& my $template = Petal\->new(
\& file => \*(Aqgerbils.html\*(Aq,
\& base_dir => \*(Aq/var/www/petshop\*(Aq,
\& input => \*(AqHTML\*(Aq,
\& output => \*(AqHTML\*(Aq,
\& );
.Ve
.PP
The recognized options are:
.SS "file => \fIfilename\fP"
.IX Subsection "file => filename"
The template filename. This option is mandatory and has no default.
.PP
Note: If you also use 'language' this option should point to a directory.
.SS "base_dir => \fIpathname\fP | [ \fIpathname list\fP ] (default: '.')"
.IX Subsection "base_dir => pathname | [ pathname list ] (default: '.')"
The directories listed in this option will be searched in turn to locate the
template file. A single directory can be specified as a scalar. For a
directory list use an arrayref.
.SS "input => '\s-1HTML\s0' | '\s-1XHTML\s0' | '\s-1XML\s0' (default: '\s-1XML\s0')"
.IX Subsection "input => 'HTML' | 'XHTML' | 'XML' (default: 'XML')"
Defines the format of the template files. Recognised values are:
.PP
.Vb 3
\& \*(AqHTML\*(Aq \- Alias for \*(AqXHTML\*(Aq
\& \*(AqXHTML\*(Aq \- Petal will use Petal::Parser to parse the template
\& \*(AqXML\*(Aq \- Petal will use Petal::Parser to parse the template
.Ve
.SS "output => '\s-1HTML\s0' | '\s-1XHTML\s0' | '\s-1XML\s0' (default: '\s-1XML\s0')"
.IX Subsection "output => 'HTML' | 'XHTML' | 'XML' (default: 'XML')"
Defines the format of the data generated as a result of processing the template
files. Recognised values are:
.PP
.Vb 3
\& \*(AqHTML\*(Aq \- Petal will output XHTML, self\-closing certain tags
\& \*(AqXHTML\*(Aq \- Alias for \*(AqHTML\*(Aq
\& \*(AqXML\*(Aq \- Petal will output generic XML
.Ve
.SS "language => \fIlanguage code\fP"
.IX Subsection "language => language code"
For internationalized applications, you can use the 'file' option to point to a
\&\fIdirectory\fR and select a language-specific template within that directory
using the 'language' option. Languages are selected using a two letter code
(eg: 'fr') optionally followed by a hyphen and a two letter country code (eg:
\&'fr\-CA').
.SS "default_language => \fIlanguage code\fP (default: 'en')"
.IX Subsection "default_language => language code (default: 'en')"
This language code will be used if no template matches the selected
language-country or language.
.SS "taint => \fItrue\fP | \fIfalse\fP (default: \fIfalse\fP)"
.IX Subsection "taint => true | false (default: false)"
If set to \f(CW\*(C`true\*(C'\fR, makes perl taint mode happy.
.SS "error_on_undef_var => \fItrue\fP | \fIfalse\fP (default: \fItrue\fP)"
.IX Subsection "error_on_undef_var => true | false (default: true)"
If set to \f(CW\*(C`true\*(C'\fR, Petal will \fIconfess()\fR errors when trying to access undefined
template variables, otherwise an empty string will be returned.
.SS "disk_cache => \fItrue\fP | \fIfalse\fP (default: \fItrue\fP)"
.IX Subsection "disk_cache => true | false (default: true)"
If set to \f(CW\*(C`false\*(C'\fR, Petal will not use the \f(CW\*(C`Petal::Cache::Disk\*(C'\fR module.
.SS "memory_cache => \fItrue\fP | \fIfalse\fP (default: \fItrue\fP)"
.IX Subsection "memory_cache => true | false (default: true)"
If set to \f(CW\*(C`false\*(C'\fR, Petal will not use the \f(CW\*(C`Petal::Cache::Memory\*(C'\fR module.
.SS "cache_only => \fItrue\fP | \fIfalse\fP (default: \fIfalse\fP)"
.IX Subsection "cache_only => true | false (default: false)"
If set to \f(CW\*(C`true\*(C'\fR, Petal will return true after having compiled a template into
perl code and a subroutine , and optionally using disk_cache or memory_cache if
either is set.
.SS "max_includes => \fInumber\fP (default: 30)"
.IX Subsection "max_includes => number (default: 30)"
The maximum number of recursive includes before Petal stops processing. This
is to guard against accidental infinite recursions.
.SS "debug_dump => \fItrue\fP | \fIfalse\fP (default: \fItrue\fP)"
.IX Subsection "debug_dump => true | false (default: true)"
If this option is true, when Petal cannot process a template it will
output lots of debugging information in a temporary file which you can
inspect. The location for this file is wherever File::Spec\->\fItmpdir()\fR
specifies as a temp directory (usually /tmp on a unix system).
.SS "encode_charset => \fIcharset\fP (default: undef)"
.IX Subsection "encode_charset => charset (default: undef)"
This option is _DEPRECATED_ as of Petal 2.01.
Petal will now always return results in Perl's internal form.
.PP
It doesn't guarantee that the result will be in \s-1UTF\-8\s0 or in your
local encoding, but at least the \s-1UTF\-8\s0 flag should be set properly.
.PP
If you want to encode the results for a specific charset, you
should look at the module Encode.
.SS "decode_charset => \fIcharset\fP (default: undef)"
.IX Subsection "decode_charset => charset (default: undef)"
This option will work only if you use Perl 5.8 or greater.
.PP
If specified, Petal will assume that the template to be processed (and its
sub-templates) are in the character set \fIcharset\fR.
.PP
\&\fIcharset\fR can be any character set that can be used with the module Encode.
.SH "TAL SYNTAX"
.IX Header "TAL SYNTAX"
This functionality is directly and shamelessly stolen from the excellent \s-1TAL\s0
specification: .
.SS "define"
.IX Subsection "define"
Abstract
.PP
.Vb 1
\&
.Ve
.PP
Evaluates \f(CW\*(C`EXPRESSION\*(C'\fR and assigns the returned value to \f(CW\*(C`variable_name\*(C'\fR.
.PP
Example
.PP
.Vb 2
\&
\&
.Ve
.PP
Why?
.PP
This can be useful if you have a \f(CW\*(C`very/very/long/expression\*(C'\fR. You can set it
to let's say \f(CW\*(C`vvle\*(C'\fR and then use \f(CW\*(C`vvle\*(C'\fR instead of using
\&\f(CW\*(C`very/very/long/expression\*(C'\fR.
.SS "condition (ifs)"
.IX Subsection "condition (ifs)"
Abstract
.PP
.Vb 3
\&
\& blah blah blah
\&
.Ve
.PP
Example
.PP
.Vb 3
\&
\& Yo, authenticated!
\&
.Ve
.PP
Why?
.PP
Conditions can be used to display something if an expression
is true. They can also be used to check that a list exists
before attempting to loop through it.
.SS "repeat (loops)"
.IX Subsection "repeat (loops)"
Abstract
.PP
.Vb 3
\&
\& blah blah blah
\&
.Ve
.PP
Why?
.PP
Repeat statements are used to loop through a list of values,
typically to display the resulting records of a database query.
.PP
Example:
.PP
.Vb 1
\&
$user/real_name
.Ve
.PP
A select list with one item selected:
.PP
.Vb 10
\&
.Ve
.PP
A table with rows of alternating colours set via \s-1CSS:\s0
.PP
.Vb 10
\&
\&
\&
\&
\& This a odd row, it comes before the even row.
\&
\&
\&
.Ve
.SH "EXPRESSIONS AND MODIFIERS"
.IX Header "EXPRESSIONS AND MODIFIERS"
Petal has the ability to bind template variables to the following Perl
datatypes: scalars, lists, hash, arrays and objects. The article describes
the syntax which is used to access these from Petal templates.
.PP
In the following examples, we'll assume that the template is used as follows:
.PP
.Vb 3
\& my $hashref = some_complex_data_structure();
\& my $template = new Petal (\*(Aqfoo.xml\*(Aq);
\& print $template\->process ( $hashref );
.Ve
.PP
Then we will show how the Petal Expression Syntax maps to the Perl way of
accessing these values.
.SS "accessing scalar values"
.IX Subsection "accessing scalar values"
Perl expression
.PP
.Vb 1
\& $hashref\->{\*(Aqsome_value\*(Aq};
.Ve
.PP
Petal expression
.PP
.Vb 1
\& some_value
.Ve
.PP
Example
.PP
.Vb 4
\& {\*(Aqsome_value\*(Aq}
\& \-\->
\& Hello, World
.Ve
.SS "accessing hashes & arrays"
.IX Subsection "accessing hashes & arrays"
Perl expression
.PP
.Vb 1
\& $hashref\->{\*(Aqsome_hash\*(Aq}\->{\*(Aqa_key\*(Aq};
.Ve
.PP
Petal expression
.PP
.Vb 1
\& some_hash/a_key
.Ve
.PP
Example
.PP
.Vb 4
\& {\*(Aqsome_hash\*(Aq}\->{\*(Aqa_key\*(Aq}
\& \-\->
\& Hello, World
.Ve
.PP
Perl expression
.PP
.Vb 1
\& $hashref\->{\*(Aqsome_array\*(Aq}\->[12]
.Ve
.PP
Petal expression
.PP
.Vb 1
\& some_array/12
.Ve
.PP
Example
.PP
.Vb 4
\& {\*(Aqsome_array\*(Aq}\->[12]
\& \-\->
\& Hello, World
.Ve
.PP
Note: You're more likely to want to loop through arrays:
.PP
.Vb 5
\&
\&
\&
Hello, World
\&
.Ve
.SS "accessing object methods"
.IX Subsection "accessing object methods"
Perl expressions
.PP
.Vb 3
\& 1. $hashref\->{\*(Aqsome_object\*(Aq}\->some_method();
\& 2. $hashref\->{\*(Aqsome_object\*(Aq}\->some_method (\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq);
\& 3. $hashref\->{\*(Aqsome_object\*(Aq}\->some_method ($hashref\->{\*(Aqsome_variable\*(Aq})
.Ve
.PP
Petal expressions
.PP
.Vb 5
\& 1. some_object/some_method
\& 2a. some_object/some_method \*(Aqfoo\*(Aq \*(Aqbar\*(Aq
\& 2b. some_object/some_method "foo" "bar"
\& 2c. some_object/some_method \-\-foo \-\-bar
\& 3. some_object/some_method some_variable
.Ve
.PP
Note that the syntax as described in 2c works only if you use strings
which do not contain spaces.
.PP
Example
.PP
.Vb 5
\&
\& 2 times
\& 2 equals
\& 4
\&
.Ve
.SS "composing"
.IX Subsection "composing"
Petal lets you traverse any data structure, i.e.
.PP
Perl expression
.PP
.Vb 4
\& $hashref\->{\*(Aqsome_object\*(Aq}
\& \->some_method()
\& \->{\*(Aqkey2\*(Aq}
\& \->some_other_method ( \*(Aqfoo\*(Aq, $hash\->{bar} );
.Ve
.PP
Petal expression
.PP
.Vb 1
\& some_object/some_method/key2/some_other_method \-\-foo bar
.Ve
.SS "true:EXPRESSION"
.IX Subsection "true:EXPRESSION"
.Vb 5
\& If EXPRESSION returns an array reference
\& If this array reference has at least one element
\& Returns TRUE
\& Else
\& Returns FALSE
\&
\& Else
\& If EXPRESSION returns a TRUE value (according to Perl \*(Aqtrueness\*(Aq)
\& Returns TRUE
\& Else
\& Returns FALSE
.Ve
.PP
the \f(CW\*(C`true:\*(C'\fR modifiers should always be used when doing Petal conditions.
.SS "false:EXPRESSION"
.IX Subsection "false:EXPRESSION"
I'm pretty sure you can work this one out by yourself :\-)
.SS "set:variable_name \s-1EXPRESSION\s0"
.IX Subsection "set:variable_name EXPRESSION"
Sets the value returned by the evaluation of \s-1EXPRESSION\s0 in
\&\f(CW\*(C`$hash\->{variable_name}\*(C'\fR. For instance:
.PP
Perl expression:
.PP
.Vb 1
\& $hash\->{variable_name} = $hash\->{object}\->method();
.Ve
.PP
Petal expression:
.PP
.Vb 1
\& set:variable_name object/method
.Ve
.SS "string:STRING_EXPRESSION"
.IX Subsection "string:STRING_EXPRESSION"
The \f(CW\*(C`string:\*(C'\fR modifier lets you interpolate petal expressions within a string
and returns the value.
.PP
.Vb 1
\& string:Welcome $user/real_name, it is $date!
.Ve
.PP
Alternatively, you could write:
.PP
.Vb 1
\& string:Welcome ${user/real_name}, it is ${date}!
.Ve
.PP
The advantage of using curly brackets is that it lets you interpolate
expressions which invoke methods with parameters, i.e.
.PP
.Vb 1
\& string:The current CGI \*(Aqaction\*(Aq param is: ${cgi/param \-\-action}
.Ve
.SH "ADVANCED PETAL"
.IX Header "ADVANCED PETAL"
.SS "writing your own modifiers"
.IX Subsection "writing your own modifiers"
Petal lets you write your own modifiers, either using coderefs
or modules.
.PP
\fICoderefs\fR
.IX Subsection "Coderefs"
.PP
Let's say that you want to write an uppercase: modifier, which
would uppercase the result of an expression evaluation, as in:
.PP
.Vb 1
\& uppercase:string:Hello, World
.Ve
.PP
Would return
.PP
.Vb 1
\& HELLO, WORLD
.Ve
.PP
Here is what you can do:
.PP
.Vb 4
\& # don\*(Aqt forget the trailing colon in C !!
\& $Petal::Hash::MODIFIERS\->{\*(Aquppercase:\*(Aq} = sub {
\& my $hash = shift;
\& my $args = shift;
\&
\& my $result = $hash\->fetch ($args);
\& return uc ($result);
\& };
.Ve
.PP
\fIModules.\fR
.IX Subsection "Modules."
.PP
You might want to use a module rather than a coderef. Here is the example above
reimplemented as a module:
.PP
.Vb 3
\& package Petal::Hash::UpperCase;
\& use strict;
\& use warnings;
\&
\& sub process {
\& my $class = shift;
\& my $hash = shift;
\& my $args = shift;
\&
\& my $result = $hash\->fetch ($args);
\& return uc ($result);
\& }
\&
\& 1;
.Ve
.PP
As long as your module is in the namespace Petal::Hash::,
Petal will automatically pick it up and assign it to its lowercased
name, i.e. in our example \f(CW\*(C`uppercase:\*(C'\fR.
.PP
If your modifier is \s-1OUTSIDE\s0 Petal::Hash::, you need to
make Petal aware of its existence as follows:
.PP
.Vb 2
\& use MyPetalModifier::UpperCase;
\& $Petal::Hash::MODIFIERS\->{\*(Aquppercase:\*(Aq} = \*(AqMyPetalModifier::UpperCase\*(Aq;
.Ve
.SH "Expression keywords"
.IX Header "Expression keywords"
\fI\s-1XML\s0 encoding / structure keyword\fR
.IX Subsection "XML encoding / structure keyword"
.PP
By default Petal will encode \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`<\*(C'\fR, \f(CW\*(C`\*(C'\fR> and \f(CW\*(C`"\*(C'\fR to \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`<\*(C'\fR,
\&\f(CW>\fR and \f(CW\*(C`"\*(C'\fR respectively. However sometimes you might want to display
an expression which is already encoded, in which case you can use the
\&\f(CW\*(C`structure\*(C'\fR keyword.
.PP
.Vb 1
\& structure my/encoded/variable
.Ve
.PP
Note that this is a language \fIkeyword\fR, not a modifier. It does not use a
trailing colon.
.PP
\fIPetal::Hash caching and fresh keyword\fR
.IX Subsection "Petal::Hash caching and fresh keyword"
.PP
Petal caches the expressions which it resolves, i.e. if you write the
expression:
.PP
.Vb 1
\& string:$foo/bar, ${baz/buz/blah}
.Ve
.PP
Petal::Hash will compute it once, and then for subsequent accesses to that
expression always return the same value. This is almost never a problem, even
for loops because a new Petal::Hash object is used for each iteration in order
to support proper scoping.
.PP
However, in some rare cases you might not want to have that behavior, in which
case you need to prefix your expression with the \f(CW\*(C`fresh\*(C'\fR keyword, i.e.
.PP
.Vb 1
\& fresh string:$foo/bar, ${baz/buz/blah}
.Ve
.PP
You can use \f(CW\*(C`fresh\*(C'\fR with \f(CW\*(C`structure\*(C'\fR if you need to:
.PP
.Vb 1
\& fresh structure string:$foo/bar, ${baz/buz/blah}
.Ve
.PP
However the reverse does not work:
.PP
.Vb 2
\&
\& structure fresh string:$foo/bar, ${baz/buz/blah}
.Ve
.SS "\s-1TOY\s0 \s-1FUNCTIONS\s0 (For debugging or if you're curious)"
.IX Subsection "TOY FUNCTIONS (For debugging or if you're curious)"
\fIperl \-MPetal \-e canonical template.xml\fR
.IX Subsection "perl -MPetal -e canonical template.xml"
.PP
Displays the canonical template for template.xml.
You can set \f(CW$Petal::INPUT\fR using by setting the \s-1PETAL_INPUT\s0 environment variable.
You can set \f(CW$Petal::OUTPUT\fR using by setting the \s-1PETAL_OUTPUT\s0 environment variable.
.PP
\fIperl \-MPetal \-e code template.xml\fR
.IX Subsection "perl -MPetal -e code template.xml"
.PP
Displays the perl code for template.xml.
You can set \f(CW$Petal::INPUT\fR using by setting the \s-1PETAL_INPUT\s0 environment variable.
You can set \f(CW$Petal::OUTPUT\fR using by setting the \s-1PETAL_OUTPUT\s0 environment variable.
.PP
\fIperl \-MPetal \-e lcode template.xml\fR
.IX Subsection "perl -MPetal -e lcode template.xml"
.PP
Displays the perl code for template.xml, with line numbers.
You can set \f(CW$Petal::INPUT\fR using by setting the \s-1PETAL_INPUT\s0 environment variable.
You can set \f(CW$Petal::OUTPUT\fR using by setting the \s-1PETAL_OUTPUT\s0 environment variable.
.SS "What does Petal do internally?"
.IX Subsection "What does Petal do internally?"
The cycle of a Petal template is the following:
.PP
.Vb 9
\& 1. Read the source XML template
\& 2. $INPUT (XML or HTML) throws XML events from the source file
\& 3. $OUTPUT (XML or HTML) uses these XML events to canonicalize the template
\& 4. Petal::CodeGenerator turns the canonical template into Perl code
\& 5. Petal::Cache::Disk caches the Perl code on disk
\& 6. Petal turns the perl code into a subroutine
\& 7. Petal::Cache::Memory caches the subroutine in memory
\& 8. Petal executes the subroutine
\& 9. (optional) Petal internationalizes the resulting output.
.Ve
.PP
If you are under a persistent environment a la mod_perl, subsequent calls to
the same template will be reduced to step 8 until the source template changes.
.PP
Otherwise, subsequent calls will resume at step 6, until the source template
changes.
.PP
If you are using the mod_perl prefork \s-1MPM\s0, you can precompile Petal templates
into Apache's shared memory at startup by using the cache_only option. This
will allow you to run through steps 1\-7 without passing any data to Petal.
.SH "DECRYPTING WARNINGS AND ERRORS"
.IX Header "DECRYPTING WARNINGS AND ERRORS"
.ie n .SS """Cannot import module $module. Reason: $@"" (nonfatal)"
.el .SS "``Cannot import module \f(CW$module\fP. Reason: $@'' (nonfatal)"
.IX Subsection "Cannot import module $module. Reason: $@ (nonfatal)"
Petal was not able to import one of the modules. This error warning will be
issued when Petal is unable to load a plugin because it has been badly install
or is just broken.
.ie n .SS """Petal modifier encode: is deprecated"" (nonfatal)"
.el .SS "``Petal modifier encode: is deprecated'' (nonfatal)"
.IX Subsection "Petal modifier encode: is deprecated (nonfatal)"
You don't need to use encode:EXPRESSION to XML-encode expression anymore,
Petal does it for you. encode: has been turned into a no-op.
.SS "Cannot find value for ... (\s-1FATAL\s0)"
.IX Subsection "Cannot find value for ... (FATAL)"
You tried to invoke an/expression/like/this/one but Petal could not resolve
it. This could be because an/expression/like evaluated to undef and hence the
remaining this/one could not be resolved.
.PP
Usually Petal gives you a line number and a dump of your template as Perl
code. You can look at the perl code to try to determine the faulty bit in
your template.
.SS "not well-formed (invalid token) at ... (\s-1FATAL\s0)"
.IX Subsection "not well-formed (invalid token) at ... (FATAL)"
Petal was trying to parse a file that is not well-formed \s-1XML\s0 or that has strange
entities in it. Try to run xmllint on your file to see if it's well formed or
try to use the \f(CW$Petal::INPUT\fR = '\s-1XHTML\s0' option.
.SS "other errors"
.IX Subsection "other errors"
Either I've forgot to document it, or it's a bug. Send an email to the Petal
mailing list.
.SH "EXPORTS"
.IX Header "EXPORTS"
None.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright 2003 \- MKDoc Ltd.
.PP
Authors: Jean-Michel Hiver,
Fergal Daly ,
and others.
.PP
This module free software and is distributed under the same license as Perl
itself. Use it at your own risk.
.PP
Thanks to everybody on the list who contributed to Petal in the form of
patches, bug reports and suggestions. See \s-1README\s0 for a list of contributors.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Join the Petal mailing list:
.PP
.Vb 1
\& http://lists.webarch.co.uk/mailman/listinfo/petal
.Ve
.PP
Mailing list archives:
.PP
.Vb 1
\& http://lists.webarch.co.uk/pipermail/petal
.Ve
.PP
Have a peek at the \s-1TAL\s0 / \s-1TALES\s0 / \s-1METAL\s0 specs:
.PP
.Vb 3
\& http://www.zope.org/Wikis/DevSite/Projects/ZPT/TAL
\& http://www.zope.org/Wikis/DevSite/Projects/ZPT/TALES
\& http://www.zope.org/Wikis/DevSite/Projects/ZPT/METAL
.Ve