Author image Jean-Michel Hiver

NAME

Petal - Perl Template Attribute Language

SYNOPSIS

  use Petal;
  @Petal::BASE_DIR = qw |. ./templates /var/www/templates|;
  my $template = new Petal ( 'test.xml' );
  print $template->process (
    some_hash   => $hashref,
    some_array  => $arrayref,
    some_object => $object,
  );

SUMMARY

Petal is a XML based templating engine that is able to process any kind of XML. HTML parsing and XHTML is also supported.

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

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

Besides, you can safely send the result of their work through HTML tidy to make sure that you always output neat, standard compliant, valid XML pages.

NAMESPACE

Although this is not mandatory, Petal templates should include use the namespace http://purl.org/petal/1.0/, preferably as an attribute of the first element of the XML template which you are processing.

Example:

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

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

GLOBAL VARIABLES

Description

$INPUT - Currently acceptable values are

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

This variable defaults to 'XML'.

$OUTPUT - Currently acceptable values are

  'XML'   - Petal will output generic XML
  'XHTML' - Same as XML except for tags like <br /> or <input />

$TAINT - If set to TRUE, makes perl taint mode happy. Defaults to FALSE.

@BASE_DIR - Base directories from which the templates should be retrieved. Petal will try to fetch the template file starting from the beginning of the list until it finds one base directory which has the requested file.

@BASE_DIR defaults to ('.', '/').

$DISK_CACHE - If set to FALSE, Petal will not use the Petal::Cache::Disk module. Defaults to TRUE.

$MEMORY_CACHE - If set to FALSE, Petal will not use the Petal::Cache::Memory module. Defaults to TRUE.

$MAX_INCLUDES - Maximum number of recursive includes before Petal stops processing. This is to prevent from accidental infinite recursions.

$CodeGenerator - The CodeGenerator class backend to use. Change this only if you know what you're doing.

Example

  # at the beginning of your program:

  # try to look up for file in '.', then in '..', then...
  @Petal::BASE_DIR = ('.', '..', '~/default/templates');

  # vroom!
  $Petal::DISK_CACHE = 1;
  $Petal::MEMORY_CACHE = 1;

  # we are parsing a valid XHTML file, and we want to output
  # XHTML as well...
  $Petal::INPUT = 'XML';
  $Petal::OUTPUT = 'XHTML';  

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 $INPUT using by setting the PETAL_INPUT environment variable. You can set $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 $INPUT using by setting the PETAL_INPUT environment variable. You can set $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 $INPUT using by setting the PETAL_INPUT environment variable. You can set $OUTPUT using by setting the PETAL_OUTPUT environment variable.

METHODS

$class->new ( file => $file );

Instanciates a new Petal object.

$self->process (%hash);

Processes the current template object with the information contained in %hash. This information can be scalars, hash references, array references or objects.

Example:

  my $data_out = $template->process (
    user   => $user,
    page   => $page,
    basket => $shopping_basket,    
  );

  print "Content-Type: text/html\n\n";
  print $data_out;

Template cycle

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

If you are under a persistent environement 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.

Petal Syntax Summary

Petal features a flexible, XML-compliant syntax which can be summarized as follows:

Template comments

  <!--? This will not be in the output -->

"Simple" syntax (Variable Interpolation)

  $my_variable
  $my_object/my_method
  $my_array/2
  $my_hash/some_key

This syntax is documented in the Petal::Doc::Inline article.

"TAL-like" syntax, i.e.

  <li petal:repeat="element list"
      petal:content="element">Some dummy element</li>

Which if 'list' was ('foo', 'bar', 'baz') would output:

  <li>foo</li>
  <li>bar</li>
  <li>baz</li>

This syntax is documented in the Petal::Doc::TAL article.

"Usual" syntax (like HTML::Template, Template::Toolkit, etc), i.e

  <?condition name="list"?>
    <?repeat name="element list"?>
      <li><?var name="element"?></li>
    <?end?>
  <?end?>

This syntax is documented in the Petal::Doc::PIs article.

Limited Xinclude support

Let's say that your base directory is '/www/projects/foo/templates', and you're editing '/www/projects/foo/templates/hello/index.html'.

From there you want to include '/www/projects/foo/templates/includes/header.html'

General syntax

You can use a subset of the XInclude syntax as follows:

  <body xmlns:xi="http://www.w3.org/2001/XInclude">
    <xi:include href="/includes/header.html" />
  </body>

For backwards compatibility reasons, you can omit the first slash, i.e.

  <xi:include href="includes/header.html" />

Relative paths

If you'd rather use a path which is relative to the template itself rather than the base directory, you can do it but the path needs to start with a dot, i.e.

  <xi:include href="../includes/header.html" />

  <xi:include href="./subdirectory/foo.xml" />

etc.

Limitations

The 'href' parameter does not support URIs, no other tag than xi:include is supported, and no other directive than the 'href' parameter is supported at the moment.

Also note that contrarily to the XInclude specification Petal DOES allow recursive includes up to $Petal::MAX_INCLUDES. This behavior is very useful when designing templates to display data which can be recursive such as sitemaps, database cursors, fibonacci suites, etc.

You can use ONLY the following Petal directives with Xinclude tags:

  * on-error
  * define
  * condition
  * repeat

replace, content, omit-tag and attributes are NOT supported in conjunction with XIncludes.

Variable expressions and modifiers

Petal lets you transparently access arrays, hashes, objects, etc. trough a unified syntax called Petales (Petal Expression Syntax). It is documented in Petal::Doc::Petales.

EXPORT

None.

KNOWN BUGS

The XML::Parser wrapper cannot expand any other entity than &lt;, &gt; &amp; and &quot;. Besides, I can't get it to NOT expand entities in 'Stream' mode :-(

HTML::TreeBuilder expands all entities, hence &nbsp;s are lost / converted to whitespaces.

XML::Parser is deprecated and should be replaced by SAX handlers at some point.

AUTHOR

Copyright 2002 - Jean-Michel Hiver <jhiver@mkdoc.com>

This module free software and is distributed under the same license as Perl itself.

Many thanks to:

William McKee <william@knowmad.com> for his useful suggestions, patches, and bug reports.

Sean M. Burke <sburke@cpan.org> for his improvements on the HTML::TreeBuilder module which tremendously helped with HTML parsing.

And everyone else I forgot :-)

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://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

Look at the different syntaxes which you can use:

Petal::Doc::Inline, Petal::Doc::PIs, Petal::Doc::TAL,

And the expression syntax: Petal::Doc::Petales.

Any extra questions? jhiver@mkdoc.com.