Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Petal(3)	      User Contributed Perl Documentation	      Petal(3)

NAME
       Petal - Perl Template Attribute Language	- TAL for Perl!

SYNOPSIS
       in your Perl code:

	 use Petal;
	 my $template =	new Petal ('foo.xhtml');
	 print $template->process (bar => 'BAZ');

       in foo.xhtml

	 <html xmlns:tal="http://purl.org/petal/1.0/">
	   <body tal:content="bar">Dummy Content</body>
	 </html>

       and you get something like:

	 <html>
	   <body>BAZ</body>
	 </html>

SUMMARY
       Petal is	a XML based templating engine that is able to process any kind
       of XML, XHTML and HTML.

       Petal borrows a lot of good ideas from the Zope Page Templates TAL
       specification, it is very well suited for the creation of WYSIWYG XHTML
       editable	templates.

       The idea	is to further enforce the separation of	logic from
       presentation. With Petal, graphic designers can use their favorite
       WYSIWYG editor to easily	edit templates without having to worry about
       the loops and ifs which happen behind the scene.

NAMESPACE
       Although	this is	not mandatory, Petal templates should include use the
       namespace <http://purl.org/petal/1.0/>. Example:

	   <html xml:lang="en"
		 lang="en"
		 xmlns="http://www.w3.org/1999/xhtml"
		 xmlns:tal="http://purl.org/petal/1.0/">

	     Blah blah blah...
	     Content of	the file
	     More blah blah...
	   </html>

       If you do not specify the namespace, Petal will by default try to use
       the "petal:" prefix. However, in	all the	examples of this POD we'll use
       the "tal:" prefix to avoid too much typing.

KICKSTART
       Let's say you have the following	Perl code:

	   use Petal;
	   local $Petal::OUTPUT	= 'XHTML';

	   my $template	= new Petal ('foo.xhtml');
	   $template->process (	my_var => some_object()	);

       some_object() 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...

   Version 1: WYSIWYG friendly prototype.
       Using TAL you can do:

	   This	is the variable	'my_var' :
	   <span tal:replace="my_var/hello_world">Hola,	Mundo!</span>

       Now you can open	your template in any WYSIWYG tool (mozilla composer,
       frontpage, dreamweaver, adobe golive...)	and work with less risk	of
       damaging	your petal commands.

   Version 2: Object-oriented version
       Let's now say that "my_var" is actually an object with a	method
       hello_world() that returns Hello	World. To output the same result, your
       line, which was:

	   <span tal:replace="my_var/hello_world">Hola,	Mundo!</span>

       Would need to be... EXACTLY the same. Petal lets	you access hashes and
       objects in an entirely transparent way and tries	to automagically do
       The Right Thing for you.

       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.

   Version 3: Personalizable
       Now let's say that your method hello_world() can	take an	optional
       argument	so that	"$some_object->hello_world ('Jack')" returns Hello
       Jack.

       You would write:

	   <span tal:replace="my_var/hello_world 'Jack'">Hola, Mundo!</span>

       Optionally, you can get rid of the quotes by using two dashes, a	la GNU
       command-line option:

	   <span tal:replace="my_var/hello_world --Jack">Hola, Mundo!</span>

       So you can pass parameters to methods using double dashes or quotes.
       Now let us say that your	"my_var" object	also has a method
       current_user() that returns the current user real name. You can do:

	   <span tal:replace="my_var/hello_world my_var/current_user">Hola, Mundo!</span>

       TRAP:

       You cannot write	nested expressions such	as:

	   ${my_var/hello_world	${my_var/current_user}}

       This will NOT work. At least, not yet.

   Version 4: Internationalized
       Let's say that you have a directory called "hello_world"	with the
       following files:

	   hello_world/en.xhtml
	   hello_world/fr.xhtml
	   hello_world/es.xhtml

       You can use Petal as follows in your Perl code:

	   use Petal;
	   local $Petal::OUTPUT	= 'XHTML';

	   my $template	= new Petal ( file => 'hello_world', lang => 'fr-CA' );
	   print $template->process ( my_var =>	some_object() );

       What will happen	is that	the $template object will look in the
       "hello_world" directory and try to find a file named "fr-CA.xhtml",
       then "fr.xhtml",	then will default to "en.xhtml". It works fine for
       includes, too!

       These internationalized templates can have whatever file-extension you
       like, Petal searches on the first part of the filename.	So you can
       call them "fr.html", "fr.xml", "fr.xhtml" or use	whatever convention
       suits you.

       NOTE: There is now support for ZPT-like i18n attributes,	which should
       provide a much nicer framework. See Petal::I18N for details.

       TIP:

       If you feel that	'en' should not	be the default language, you can
       specify a different default:

	   my $template	= new Petal (
	       file		=> 'hello_world',
	       language		=> 'zh',
	       default_language	=> 'fr'	# vive la France!
	   );

       TRAP:

       If you do specify the "lang" option, you	MUST use a path	to a template
       directory, not a	file directory.

       Conversely, if you do not specify a "lang" option, you MUST use a path
       to a template file, not a directory.

