NAME

       Template::Plugin::XML - XML plugin for the Template Toolkit

SYNOPSIS

           [% USE XML;
              dom    = XML.dom('foo.xml');
              xpath  = XML.xpath('bar.xml');
              simple = XML.simple('baz.xml');
              rss    = XML.simple('news.rdf');
           %]

           [% USE XML(file='foo.xml');
              dom    = XML.dom
              xpath  = XML.xpath
              # ...etc...
           %]

           [% USE XML(dir='/path/to/xml');
              file  = XML.file('foo.xml' );
              dom   = file.dom
              xpath = file.xpath
              # ...etc...
           %]

DESCRIPTION

       The Template-XML distribution provides a number of Template Toolkit plugin modules for
       working with XML.

       The Template::Plugin::XML module is a front-end to the various other XML plugin modules.
       Through this you can access XML files and directories of XML files via the
       Template::Plugin::XML::File and Template::Plugin::XML::Directory modules (which subclass
       from the Template::Plugin::File and Template::Plugin::Directory modules respectively).
       You can then create a Document Object Model (DOM) from an XML file
       (Template::Plugin::XML::DOM), examine it using XPath queries
       (Template::Plugin::XML::XPath), turn it into a Perl data structure
       (Template::Plugin::XML::Simple) or parse it as an RSS (RDF Site Summary) file.

       The basic XML plugins were distributed as part of the Template Toolkit until version 2.15
       released in May 2006.  At this time they were extracted into this separate Template-XML
       distribution and an alpha version of this Template::Plugin::XML front-end module was
       added.

       The Template::Plugin::XML module is still in development and not guaranteed to work
       correctly yet.  However, all the other XML plugins are more-or-less exactly as they were
       in TT version 2.14 and should work as normal.

       For general information on the Template Toolkit see the documentation for the Template
       module or <http://template-toolkit.org>.  For information on using plugins, see
       Template::Plugins and "USE" in Template::Manual::Directives.  For further information on
       XML, see <http://xml.com/>.

METHODS

       The XML plugin module provides a number of methods to create various other XML plugin
       objects.

       file(name)

       Creates a Template::Plugin::XML::File object.  This is a subclass of
       Template::Plugin::File.

       dir(path)

       Creates a Template::Plugin::XML::Directory object.  This is a subclass of
       Template::Plugin::Directory.

       dom()

       Generate a Document Object Module from an XML file.  This can be called against a
       directory, file or an XML plugin object, as long as the source XML filename is defined
       somewhere along the line.

           [% dom = XML.dom(filename) %]

           [% file = XML.file(filename);
              dom  = file.dom
           %]

           [% dir = XML.dir(dirname);
              dom = dir.dom(filename)
           %]

       xpath()

       Perform XPath queries on the file.  Like the dom() method, xpath() can be called against a
       file, directory or an XML plugin object.

           [% xpath = XML.xpath(filename) %]

           [% file  = XML.file(filename);
              xpath = file.xpath
           %]

           [% dir   = XML.dir(dirname);
              xpath = dir.xpath(filename)
           %]

       simple()

       TODO: As per dom() and xpath() but for XML::Simple

       rss()

       TODO: As per dom(), xpath() and simple() but for XML::RSS

XML PLUGINS

       These are the XML plugins provided in this distribution.

       Template::Plugin::XML

       Front-end module to the XML plugin collection.

       Template::Plugin::XML::File

       This plugin module is used to represent individual XML files.  It is a subclass of the
       Template::Plugin::File module, providing the additional dom(), xpath(), simple() and other
       methods relevant to XML files.

       Template::Plugin::XML::Directory

       This plugin module is used to represent directories of XML files.  It is a subclass of the
       Template::Plugin::Directory module and provides the same additional XML related methods as
       Template::Plugin::XML::File.

       Template::Plugin::XML::DOM

       Plugin interface providing access to the XML::DOM module.

           [% USE XD = XML.Dom %]
           [% dom = XD.parse_file('example.xml') %]
           [% pages = dom.getElementsByTagName('page') %]

       Template::Plugin::XML::RSS

       Plugin interface providing access to the XML::RSS module.

           [% USE news = XML.RSS('news.rdf') -%]
           [% FOREACH item IN news.items -%]
              * [% item.title %]
           [% END %]

       Template::Plugin::XML::Simple

       Plugin interface providing access to the XML::Simple module.

           [%  USE xml = XML.Simple('example.xml') %]

       Template::Plugin::XML::XPath

       Plugin interface providing access to the XML::XPath module.

           [% USE xpath = XML.XPath('example.xml');
              bar = xpath.find('/foo/bar');
           %]

AUTHORS

       Andy Wardley wrote the Template Toolkit plugin modules, with assistance from Simon
       Matthews in the case of the XML::DOM plugin.  Matt Sergeant wrote the XML::XPath module.
       Enno Derksen and Clark Cooper wrote the XML::DOM module.  Jonathan Eisenzopf wrote the
       XML::RSS module.  Grant McLean wrote the XML::Simple module.  Clark Cooper and Larry Wall
       wrote the XML::Parser module.  James Clark wrote the expat library.

COPYRIGHT

       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

SEE ALSO

       Template, Template::Plugins, Template::Plugin::XML::DOM, Template::Plugin::XML::RSS,
       Template::Plugin::XML::Simple, Template::Plugin::XML::XPath