---
name: "Template::Plugin::XML::DOM"
section: "3pm"
platform: "linux"
package: "libtemplate-plugin-xml-perl"
version: "2.17-6"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Template::Plugin::XML::DOM"
---

# Template::Plugin::XML::DOM(3pm)

Plugin interface to XML::DOM

## NAME

Template::Plugin::XML::DOM - Plugin interface to XML::DOM

## SYNOPSIS

```
    # load plugin
    [% USE dom = XML.DOM %]
    # also provide XML::Parser options
    [% USE dom = XML.DOM(ProtocolEncoding = 'ISO-8859-1') %]
    # parse an XML file
    [% doc = dom.parse(filename) %]
    [% doc = dom.parse(file = filename) %]
    # parse XML text
    [% doc = dom.parse(xmltext) %]
    [% doc = dom.parse(text = xmltext) %]
    # call any XML::DOM methods on document/element nodes
    [% FOREACH node = doc.getElementsByTagName('report') %]
       * [% node.getAttribute('title') %]   # or [% node.title %]
    [% END %]
    # define VIEW to present node(s)
    [% VIEW report notfound='xmlstring' %]
       # handler block for a <report>...</report> element
       [% BLOCK report %]
          [% item.content(view) %]
       [% END %]
       # handler block for a <section title="...">...</section> element
       [% BLOCK section %]
       <h1>[% item.title %]</h1>
       [% item.content(view) %]
       [% END %]
       # default template block converts item to string
       [% BLOCK xmlstring; item.toString; END %]

       # block to generate simple text
       [% BLOCK text; item; END %]
    [% END %]
    # now present node (and children) via view
    [% report.print(node) %]
    # or print node content via view
    [% node.content(report) %]
    # following methods are soon to be deprecated in favour of views
    [% node.toTemplate %]
    [% node.childrenToTemplate %]
    [% node.allChildrenToTemplate %]
```

## DESCRIPTION

This is a Template Toolkit plugin interfacing to the XML::DOM module. The plugin loads the XML::DOM module and creates an XML::DOM::Parser object which is stored internally.  The **parse()** method can then be called on the plugin to parse an XML stream into a DOM document.

```
    [% USE dom = XML.DOM %]
    [% doc = dom.parse('/tmp/myxmlfile') %]
```

The XML::DOM plugin object (i.e. 'dom' in these examples) acts as a sentinel for the documents it creates ('doc' and any others).  When the plugin object goes out of scope at the end of the current template, it will automatically call **dispose()** on any documents that it has created.  Note that if you dispose of the the plugin object before the end of the block (i.e.  by assigning a new value to the 'dom' variable) then the documents will also be disposed at that point and should not be used thereafter.

```
    [% USE dom = XML.DOM %]
    [% doc = dom.parse('/tmp/myfile') %]
    [% dom = 'new value' %]     # releases XML.DOM plugin and calls
                                # dispose() on 'doc', so don't use it!
```

The plugin constructor will also accept configuration options destined for the XML::Parser object:

```
    [% USE dom = XML.DOM(ProtocolEncoding = 'ISO-8859-1') %]
```

## METHODS

### parse()

The **parse()** method accepts a positional parameter which contains a filename or XML string.  It is assumed to be a filename unless it contains a \< character.

```
    [% xmlfile = '/tmp/foo.xml' %]
    [% doc = dom.parse(xmlfile) %]
    [% xmltext = BLOCK %]
    <xml>
      <blah><etc/></blah>
      ...
    </xml>
    [% END %]
    [% doc = dom.parse(xmltext) %]
```

The named parameters 'file' (or 'filename') and 'text' (or 'xml') can also be used:

```
    [% doc = dom.parse(file = xmlfile) %]
    [% doc = dom.parse(text = xmltext) %]
```

The **parse()** method returns an instance of the XML::DOM::Document object  representing the parsed document in DOM form.  You can then call any  XML::DOM methods on the document node and other nodes that its methods may return.  See XML::DOM for full details.

```
    [% FOREACH node = doc.getElementsByTagName('CODEBASE') %]
       * [% node.getAttribute('href') %]
    [% END %]
```

This plugin also provides an AUTOLOAD method for XML::DOM::Node which  calls **getAttribute()** for any undefined methods.  Thus, you can use the  short form of

```
    [% node.attrib %]
```

in place of

```
    [% node.getAttribute('attrib') %]
```

## PRESENTING DOM NODES USING VIEWS

You can define a VIEW to present all or part of a DOM tree by automatically mapping elements onto templates.  Consider a source document like the following:

```
    <report>
      <section title="Introduction">
        <p>
        Blah blah.
        <ul>
          <li>Item 1</li>
          <li>item 2</li>
        </ul>
        </p>
      </section>
      <section title="The Gory Details">
        ...
      </section>
    </report>
```

We can load it up via the XML::DOM plugin and fetch the node for the  \<report\> element.

```
    [% USE dom = XML.DOM;
       doc = dom.parse(file = filename);
       report = doc.getElementsByTagName('report')
    %]
```

We can then define a VIEW as follows to present this document fragment in  a particular way.  The Template::Manual::Views documentation contains further details on the VIEW directive and various configuration options it supports.

```
    [% VIEW report_view notfound='xmlstring' %]
       # handler block for a <report>...</report> element
       [% BLOCK report %]
          [% item.content(view) %]
       [% END %]
       # handler block for a <section title="...">...</section> element
       [% BLOCK section %]
       <h1>[% item.title %]</h1>
       [% item.content(view) %]
       [% END %]
       # default template block converts item to string representation
       [% BLOCK xmlstring; item.toString; END %]

       # block to generate simple text
       [% BLOCK text; item; END %]
    [% END %]
```

Each BLOCK defined within the VIEW represents a presentation style for  a particular element or elements.  The current node is available via the 'item' variable.  Elements that contain other content can generate it according to the current view by calling \[% item.content(view) %\]. Elements that don't have a specific template defined are mapped to the 'xmlstring' template via the 'notfound' parameter specified in the VIEW header.  This replicates the node as an XML string, effectively allowing general XML/XHTML markup to be passed through unmodified.

To present the report node via the view, we simply call:

```
    [% report_view.print(report) %]
```

The output from the above example would look something like this:

```
    <h1>Introduction</h1>
    <p>
    Blah blah.
    <ul>
      <li>Item 1</li>
      <li>item 2</li>
    </ul>
    </p>

    <h1>The Gory Details</h1>
    ...
```

To print just the content of the report node (i.e. don't process the 'report' template for the report node), you can call:

```
    [% report.content(report_view) %]
```

## AUTHORS

This plugin module was written by Andy Wardley and Simon Matthews.

The XML::DOM module is by Enno Derksen and Clark Cooper.  It extends the the XML::Parser module, also by Clark Cooper which itself is built on James Clark's expat library.

## COPYRIGHT

Copyright (C) 2000-2006 Andy Wardley, Simon Matthews.

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

## SEE ALSO

Template::Plugin, XML::DOM, XML::Parser