OPTIONS
       When you	create a Petal template	object you can specify various options
       using name => value pairs as arguments to the constructor.  For
       example:

	 my $template =	Petal->new(
	   file	    => 'gerbils.html',
	   base_dir => '/var/www/petshop',
	   input    => 'HTML',
	   output   => 'HTML',
	 );

       The recognized options are:

   file	=> filename
       The template filename.  This option is mandatory	and has	no default.

       Note: If	you also use 'language'	this option should point to a
       directory.

   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.

   input => 'HTML' | 'XHTML' | 'XML' (default: 'XML')
       Defines the format of the template files.  Recognised values are:

	 'HTML'	 - Alias for 'XHTML'
	 'XHTML' - Petal will use Petal::Parser	to parse the template
	 'XML'	 - Petal will use Petal::Parser	to parse the template

   output => 'HTML' | 'XHTML' |	'XML' (default:	'XML')
       Defines the format of the data generated	as a result of processing the
       template	files.	Recognised values are:

	 'HTML'	 - Petal will output XHTML, self-closing certain tags
	 'XHTML' - Alias for 'HTML'
	 'XML'	 - Petal will output generic XML

   language => language	code
       For internationalized applications, you can use the 'file' option to
       point to	a directory 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').

   default_language => language	code (default: 'en')
       This language code will be used if no template matches the selected
       language-country	or language.

   taint => true | false (default: false)
       If set to "true", makes perl taint mode happy.

   error_on_undef_var => true |	false (default:	true)
       If set to "true", Petal will confess() errors when trying to access
       undefined template variables, otherwise an empty	string will be
       returned.

   error_on_include_error => true | false (default: false)
       If set to "true", Petal will confess() errors when trying render
       includes.

   disk_cache => true |	false (default:	true)
       If set to "false", Petal	will not use the "Petal::Cache::Disk" module.

   memory_cache	=> true	| false	(default: true)
       If set to "false", Petal	will not use the "Petal::Cache::Memory"
       module.

   cache_only => true |	false (default:	false)
       If set to "true", 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.

   max_includes	=> number (default: 30)
       The maximum number of recursive includes	before Petal stops processing.
       This is to guard	against	accidental infinite recursions.

   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->tmpdir()
       specifies as a temp directory (usually /tmp on a	unix system).

   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.

       It doesn't guarantee that the result will be in UTF-8 or	in your	local
       encoding, but at	least the UTF-8	flag should be set properly.

       If you want to encode the results for a specific	charset, you should
       look at the module Encode.

   decode_charset => charset (default: undef)
       This option will	work only if you use Perl 5.8 or greater.

       If specified, Petal will	assume that the	template to be processed (and
       its sub-templates) are in the character set charset.

       charset can be any character set	that can be used with the module
       Encode.

