Microsummary XML grammar reference

A microsummary generator is an XML document that describes how to pull specific information from a web page to be presented in summary form as a bookmark whose title changes based on the content of the page it targets.

This article provides detailed information about the XML grammar used to build microsummary generators, describing each element and their attributes. For an introduction to how to create a microsummary, read the article Creating a Microsummary.

Example

The microsummary generator created in the Creating a Microsummary tutorial:

<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Firefox Download Count">
  <template>
    <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0">
      <output method="text"/>
      <template match="/">
        <value-of select="id('download-count')"/>
        <text> Fx downloads</text>
      </template>
    </transform>
  </template>
  <pages>
    <include>https://(www\.)?spreadfirefox\.com/(index\.php)?</include>
  </pages>
</generator>

Namespace

The namespace URI for microsummary generator XML documents is:

https://www.mozilla.org/microsummaries/0.1

All elements in a microsummary generator document should be in this namespace except the descendants of the <template> element, which should be in the XSLT namespace:

https://www.w3.org/1999/XSL/Transform

The <generator> element

The <generator> element is the root tag for all microsummary generators, and should contain the remainder of the XML code describing the generator.

Attributes:

name (required)

A descriptive, human-readable name for the microsummary created by the generator.

uri (optional)

A valid URI uniquely identifying the generator. Only relevant for generators dynamically created by Firefox code and extensions. Generators installed from the web via nsSidebar::addMicrosummaryGenerator are identified by the remote URL from which they were downloaded, and Firefox ignores the value of this attribute for them.

Child Elements:

<template> (required)

Defines how to transform pages into their microsummaries.

<pages> (required)

Identifies the set of pages that the generator is able to summarize.

<update> (optional)

Specifies how frequently Firefox should update the microsummaries.

The <template> element

The <template> element contains the XSLT stylesheet which transforms web pages into their microsummaries.

Attributes:

None.

Child Elements:

<stylesheet> or <transform> (required)

The XSLT stylesheet which performs the transformation.

Per XSLT, you may specify the stylesheet child element using either the <stylesheet> or the <transform> tag, which are interchangeable.

The <pages> element

The <pages> element identifies the set of pages that the generator is able to summarize.

Attributes:

None.

Child Elements:

<include> (optional)

A regular expression matching the URLs of pages that the generator is able to summarize.

<exclude> (optional)

A regular expression matching the URLs of pages that the generator is not able to summarize.

The <pages> element can contain zero or more <include> and <exclude> child elements, each of which must contain a valid JavaScript-compatible regular expression. It must not contain any other elements, and it does not have any attributes.

When a generator is examined to determine whether or not it is able to summarize a page, the regular expressions provided by the child elements are evaluated against the URL of the page. A generator is considered to be able to summarize a page if at least one of the <include> expressions matches the URL of the page and none of the <exclude> expressions match the URL of the page.

The order in which child elements appear within the <pages> element is not significant. White space between the child element tags and the regular expressions they contain is also not significant; it is not considered part of the regular expression, and it does not affect evaluation of the expressions.

The following example identifies a generator as being able to summarize all pages on the www.example.com web site except pages named about.html:

<pages>
  <include>
    ^https://www\.example\.com/
  </include>
  <exclude>/about\.html</exclude>
</pages>

See the reference Core_JavaScript_1.5_Reference:Global_Objects:RegExp for the details of the regular expression syntax valid for generators and the tutorial Creating regular expressions for a microsummary generator for step by step instructions to writing regular expressions that match URLs.

The <include> element

The <include> element identifies a set of pages that the generator is able to summarize. It must be a child of the <pages> element, and it must contain a JavaScript-compatible regular expression.

For more information about the use of this element, see the entry for #The_<pages>_element.

The <exclude> element

The <exclude> element identifies a set of pages that the generator is not able to summarize. It must be a child of the <pages> element, and it must contain a JavaScript-compatible regular expression.

For more information about the use of this element, see the entry for #The_<pages>_element.

The <update> element

The optional <update> element specifies how frequently Firefox should update microsummaries generated by the generator. The element can be used to specify both an absolute update interval and a series of conditional intervals based on the content of the page being summarized.

Attributes:

interval (optional)

An absolute interval of time, in minutes, that must elapse between updates.

Child Elements:

<condition> (optional)

An XPath boolean expression along with a conditional interval of time, in minutes, that must elapse between updates if the expression evaluates to true.

The interval attribute defines an absolute interval in minutes. Its value must be a number greater than or equal to 1. Fractional values (e.g. 5.5 minutes) are permitted, although they probably aren't useful.

The <update> element may contain any number of <condition> child elements.

Firefox determines which interval to apply to a microsummary generated by a generator according to the following rules:

1. Firefox processes each <condition> child element in document order. For each one, Firefox evaluates the element's XPath boolean expression against the page being summarized. If the expression evaluates to true, Firefox applies that element's interval and stops processing child elements. Thus, the first matching <condition> determines the update interval.
2. If there are no <condition> child elements, or if none of their expressions evaluate to true, Firefox applies the value of the <update> element's interval attribute.
3. If the <update> element does not include an interval attribute, Firefox applies the interval specified by the browser.microsummary.updateInterval preference.
4. If that preference has not been set, Firefox applies its default update interval, which is 30 minutes.

Notes:

• regardless of the absolute or conditional update interval specified by this element, Firefox will never update microsummaries more frequently than once per minute;
• because Firefox checks for expired microsummaries every 15 seconds, it is possible for a microsummary update to begin up to 15 seconds later than its interval indicates;
• Firefox respects the browser cache when updating microsummaries, so it will not reload a page to update its microsummary if the cache contains a fresh copy of the page.

The <condition> element

The optional <condition> element specifies an XPath boolean expression along with a conditional interval of time, in minutes, that must elapse between updates if the expression evaluates to true when evaluated against the page being summarized. It must be a child of the <update> element.

Attributes:

expression (required)

An XPath boolean expression to be evaluated against the page being summarized.

interval (required)

An interval of time, in minutes, that must elapse between updates if the expression evaluates to true.

Child Elements:

None.

For more information about the use of this element, see the entry for the <update> element.

See also

• Creating a Microsummary
• XSLT