NAME

Text::TagTemplate - Perl text template instantiation

SYNOPSIS

  use Text::TagTemplate;
  my %namespace = (
	      foo => "bar",
  );

 my $interp = Text::TagTemplate->new("examples", format => "<!-- %s -->");
 my $interp = Text::TagTemplate->new("examples", format => "<!-- %s -->", debug => 1);
 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 Text::TagTemplate module provides for assembling templates using a simple XML-like tag markup. It works on any text document, including (of course) HTML and XML. Previous versions were distributed as XML::Template, but this was a misnomer because it is not really XML.

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

debug => mode
  use the debug switch to include non-interpretable code in the output;
  mode can be 1 (on) or 0 (off), default setting is 0 (off).
  (NOTE: up to Version 1.1.0 the debug mode was set by default.)

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

<ifdefined name="variable"></ifdefined> -- interpret only if the variable is defined in the namespace ( = the variable exists with a defined value )

<ifundefined name="variable"></ifundefined> -- interpret if the variable is undefined in the namespace ( = doesn't exist or has an undefined value )

The syntax for the namespaces specified with the "name" attribute of the <with>, <repeat>, <ifdefined> and <ifundefined> 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}->[1]->{bar}

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

AUTHOR

Geoff Hutchison <ghutchis@wso.williams.edu>

SEE ALSO

ePerl, HTML::Embperl