TAL SYNTAX
       This functionality is directly and shamelessly stolen from the
       excellent TAL specification: <http://wiki.zope.org/ZPT/TAL>.

   define
       Abstract

	 <tag tal:define="variable_name	EXPRESSION">

       Evaluates "EXPRESSION" and assigns the returned value to
       "variable_name".

       Example

	 <!--? sets document/title to 'title' -->
	 <span tal:define="title document/title">

       Why?

       This can	be useful if you have a	"very/very/long/expression".  You can
       set it to let's say "vvle" and then use "vvle" instead of using
       "very/very/long/expression".

   condition (ifs)
       Abstract

	 <tag tal:condition="true:EXPRESSION">
	    blah blah blah
	 </tag>

       Example

	 <span tal:condition="true:user/is_authenticated">
	   Yo, authenticated!
	 </span>

       Why?

       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.

   repeat (loops)
       Abstract

	 <tag tal:repeat="element_name EXPRESSION">
	    blah blah blah
	 </tag>

       Why?

       Repeat statements are used to loop through a list of values, typically
       to display the resulting	records	of a database query.

       Example:

	 <li tal:repeat="user system/user_list">$user/real_name</li>

       A select	list with one item selected:

	 <select>
	   <option
	     selected="selected"
	     tal:attributes="value self/selected_lang/value"
	     tal:content="self/selected_lang/label"
	   >English</option>
	   <option
	     value="i-klingon"
	     tal:repeat="lang self/unselected_langs;"
	     tal:attributes="value lang/value"
	     tal:content="lang/label"
	   >Klingon</option>
	 </select>

       A table with rows of alternating	colours	set via	CSS:

	 <table>
	   <div
	     tal:omit-tag=""
	     tal:repeat="audience self/audiences"
	   >
	     <tr
	       class="odd"
	       tal:condition="repeat/odd"
	     >
	       <td>
		 This a	odd row, it comes before the even row.
	       </td>
	     </tr>
	     <tr
	       class="even"
	       tal:condition="repeat/even"
	     >
	       <td>
		 This a	even row.
	       </td>
	     </tr>
	   </div>
	 </table>

       repeat is a local temporary object that only exists within a
       petal:repeat loop.  It has a bunch of methods useful for	selecting
       different positions in the loop:

       repeat/index

       index returns the numeric position of this item within the loop,	starts
       with one	not zero.

       repeat/number

       number is an alias for index.

       repeat/even

       even is true if the position is even (0,	2, 4 ...)

       repeat/odd

       odd is true is the position is odd (1, 3, 5 ...)

       repeat/start

       start is	true if	this is	the first item.

       repeat/end

       end is true if this is the last item.

       repeat/inner

       inner is	true if	this is	not the	start or end.

   attributes
       Abstract

	 <tag tal:attributes="attr1 EXPRESSION_1; attr2	EXPRESSION_2"; ...">
	    blah blah blah
	 </tag>

       Example

	 <a href="http://www.gianthard.com"
	    lang="en-gb"
	    tal:attributes="href document/href_relative; lang document/lang">

       Why?

       Attributes statements can be used to template a tag's attributes.

   content
       Abstract

	 <tag tal:content="EXPRESSION">Dummy Data To Replace With EXPRESSION</tag>

       By default, the characters greater than,	lesser than, double quote and
       ampersand are encoded to	the entities _lt;, _gt;, _quot;	and _amp;
       respectively.  If you don't want	them to	(because the result of your
       expression is already encoded) you have to use the "structure" keyword.

       Example

	 <span tal:content="title">Dummy Title</span>

	 <span tal:content="structure some/variable">
	    blah blah blah
	 </span>

       Why?

       It lets you replace the contents	of a tag with whatever value the
       evaluation of EXPRESSION	returned. This is handy	because	you can	fill
       your templates with dummy content which will make them usable in	a
       WYSIWYG tool.

   replace
       Abstract

	 <tag tal:replace="EXPRESSION">
	   This	time the entire	tag is replaced
	   rather than just the	content!
	 </tag>

       Example

	 <span tal:replace="title">Dummy Title</span>

       Why?

       Similar reasons to "content". Note however that "tal:content" and
       "tal:replace" are *NOT* aliases.	The former will	replace	the contents
       of the tag, while the latter will replace the whole tag.

       Indeed you cannot use "tal:content" and "tal:replace" in	the same tag.

   omit-tag
       Abstract

	 <tag tal:omit-tag="EXPRESSION">Some contents</tag>

       Example

	 <b tal:omit-tag="not:bold">I may not be bold.</b>

       If "not:bold" is	evaluated as TRUE, then	the <b>	tag will be omited.
       If "not:bold" is	evaluated as FALSE, then the <b> tag will stay in
       place.

       Why?

       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 TRUE.

       TIP:

       If you want to ALWAYS remove a tag, you can use "omit-tag="string:1""

   on-error
       Warning:	this is	currently only partially implemented.  "on-error" may
       be used in Petal	templates, but the expression isn't evaluated -	Petal
       simply prints the expression as a string.

       Abstract

	 <tag on-error="EXPRESSION">...</tag>

       Example

	 <p on-error="string:Cannot access object/method!!">
	   $object/method
	 </p>

       Why?

       When Petal encounters an	error, it usually dies with some obscure error
       message.	The "on-error" statement lets you trap the error and replace
       it with a proper	error message.

   using multiple statements
       You can do things like:

	 <p tal:define="children document/children"
	    tal:condition="children"
	    tal:repeat="child children"
	    tal:attributes="lang child/lang; xml:lang child/lang"
	    tal:content="child/data"
	    tal:on-error="string:Ouch!">Some Dummy Content</p>

       Given the fact that XML attributes are not ordered, within the same tag
       statements will be executed in the following order:

	   define
	   condition
	   repeat
	       attributes
	       content
	   OR
	       replace
	   OR
	       omit-tag
	       content

       TRAP:

       Don't forget that the default prefix is "petal:"	NOT "tal:", until you
       set the petal namespace in your HTML or XML document as follows:

	   <html xmlns:tal="http://purl.org/petal/1.0/">

