XML::Template v3.20 Copyright (c) 2002-2003 Jonathan A. Waxman. All rights reserved. This is free software; you can redistribute it and/or modify it under the same terms as Perl itself. OVERVIEW -------- XML::Template is an X(HT)ML-based document processing framework written in Perl designed specifically for constructing web sites and web applications. The essential framework of XML::Template provides XML document parsing and caching services; scalar, array, and nested variables; and XPath support. Plug-in modules written in Perl may be easily added to extend the available tag set using XML namespace conventions. XML::Template comes with numerous standard plug-in modules including modules for variable iteration, conditionals, exception handling, and performing abstract database queries and iterations. The intention of XML::Template is to provide a simple and consistent framework for developing dynamic web sites and web applications entirely in XHTML. There are many excellent options available that can approximately do this; however, at the time I started writing this, I was unable to find anything that offered exactly what I wanted and what XML::Template provides. Even today, I am still unsatisfied with all the other alternatives, but that is another discussion. Because of its modularity, no particular design strategy or tagset is imposed on the user, however, the standard modules that come with XML::Template provide suggestive design elements. In particular, special attention is given to database integration and modular design strategies. XML::Template comes with a web site administrator and content management application, siteadmin, designed entirely using the XML::Template framework and standard modules. It offers a powerful example of the kind of web application that XML::Template can be used to create. FEATURES -------- o Written entirely in Perl. o Highly modular and extensible design. o Templates are converted to Perl code and cached to files resulting in extremely fast performance. o Supports scalar, array, nested (hash), and XPath variables and variable subroutines. o Support variable tags. This feature allows variable substitution in an actual tagname itself, so the tag that gets used can be defined dynamically. o Easy to extend the tagset using XML namespace conventions. o Highly configurable via system-wide and host-specific XML configuration files. Multiple virtual hosts and data sources can be defined. Namespace configuration supports alternate attribute parsers, attribute type checking, nested and "related" tag specification, and body content attributes. o Standard modules include support for conditionals, mail, exceptions, file inclusion and IO, variables, variable and abstract iterators, forms, and DBI database queries. The database modules include support for data items, groups, XHTML blocks, and users. o Special attention given to database support - very little if any SQL is necessary to perform the most common kinds of database queries. Related database table queries are supported using the concept of related namespaces. o Exception handling and exception XHTML template support. INSTALLATION ------------ The latest version of XML::Template can be obtained from: http://www.cpan.org/modules/by-module/XML-Template/ See INSTALL for detailed installation instructions. BRIEF TUTORIAL -------------- 1. X(HT)ML ----------- XML Specification: http://www.w3.org/TR/REC-xml XML in 10 Points: http://www.w3.org/XML/1999/XML-in-10-points XHTML Specification: http://www.w3.org/TR/xhtml1/ XML::Template is an X(HT)ML framework for developing dynamic web sites and applications written entirely in Perl. The format of XML::Template documents is entirely XML. XML::Template provides the basic XML document parsing and caching services. 2. Namespaces -------------- Specification: http://www.w3.org/TR/REC-xml-names/ XML namespaces provides the means by which the tag set available to an XML::Template document is extended. The details of the namespace are defined in the XML::Template configuration file. For instance, here is an example namespace definition from an XML::Template configuration file: test Test Test elements. XML::Template::Element::Test empty yes no ^\d+$ XML::Template::Parser::TestAtt2 The configuration defines variious attributes of the namespace, such as the description and the actual Perl module that provides the implementation. You can also define optional attributes and constraints on the elements in the namespace and on the attributes of the elements. More detailed documentation is provides in the sample configuration file that comes with the XML::Template distribution, or in the POD document XML::Template::xml-template.conf. Here's an example of an XML::Template document that uses the above namespace: The following are elements from the test namespace:

3. XML::Template Variables --------------------------- XML::Template provides scalar, array, nested, and XPath variables. Additionally, subroutines can be defined which operate on variable values. Scalar Variables ---------------- Scalar variables are simple variables that contain a single value. They look like this: ${}, where is the name of the scalar variable. For instance, The value of the variable named name: ${name} To set the value of a scalar variable, you need to use the set element from the var namespace: Jonathan Waxman Array Variables --------------- Array variables contain a sequence or array of values. They look like: ${[]}, where is the name of the array variable and is an integer index. For instance, First name: ${names[0]}
Second name: ${names[1]}
Third name: ${names[2]}
Fourth name: ${names[3]} ...
To set an array variable, you need to use the set and element elements of the var namespace: Goose Kristina Clair Josh Marcus Jonathan Waxman Nested Variables ---------------- A nested variable is a named variable nested in another named variable. They look like: ${.}, where is the name of the variable nested within the variable named . Variables can be nested to an arbitrary depth. For instance, First name: ${name.first}
Last name: ${name.last}
Street address: ${name.address.street}
To set a nest variable, you need to use the name and element elements from the var namespace: Jonathan Waxman 123 Street Road XPath Variables --------------- An XPath variable is a variable that extracts a part of an XML document using an XPath query. They look like: ${/}, where is the name of the variable that contains the XML document and is an XPath query. Suppose you set the value of a variable to some XML: Jonathan Waxman

123 Street Road Philadelphia
You can access different parts of the XML document stored in the variable "xml" using XPath expressions. Some examples: ${xml/person[@username="jowaxman"/firstname} ${xml/person/@username} Mixed Variables --------------- You can mix all the different variable types. You can also use variables inside of variables. For instance, ${person[${index}].xml/info[@type="personal"]} ${person.${names[1]}.address} If a variable name contains "." or "/", you can either backslash them, or surround the text they are embedded within by curly braces. This is especially useful if the variable name comes from another variable. For instance, ${person.Jonathan\.Waxman.address}
${person.{Jon/athan.Waxman}.address}
${person.{${name}}.address}
Subroutines ----------- Subroutines can be defined to operate on the values of variables. They look like: ${}. or ${}. (), where is some variable, is the subroutine name, and is an optional comma-separated list of parameters to the subroutine. For instance, Today's date: ${date}.format ("%D %T") ${array}.push ("element") last element: ${array}.pop Subroutines are defined in the XML::Template configuration file. Here is an example: Whether a value is defined. XML::Template::Util Format a date. XML::Template::Util Push onto an array. XML::Template::Element::Var Pop off an array. XML::Template::Element::Var