GetXML Plugin for Movable Type

Current version: 1.1 (7/12/04)

• Download (.tar.gz file)
• Plugin Code (.pl file)
• About the GetXML Plugin
• Accessing XML Data
• MTGetXML
• MTGetXMLElement
• MTGetXMLValue
• MTIfXMLElementExists
• MTIfXMLElementNotExists
• MTGetXMLElementCount
• MTGetXMLElementIndex
• MTGetXMLURL
• MTGetXMLCacheDate
• MTGetXMLDump
• space_to_plus
• Usage Examples
• Version History

About the GetXML Plugin

This Movable Type plugin implements a set of template tags for retrieving data in XML format and displaying the data on your MT-generated pages. It's basically a Movable Type interface to the extremely handy XML::Simple Perl module. The plugin will work with any well-formed XML document that can be retrieved via an HTTP GET request.

The GetXML plugin is extremely generalized, and to use it you'll have to understand the structure of the XML data you want to work with. There are specific MT plugins available for certain particular types of XML data, such as RSS feeds, Amazon content, and weather forecasts. If there's a specific plugin out there for the XML resource you're interested in, by all means use it instead. GetXML is intended for XML data for which no plugin exists yet, or whose structure is simple enough that it might not merit its own plugin.

Requirements

To cache XML data, the GetXML plugin uses a feature of Movable Type (MT::PluginData) that was introduced in MT version 2.6. If you're using an earlier version, the plugin will work, but will not do any caching.

The GetXML plugin uses the following Perl modules:

• LWP::Simple (this module, in turn, requires several other modules, which are installed as part of the LWP package)
• XML::Simple
• XML::Parser (used by XML::Simple)
• Storable (optional; used for caching; if Storable is not installed, GetXML will work but will not do any caching)
• Data::Dumper (optional; only needed if you want to use the MTGetXMLDump tag)

Installation

To install the GetXML plugin, upload the file GetXML.pl to the plugins directory within your Movable Type directory. If you do not already have a plugins directory, create one before uploading the file. For more information about Movable Type plugins, see the documentation.

Support

Please use the support forums for all support requests, bug reports, feature requests, questions, and comments regarding this plugin.

Accessing XML Data

An XML document consists of tagged elements. An element can contain either a piece of text (a simple element), or it can contain other elements and/or attributes (a complex element).

The MTGetXMLValue tag displays the text of a simple element. The MTGetXMLElement container tag lets you access the elements contained within a complex element. Within an MTGetXMLElement container, the tags that take an element name—MTGetXMLElement, MTGetXMLValue, MTIfElementExists, MTIfXMLElementNotExists, and MTGetXMLElementCount—refer to the elements nested within the element. You can nest MTGetXMLElement tags as deeply as necessary.

If a tag contains a text value and also contains other elements or attributes, the text value will be treated as a nested element with the name content.

An element may have "sibling" elements with the same name, within the same contaning element. If this is the case, MTGetXMLElement will loop through all the sibling elements, displaying its contents once for each.

Let's look at an example XML document:

<?xml version="1.0"?>
<sportspicks xmlns="http://example.com/sports.dtd">
 <title>Bob's Daily Picks</title>
 <game sport="basketball">
  <hometeam>Knicks</hometeam>
  <awayteam>Celtics</awayteam>
  <spread source="vegas">Knicks by 6</spread>
  <pick>Knicks</pick>
 </game>
 <game sport="basketball">
  <hometeam>Pistons</hometeam>
  <awayteam>Spurs</awayteam>
  <spread source="vegas">Pistons by 10</spread>
  <pick>Pistons</pick>
 </game>
</sportspicks>

Here's the MT template code you might use to display this data with the GetXML plugin:

<MTGetXML location="http://example.com/sportspicks.xml">
 <p><$MTGetXMLValue name="title"$></p>
 <MTGetXMLElement name="game">
  <$MTGetXMLValue name="awayteam"$> at <$MTGetXMLValue name="hometeam"$> 
  <MTGetXMLElement name="spread">
   (spread: <$MTGetXMLValue name="content"$>)<br> 
  </MTGetXMLElement>
  Bob's pick: <$MTGetXMLValue name="pick"$>
 </MTGetXMLElement>
</MTGetXML>

A couple of things to note about this example:

• There's no need to use an outer <MTGetXMLElement name="sportspicks"> container, because by default the plugin omits the XML document's root element. If you do want to include the root element, pass keeproot="1" to MTGetXML.
• Because the spread tag has an attribute, the element is treated as a complex element, so the tag's value has to be accessed as if it were a nested element called content.

There are two special ways to access a set of sibling simple elements.

• If you're looping through a set of simple elements, you can use MTGetXMLValue without passing an element name:

  <ingredient>2 cans tomatoes</ingredient>
  <ingredient>1/3 cup sliced olives</ingredient>
  <ingredient>6 oz. feta cheese</ingredient>
  <ingredient>2 Tbsp olive oil</ingredient>

  <MTGetXMLElement name="ingredient">
   <$MTGetXMLValue$><br>
  </MTGetXMLElement>

• If a set of sibling elements consists of only simple elements, you can use MTGetXMLValue directly to display the values of all the sibling elements, strung together. This is useful in cases where an element's content is interspersed with other elements, in which case you end up with the text broken up into multiple content elements. (This is true in the Bible example below.)

MTGetXML

This container tag is the master tag that tells the plugin to retrieve and interpret an XML document. All the other tags must go within MTGetXML.