METAL MACROS
       Petal supports an implementation	of the METAL specification, which is a
       very WYSIWYG compatible way of doing template includes.

   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:

	 File foo.xml
	 ============

	 <html xmlns:metal="http://xml.zope.org/namespaces/metal">
	   <body>
	     <p	metal:define-macro="footer">
	       (c) Me (r)(tm) (pouet pouet)
	     </p>
	   </body>
	 </html>

   use-macro
       In order	to use a previously defined macro, you use the metal:use-macro
       directive.  For example:

	 File bar.xml
	 ============

	 <html xmlns:metal="http://xml.zope.org/namespaces/metal">
	   <body>
	     ... plenty	of content ...

	     <p	metal:use-macro="foo.xml#footer">
	       Page Footer.
	     </p>
	   </body>
	 </html>

   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:

	 File foo.xml
	 ============

	 <html xmlns:metal="http://xml.zope.org/namespaces/metal">
	   <body>
	     <p	metal:define-macro="footer">
	       (c) Me (r)(tm) <span metal:define-slot="pouet">(pouet pouet)</span>
	     </p>
	   </body>
	 </html>

   fill-slot
       Your including file can override	any slot using the fill-slot
       instruction, i.e.

	 File bar.xml
	 ============

	 <html xmlns:metal="http://xml.zope.org/namespaces/metal">
	   <body>
	     ... plenty	of content ...

	     <p	metal:use-macro="foo.xml#footer">
	       Page Footer. <span metal:fill-slot="pouet" petal:omit-tag="">(bar baz)</span>
	     </p>
	   </body>
	 </html>

       This would result in the	macro 'foo.xml#footer' to produce:

	 <html>
	   <body>
	     <p>
	       (c) Me (r)(tm) (bar baz)
	     </p>
	   </body>
	 </html>

   self	includes
       In Zope,	METAL macros are expanded first, and then the TAL instructions
       are processed.  However with Petal, METAL macros	are expanded at	run-
       time just like regular includes,	which allows for recursive macros.

       This example templates a	sitemap, which on a hierarchically organized
       site would be recursive by nature:

	 <html xmlns:metal="http://xml.zope.org/namespaces/metal"
	       xmlns:petal="http://purl.org/petal/1.0/">
	   <body>
	     <p>Sitemap:</p>

	     <li metal:define-macro="recurse">
	       <a href="#"
		  petal:attributes="href child/Full_Path"
		  petal:content="child/Title"
	       >Child Document Title</a>
	       <ul
		 petal:define="children	child/Children"
		 petal:condition="children"
		 petal:repeat="child children"
	       >
		 <li metal:use-macro="#recurse">Dummy Child 1</li>
		 <li petal:replace="nothing">Dummy Child 2</li>
		 <li petal:replace="nothing">Dummy Child 3</li>
	       </ul>
	     </li>
	   </body>
	 </html>

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.

       In the following	examples, we'll	assume that the	template is used as
       follows:

	 my $hashref = some_complex_data_structure();
	 my $template =	new Petal ('foo.xml');
	 print $template->process ( $hashref );

       Then we will show how the Petal Expression Syntax maps to the Perl way
       of accessing these values.

   accessing scalar values
       Perl expression

	 $hashref->{'some_value'};

       Petal expression

	 some_value

       Example

	 <!--? Replaces	Hello, World with the contents of
	       $hashref->{'some_value'}
	 -->
	 <span tal:replace="some_value">Hello, World</span>

   accessing hashes & arrays
       Perl expression

	 $hashref->{'some_hash'}->{'a_key'};

       Petal expression

	 some_hash/a_key

       Example

	 <!--? Replaces	Hello, World with the contents
	       of $hashref->{'some_hash'}->{'a_key'}
	 -->
	 <span tal:replace="some_hash/a_key">Hello, World</span>

       Perl expression

	 $hashref->{'some_array'}->[12]

       Petal expression

	 some_array/12

       Example

	 <!--? Replaces	Hello, World with the contents
	      of $hashref->{'some_array'}->[12]
	 -->
	 <span tal:replace="some_array/12">Hello, World</span>

       Note: You're more likely	to want	to loop	through	arrays:

	 <!--? Loops trough the	array and displays each	values -->
	 <ul tal:condition="some_array">
	   <li tal:repeat="value some_array"
	       tal:content="value">Hello, World</li>
	 </ul>

   accessing object methods
       Perl expressions

	 1. $hashref->{'some_object'}->some_method();
	 2. $hashref->{'some_object'}->some_method ('foo', 'bar');
	 3. $hashref->{'some_object'}->some_method ($hashref->{'some_variable'})

       Petal expressions

	 1. some_object/some_method
	 2a. some_object/some_method 'foo' 'bar'
	 2b. some_object/some_method "foo" "bar"
	 2c. some_object/some_method --foo --bar
	 3. some_object/some_method some_variable

       Note that the syntax as described in 2c works only if you use strings
       which do	not contain spaces.

       Example

	 <p>
	   <span tal:replace="value1">2</span> times
	   <span tal:replace="value2">2</span> equals
	   <span tal:replace="math_object/multiply value1 value2">4</span>
	 </p>

   composing
       Petal lets you traverse any data	structure, i.e.

       Perl expression

	 $hashref->{'some_object'}
		 ->some_method()
		 ->{'key2'}
		 ->some_other_method ( 'foo', $hash->{bar} );

       Petal expression

	 some_object/some_method/key2/some_other_method	--foo bar

   true:EXPRESSION
	 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 'trueness')
	     Returns TRUE
	   Else
	     Returns FALSE

       the "true:" modifiers should always be used when	doing Petal
       conditions.

   false:EXPRESSION
       I'm pretty sure you can work this one out by yourself :-)

   set:variable_name EXPRESSION
       Sets the	value returned by the evaluation of EXPRESSION in
       "$hash->{variable_name}". For instance:

       Perl expression:

	 $hash->{variable_name}	= $hash->{object}->method();

       Petal expression:

	 set:variable_name object/method

   string:STRING_EXPRESSION
       The "string:" modifier lets you interpolate petal expressions within a
       string and returns the value.

	 string:Welcome	$user/real_name, it is $date!

       Alternatively, you could	write:

	 string:Welcome	${user/real_name}, it is ${date}!

       The advantage of	using curly brackets is	that it	lets you interpolate
       expressions which invoke	methods	with parameters, i.e.

	 string:The current CGI	'action' param is: ${cgi/param --action}

