XML Templates

Mozilla also supports the use of XML datasources. An XML document will be loaded and XPath expressions may be used to take portions of the XML document and generate content from these. When an XML source is desired, specify a querytype attribute on the root node of the template to the value xml. This indicates to the template builder that an XML source is being used as that the queries use syntax that is specific to XML.

The datasources attribute should be set to the URL of an XML document, either a local file or a remote web site. The ref attribute isn't currently used for XML sources, as the root of the document is always the starting point for XML queries; you should just set the ref attribute to a dummy value, for example '*' which is typically used.

An example:

<listbox datasources="people.xml" ref="*" querytype="xml">
  <template>
    ...
  </template>
<listbox>

The URL in the datasources attribute may be a relative URL or an absolute URL.

Note: If you want to have the state of the disclosure triangles ("twisties") be persistent, be sure to give each node a unique "id" attribute. These are used to track the current state of the disclosure triangles. Support for this was introduced in Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4).

For this and the following examples, we are going to use the following XML document containing a list of people:

<people>
  <person name="Napoleon Bonaparte" gender="male"/>
  <person name="Cleopatra" gender="female"/>
  <person name="Julius Caesar" gender="male"/>
  <person name="Ferdinand Magellan" gender="male"/>
  <person name="Laura Secord" gender="female"/>
</people>

XML Query Syntax

The query syntax is fairly simple for XML datasources. Just place an expr attribute on the query element containing an XPath expression returns the set of results to output. Here is an example:

<listbox datasources="people.xml" ref="*" querytype="xml">
  <template>
    <query expr="person"/>
    <action>
      <listitem uri="?" label="?name"/>
    </action>
  </template>
</listbox>

The expr attribute is a very simple XPath expression which simply retrieves the person elements from within the datasource. As there are five in the XML document, five results will be generated. The action element defines the content to generate for each result. The content of the action element will be generated and repeated for each result, which in this case, is a listitem.

The child of the action element has to have a uri attribute, although it does not have to be a direct child. The element with the uri attribute and its children will be copied once for each result. Any elements between the action element and this element are only copied once. This is useful when recursive generation or multiple rules are used, and we'll see examples of why this is useful later. For an RDF query, the uri attribute specifies the member variable; for an XML query the member variable is always '?' so the value of the uri attribute for XML templates should always be the single question mark character as in this example.

The label attribute has been set to a special value ?name. When a question mark character followed by a string appears in an attribute value, the label value is not directly, but instead the value of an attribute for the source XML is used. For each node generated by the XPath expression used in the query, the attribute on the generated XML node is taken and substituted for the question mark and following string.

In the above example, the use of the ?name value, causes the name attribute on each result node to be used as the value of the label. You can see the name attributes in the original XML data above. This substitution occurs for any attribute within the action body, so you can also set other attributes with this technique.

In this example, an hbox element containing a button and a label is generated for each result.

<vbox datasources="people.xml" ref="*" querytype="xml">
  <template>
    <query expr="person"/>
    <action>
      <hbox uri="?" align="center">
        <button label="?name"/>
        <label value="?gender"/>
      </hbox>
    </action>
  </template>
</vbox>

Note how two attributes are substituted here, the label on the button and the value on the label.

The query does not have to be as simple as the one used here. Any XPath expression may be used. For instance, the following query returns only those results for female people.

<query expr="person[@gender='female']"/>

As long as the expression returns one or more nodes, it can be used in an query expression.

Using Inline XML

It's also possible to embed the XML data directly within the XUL document if desired. Instead of using a URL for the datasources attribute, you can use an anchor reference to refer to a node within the same document. The effect is the same, but the data isn't stored in a separate file.

<people id="famouspeople" xmlns="">
  <person name="Napoleon Bonaparte" gender="male"/>
  <person name="Cleopatra" gender="female"/>
  <person name="Julius Caesar" gender="male"/>
  <person name="Ferdinand Magellan" gender="male"/>
  <person name="Laura Secord" gender="female"/>
</people>

<listbox datasources="#famouspeople" ref="*" querytype="xml">
  <template>
    <query expr="person"/>
    <action>
      <listitem uri="?" label="?name"/>
    </action>
  </template>
</listbox>

Here, an anchor reference, starting with a number sign (#) is used for the datasources attribute. It refers to an element with that id (without the number sign) and uses that node as the source XML node instead of a separate file. Otherwise the data included inline and the template are the same. Note the only change is that the addition of the xmlns attribute on the data; this is used to clear the namespace used for the elements in the data, otherwise they become XUL elements. You can also specify a namespace. If so, you will need to ensure that prefixes are defined within the template as well, so that they can be used in the XPath expressions. The namespace prefixes that may be used in an XPath expression are those that are defined on the query or assign element where the expression is used.

Be aware that when XML data is included inline as in this example, the content may be displayed and may affect the layout of other parts of the window. You may wish to hide the inline XML by placing it inside a hidden box.