.Ve
.PP
Why?
.PP
Attributes statements can be used to template a tag's attributes.
.SS "content"
.IX Subsection "content"
Abstract
.PP
.Vb 1
\& Dummy Data To Replace With EXPRESSION
.Ve
.PP
By default, the characters greater than, lesser than, double quote and
ampersand are encoded to the entities \fI<\fR, \fI>\fR, \fI"\fR and \fI&\fR
respectively. If you don't want them to (because the result of your expression
is already encoded) you have to use the \f(CW\*(C`structure\*(C'\fR keyword.
.PP
Example
.PP
.Vb 1
\& Dummy Title
\&
\&
\& blah blah blah
\&
.Ve
.PP
Why?
.PP
It lets you replace the contents of a tag with whatever value the evaluation of
\&\s-1EXPRESSION\s0 returned. This is handy because you can fill your templates with
dummy content which will make them usable in a \s-1WYSIWYG\s0 tool.
.SS "replace"
.IX Subsection "replace"
Abstract
.PP
.Vb 4
\&
\& This time the entire tag is replaced
\& rather than just the content!
\&
.Ve
.PP
Example
.PP
.Vb 1
\& Dummy Title
.Ve
.PP
Why?
.PP
Similar reasons to \f(CW\*(C`content\*(C'\fR. Note however that \f(CW\*(C`tal:content\*(C'\fR and
\&\f(CW\*(C`tal:replace\*(C'\fR are *NOT* aliases. The former will replace the contents of the
tag, while the latter will replace the whole tag.
.PP
Indeed you cannot use \f(CW\*(C`tal:content\*(C'\fR and \f(CW\*(C`tal:replace\*(C'\fR in the same tag.
.SS "omit-tag"
.IX Subsection "omit-tag"
Abstract
.PP
.Vb 1
\& Some contents
.Ve
.PP
Example
.PP
.Vb 1
\& I may not be bold.
.Ve
.PP
If \f(CW\*(C`not:bold\*(C'\fR is evaluated as \fI\s-1TRUE\s0\fR, then the tag will be omited.
If \f(CW\*(C`not:bold\*(C'\fR is evaluated as \fI\s-1FALSE\s0\fR, then the tag will stay in place.
.PP
Why?
.PP
omit-tag statements can be used to leave the contents of a tag in place while
omitting the surrounding start and end tags if the expression which is
evaluated is \s-1TRUE.\s0
.PP
\&\s-1TIP:\s0
.PP
If you want to \s-1ALWAYS\s0 remove a tag, you can use \f(CW\*(C`omit\-tag="string:1"\*(C'\fR
.SS "on-error"
.IX Subsection "on-error"
Warning: this is currently only partially implemented. \f(CW\*(C`on\-error\*(C'\fR may be used
in Petal templates, but the expression isn't evaluated \- Petal simply prints
the expression as a string.
.PP
Abstract
.PP
.Vb 1
\& ...
.Ve
.PP
Example
.PP
.Vb 3
\&
\& $object/method
\&
.Ve
.PP
Why?
.PP
When Petal encounters an error, it usually dies with some obscure error
message. The \f(CW\*(C`on\-error\*(C'\fR statement lets you trap the error and replace it
with a proper error message.
.SS "using multiple statements"
.IX Subsection "using multiple statements"
You can do things like:
.PP
.Vb 6
\& Some Dummy Content
.Ve
.PP
Given the fact that \s-1XML\s0 attributes are not ordered, within the same tag
statements will be executed in the following order:
.PP
.Vb 10
\& define
\& condition
\& repeat
\& attributes
\& content
\& OR
\& replace
\& OR
\& omit\-tag
\& content
.Ve
.PP
\&\s-1TRAP:\s0
.PP
Don't forget that the default prefix is \f(CW\*(C`petal:\*(C'\fR \s-1NOT\s0 \f(CW\*(C`tal:\*(C'\fR, until
you set the petal namespace in your \s-1HTML\s0 or \s-1XML\s0 document as follows:
.PP
.Vb 1
\&
.Ve
.SH "METAL MACROS"
.IX Header "METAL MACROS"
Petal supports an implementation of the \s-1METAL\s0 specification, which is a very
\&\s-1WYSIWYG\s0 compatible way of doing template includes.
.SS "define-macro"
.IX Subsection "define-macro"
In order to define a macro inside a file (i.e. a fragment to be included), you
use the metal:define\-macro directive. For example:
.PP
.Vb 2
\& File foo.xml
\& ============
\&
\&
\&
\&
\& (c) Me (r)(tm) (pouet pouet)
\&
\&
\&
.Ve
.SS "use-macro"
.IX Subsection "use-macro"
In order to use a previously defined macro, you use the metal:use\-macro directive.
For example:
.PP
.Vb 2
\& File bar.xml
\& ============
\&
\&
\&
\& ... plenty of content ...
\&
\&
\& Page Footer.
\&
\&
\&
.Ve
.SS "define-slot"
.IX Subsection "define-slot"
In any given macro you can define slots, which are bits of macros that can be
overridden by something else using the fill-macro directive. To re-use the
example above, imagine that we want to be able to optionally override the
(pouet pouet) bit with something else:
.PP
.Vb 2
\& File foo.xml
\& ============
\&
\&
\&
\&
\& (c) Me (r)(tm) (pouet pouet)
\&
\&
\&
.Ve
.SS "fill-slot"
.IX Subsection "fill-slot"
Your including file can override any slot using the fill-slot instruction, i.e.
.PP
.Vb 2
\& File bar.xml
\& ============
\&
\&
\&
\& ... plenty of content ...
\&
\&
\& Page Footer. (bar baz)
\&
\&
\&
.Ve
.PP
This would result in the macro 'foo.xml#footer' to produce:
.PP
.Vb 7
\&
\&
\&
\& (c) Me (r)(tm) (bar baz)
\&
\&
\&
.Ve
.SS "self includes"
.IX Subsection "self includes"
In Zope, \s-1METAL\s0 macros are expanded first, and then the \s-1TAL\s0 instructions are processed.
However with Petal, \s-1METAL\s0 macros are expanded at run-time just like regular includes,
which allows for recursive macros.
.PP
This example templates a sitemap, which on a hierarchically organized site would
be recursive by nature:
.PP
.Vb 4
\&
\&
\& Sitemap:
\&
\&
\& Child Document Title
\&
\& - Dummy Child 1
\& - Dummy Child 2
\& - Dummy Child 3
\&
\&
\&
\&
.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
\&
\&
.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 FUNCTIONS\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 / TALES / METAL\s0 specs:
.PP
.Vb 3
\& http://wiki.zope.org/ZPT/TAL
\& http://wiki.zope.org/ZPT/TALES
\& http://wiki.zope.org/ZPT/METAL
.Ve