ADVANCED PETAL
   writing your	own modifiers
       Petal lets you write your own modifiers,	either using coderefs or
       modules.

       Coderefs

       Let's say that you want to write	an uppercase: modifier,	which would
       uppercase the result of an expression evaluation, as in:

	 uppercase:string:Hello, World

       Would return

	 HELLO,	WORLD

       Here is what you	can do:

	 # don't forget	the trailing colon in C<uppercase:> !!
	 $Petal::Hash::MODIFIERS->{'uppercase:'} = sub {
	     my	$hash =	shift;
	     my	$args =	shift;

	     my	$result	= $hash->fetch ($args);
	     return uc ($result);
	 };

       Modules.

       You might want to use a module rather than a coderef. Here is the
       example above reimplemented as a	module:

	   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;

       As long as your module is in the	namespace
       Petal::Hash::<YourModifierName>,	Petal will automatically pick it up
       and assign it to	its lowercased name, i.e. in our example "uppercase:".

       If your modifier	is OUTSIDE Petal::Hash::<YourModifierName>, you	need
       to make Petal aware of its existence as follows:

	 use MyPetalModifier::UpperCase;
	 $Petal::Hash::MODIFIERS->{'uppercase:'} = 'MyPetalModifier::UpperCase';

Expression keywords
       XML encoding / structure	keyword

       By default Petal	will encode "&", "<", ""> and """ to "&amp;", "&lt;",
       &gt and "&quot;"	respectively. However sometimes	you might want to
       display an expression which is already encoded, in which	case you can
       use the "structure" keyword.

	 structure my/encoded/variable

       Note that this is a language keyword, not a modifier. It	does not use a
       trailing	colon.

       Petal::Hash caching and fresh keyword

       Petal caches the	expressions which it resolves, i.e. if you write the
       expression:

	 string:$foo/bar, ${baz/buz/blah}

       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.

       However,	in some	rare cases you might not want to have that behavior,
       in which	case you need to prefix	your expression	with the "fresh"
       keyword,	i.e.

	 fresh string:$foo/bar,	${baz/buz/blah}

       You can use "fresh" with	"structure" if you need	to:

	 fresh structure string:$foo/bar, ${baz/buz/blah}

       However the reverse does	not work:

	 <!--? VERY BAD, WON'T WORK !!!	-->
	 structure fresh string:$foo/bar, ${baz/buz/blah}

   TOY FUNCTIONS (For debugging	or if you're curious)
       perl -MPetal -e canonical template.xml

       Displays	the canonical template for template.xml.  You can set
       $Petal::INPUT using by setting the PETAL_INPUT environment variable.
       You can set $Petal::OUTPUT using	by setting the PETAL_OUTPUT
       environment variable.

       perl -MPetal -e code template.xml

       Displays	the perl code for template.xml.	 You can set $Petal::INPUT
       using by	setting	the PETAL_INPUT	environment variable.  You can set
       $Petal::OUTPUT using by setting the PETAL_OUTPUT	environment variable.

       perl -MPetal -e lcode template.xml

       Displays	the perl code for template.xml,	with line numbers.  You	can
       set $Petal::INPUT using by setting the PETAL_INPUT environment
       variable.  You can set $Petal::OUTPUT using by setting the PETAL_OUTPUT
       environment variable.

   What	does Petal do internally?
       The cycle of a Petal template is	the following:

	   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.

       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.

       Otherwise, subsequent calls will	resume at step 6, until	the source
       template	changes.

       If you are using	the mod_perl prefork MPM, 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.

DECRYPTING WARNINGS AND	ERRORS
   "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.

   "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.

   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.

       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.

   not well-formed (invalid token) at ... (FATAL)
       Petal was trying	to parse a file	that is	not well-formed	XML 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 $Petal::INPUT	= 'XHTML' option.

   other errors
       Either I've forgot to document it, or it's a bug. Send an email to the
       Petal mailing list.

EXPORTS
       None.

AUTHOR
       Copyright 2003 -	MKDoc Ltd.

       Authors:	Jean-Michel Hiver,
		Fergal Daly <fergal@esatclear.ie>,
		and others.

       This module free	software and is	distributed under the same license as
       Perl itself. Use	it at your own risk.

       Thanks to everybody on the list who contributed to Petal	in the form of
       patches,	bug reports and	suggestions. See README	for a list of
       contributors.

SEE ALSO
       Join the	Petal mailing list:

	 http://lists.webarch.co.uk/mailman/listinfo/petal

       Mailing list archives:

	 http://lists.webarch.co.uk/pipermail/petal

       Have a peek at the TAL /	TALES /	METAL specs:

	 http://wiki.zope.org/ZPT/TAL
	 http://wiki.zope.org/ZPT/TALES
	 http://wiki.zope.org/ZPT/METAL

perl v5.32.1			  2020-05-20			      Petal(3)

NAME | SYNOPSIS | SUMMARY | NAMESPACE | KICKSTART | OPTIONS | TAL SYNTAX | METAL MACROS | EXPRESSIONS AND MODIFIERS | ADVANCED PETAL | Expression keywords | DECRYPTING WARNINGS AND ERRORS | EXPORTS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Petal&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help