NAME

XML::Template - Perl XML template instantiation

SYNOPSIS

  use XML::Template;
  my %namespace = (
	      foo => "bar",
  );

 my $interp = XML::Template->new("examples", format => "<!-- %s -->");
 print $interp->compose(\%namespace, "example.xmlt");
 print $interp->compose_string(\%ns,"<template>${foo}</template>");

 <template>
    $(var) or ${var}
    ${DATE}
    ${TIME}
    ${NOW}

    <assign name="not_ok" value="ok"/>
    <include src="foobar.xmlt"/>
    <variableInclude name="foobar"/>

    <repeat name="RESULTS">
    hash key: ${_} 
    ${NUMBER}: ${RESULT}
    </repeat>
    
    <with name="nested_hash">
    ${result}
    </with>

    <with name="ENV">
    ${SCRIPT_NAME}
    </with>
 </template>

DESCRIPTION

The XML::Template module provides for assembling templates using a simple XML tag markup. The code is not limited to parsing XML documents. It works on any text document, including (of course) HTML, but is labeled as an XML template system because it uses XML tags for the markup used.

I don't pretend that this is a unique idea. There are *many* Perl template systems. What separates this one from the pack (AFAIK) is that it supports more than just variable substituion. Using XML markup, you can include other template files, perform simple variable assignment, nested namespaces, and best of all, perform simple looping constructs. For kicks, it also offers the CGI environment variables as builtins, as well as the server's current date, time and date/time string.

In short the module offers what I see as the 80/20 rule. It doesn't allow full Perl constructs (see something like ePerl or HTML::Embperl for that) but implements the 20% of the features that make up 80% of the needs for templates. It also serves as an excellent pre-processor for either ePerl or HTML::Embperl or the like. ;-)

To call it, simply call as shown in the synopsis. Arguments to new() are a directory where all XML template files are rooted possibly followed by an associative array of additional options. The ones currently supported are:

format => FMT   
  use FMT to format output messages produced by the parser; FMT
  is specified using the standard sprintf formats and defaults to 
  "<!-- %s -->\n"

The functions compose() and compose_string() take a hash reference and a filename (compose) or a string (compose_string) to parse and interpolate according to the hash. Any text inside any <template></template> tags will be interpreted. The remaining text will be completely ignored, useful for those situations where you want to use '$' characters, or simply want the parser to run faster.

The template language supports the following syntax:

<template></template> -- Define the sections of the file to interpret

$(variable) or ${variable} -- identifiers are word characters (including the underscore)

<include src="filename" /> -- filename is rooted by the path given at new()

<variableInclude name="variable"/> -- include the file pointed to by variable

<assign name="variable" value="..."/> -- assign "..." to identifier "variable" <assign value="..." name="variable"/>

<with name="nested"></with> -- use the nested hash for variable substitution.

<repeat name="nested"></repeat> -- repeat for every item in nested hash. If no name attribute is given, the items are selected from the root namespace.

The syntax for the namespaces specified with the "name" attribute of the <with> and <repeat> tags follow a syntax similar to XQL/XSL:

"/"              => root namespace $root
"/top/mid/bot"   => $root->{top}->{mid}->{bot}
"this/that"      => $current->{this}->{that}
"../above/below" => not supported (yet)
"ENV"            => environment variables

Anonymous arrays in the namespace structure are supported by using digits in path segments (note that initial index array is 0):

"/foo/2/bar"    => $root->{foo}->[0]->{bar}

In addition, variable substitution supports DATE, TIME, and NOW, the system's default date, time, and date-time strings.

AUTHOR

Geoff Hutchison <ghtuchis@wso.williams.edu>

SEE ALSO

ePerl(1), HTML::Embperl