You can specify the location of the XML document in one of two ways. You can simply put the entire location into the location attribute, or you can pass only the base URL in location and also pass any number of other attributes that will be used as arguments to construct a query string. For example, given this code:

<MTGetXML location="http://machine.somewhere.com/services/funxml.cgi" year="1973" zip="11201">
..
</MTGetXML>

the plugin will attempt to load the following URL:

http://machine.somewhere.com/services/funxml.cgi?year=1973&zip=11201

Both the location attribute and the argument attributes can contain MT template code, with square brackets instead of angle brackets and single quotes instead of double quotes. (To include a literal square bracket or single quote, escape it by preceding it with a backslash.) Any MT template tags within these attributes will be evaluated and the resulting text will be used in the location.

The tag takes the following attributes:

• location="url" (required)
  The full location of the XML document, or the base URL to which the argument attributes will be added.
• [argument]="value" (optional)
  An argument to be added to the base location URL.
• cache="N" (optional)
  To avoid retrieving the same XML repeatedly in rapid succession, the plugin caches each retrieved document in MT's database. By default, the cached copy will be used if the template is rebuilt again within 15 minutes, after which the plugin will re-request the document. To keep the cached copy for a different length of time, use the cache attribute. The cached copy will be used for N minutes. If you don't want the plugin to cache the document at all, pass cache="0". To change the default caching duration, edit this line toward the top of the GetXML.pl file:

  my $DEFAULT_CACHE_MINS = 15;

• errors="display|warn|die|ignore" (optional)
  This setting tells the plugin what to do if an error occurs in getting the XML document: either the specified URL cannot be retrieved, or the XML document is not well-formed and cannot be parsed. Which option you use in a given situation will depend on the context in which you're using the XML data.
  • display: (default) MTGetXML will display an error message on the built page. The template rebuild will proceed.
  • warn: The template rebuild will proceed, and a warning message containing the error will be shown in the rebuild window. MTGetXML will not display anything.
  • die: The template rebuild will be aborted and an error message will be shown in the rebuild window.
  • ignore: MTGetXML will not display anything, and the error will not be reported.

  To change the default setting, edit this line toward the top of the GetXML.pl file:

  my $DEFAULT_ERRORS = 'display';

• keeproot="1" (optional)
  By default, XML::Simple omits the outermost, or root, element when parsing an XML document. Pass keeproot="1" to make XML::Simple include the root element (in which case you'll need to use an extra MTGetXMLElement container in order to access the data).
• suppressempty="1" (optional)
  By default, if an XML element is empty (containing nothing, or only whitespace), XML::Simple will include an empty element in the parsed data structure, meaning that MTIfElementExists will consider that element to exist. Pass suppressempty="1" if you want empty elements to be omitted entirely.
• noattr="1" (optional)
  By default, XML::Simple treats attributes to XML tags as nested elements. For example, take the following XML:

  <title language="english">A Book of Verses</title>

  In order to display the title, you would have to use this code:

  <MTGetXMLElement name="title">
   <$MTGetXMLValue name="content"$>
  </MTGetXMLElement>

  If you're not concerned with the data contained in the attributes, you can pass noattr="1" and XML::Simple will ignore attributes entirely, meaning you could display the title more directly, like this:

  <$MTGetXMLValue name="title"$>

MTGetXMLElement

This container tag lets you access the elements and attributes within a complex element, and loop through a series of sibling elements.

The tag takes the following attributes:

• name="value" (required)
  The name of the element.
• limit="N" (optional)
  When looping through a series of sibling elements, use this attribute to display only the first N elements.

MTGetXMLValue

This tag displays the value of a simple element.

The tag takes the following attributes:

• name="value" (usually required)
  The name of the element. Can be omitted if the containing MTGetXMLElement tag is looping through a set of sibling elements that are all simple elements.
• errors="display|warn|die|ignore" (optional)
  If you try to use MTGetXMLValue to display an element that's actually a complex element containing multiple values, the plugin will treat this as an error. The errors attribute determines how the error will be handled. The options are the same as described above under the errors attribute of MTGetXML.

MTIfXMLElementExists

This container tag displays its contents if and only if the specified element exists at the current level. (Note that the element does not have to contain anything; see the suppressempty attribute to MTGetXML if you don't want empty elements to be considered to exist.)

The tag takes the following attribute:

• name="value" (required)
  The name of the element.

MTIfXMLElementNotExists

This container tag displays its contents if and only if the specified element does not exist at the current level.

The tag takes the following attribute:

• name="value" (required)
  The name of the element.

MTGetXMLElementCount

This tag displays the total number of sibling elements with the specified name that exist at the current level.

The tag takes the following attribute:

• name="value" (required)
  The name of the element(s).

MTGetXMLElementIndex

Within an MTGetXMLElement container that's looping through multiple sibling elements, this tag displays the index of the current loop iteration.

The tag takes the following attribute:

• name="value" (required)
  The name of the element.

MTGetXMLURL

This tag displays the URL of the XML document that MTGetXML retrieved. This is useful if you're using MT template tags within the URL and aren't sure of the built values of the tags.

MTGetXMLCacheDate

This tag displays the date and time the XML document was last cached (it will display [Not cached] if the document has not been cached). Like other MT date tags, MTGetXMLCacheDate takes format and language attributes. See Date Tag Formats in the MT documentation for more information.

<MTGetXML location="http://example.com/searchengine.cgi" q="[MTEntryTitle space_to_plus='1']">
...
</MTGetXML>

http://example.com/searchengine.cgi?q=Some+Thoughts+on+Cornflakes