mozilla

Revision 87563 of Microsummary XML grammar reference

  • Revision slug: Microsummary_XML_grammar_reference
  • Revision title: Microsummary XML grammar reference
  • Revision id: 87563
  • Created:
  • Creator: MykMelez
  • Is current revision? No
  • Comment flushing out the section for the <pages> element
Tags: 

Revision Content

{{template.Draft()}}

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.

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.

It has the following 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.

The <pages> element

The <pages> element identifies the set of pages that the generator is able to summarize. It must contain a sequence of 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>
    ^http://www\.example\.com/
  </include>
  <exclude>/about\.html</exclude>
</pages>

Note: regular expressions intended to match the beginnings of page URLs should start with the caret (^) to ensure they do not inadvertently match URLs which merely contain the URLs they intend to match. For example, the regular expression http://www\.example\.com/ matches both the URL http://www.example.com/ and the URL http://www.evil.com/http://www.example.com/, but the regular expression ^http://www\.example\.com/ matches only the first of those two URLs.

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 <update> element lets the generator specify values describing how often Firefox should check to see if there's a newer version of the generator, as well as where to look for the update. The following attributes are available:

interval
The time interval, in minutes, that should elapse between looking for an updated version of the generator. The interval must be at least 1 minute. The interval can include a fractional part (such as 5.5 minutes), although that's not necessarily useful.

Microsummaries are checked to see if it's time to refresh them every 15 seconds, so it's possible that the refresh may take place as much as 15 seconds later than the specified interval.

Conditional update intervals

If you wish to provide conditions under which the update interval can vary, you can do so by placing <condition> tags inside the <interval> section. These have the following syntax:

 <condition> expression="expr" interval="interval"</condition<&gt>
expression
An XPath Boolean expression to evaluate. If it evaluates to true, the given interval is applied.
interval
The interval to apply if expr evaluates to true.

The <template> element

The <template> element is used to wrap a set of XSLT transform sheets that do the job of translating the document contents into the format to be displayed in the microsummary. It has the following attributes:

match
Defines the node of the document to which the transform should be applied.

The <template> tag should contain the XSLT transform.

See also

Revision Source

<p>{{template.Draft()}}
</p><p>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.
</p><p>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 <a href="en/Creating_a_Microsummary">Creating a Microsummary</a>.
</p>
<h2 name="The_.3Cgenerator.3E_element">The <code>&lt;generator&gt;</code> element</h2>
<p>The <code>&lt;generator&gt;</code> element is the root tag for all microsummary generators, and should contain the remainder of the XML code describing the generator.
</p><p>It has the following attributes:
</p>
<dl><dt> <code>name</code> (required)
</dt><dd> A descriptive, human-readable name for the microsummary created by the generator.
</dd><dt> <code>uri</code> (optional)
</dt><dd> A valid URI uniquely identifying the generator.  Only relevant for generators dynamically created by Firefox code and extensions.  Generators installed from the web via <code>nsSidebar::addMicrosummaryGenerator</code> are identified by the remote URL from which they were downloaded, and Firefox ignores the value of this attribute for them.
</dd></dl>
<h2 name="The_.3Cpages.3E_element">The <code>&lt;pages&gt;</code> element</h2>
<p>The <code>&lt;pages&gt;</code> element identifies the set of pages that the generator is able to summarize.  It must contain a sequence of zero or more <code>&lt;include&gt;</code> and <code>&lt;exclude&gt;</code> 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.
</p><p>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 <code>&lt;include&gt;</code> expressions matches the URL of the page and none of the <code>&lt;exclude&gt;</code> expressions match the URL of the page.
</p><p>The order in which child elements appear within the <code>&lt;pages&gt;</code> 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.
</p><p>The following example identifies a generator as being able to summarize all pages on the <code>www.example.com</code> web site except pages named <code>about.html</code>:
</p>
<pre class="eval">&lt;pages&gt;
  &lt;include&gt;
    <span class="plain">^http://www\.example\.com/</span>
  &lt;/include&gt;
  &lt;exclude&gt;/about\.html&lt;/exclude&gt;
&lt;/pages&gt;
</pre>
<p>Note: regular expressions intended to match the beginnings of page URLs should start with the caret (^) to ensure they do not inadvertently match URLs which merely contain the URLs they intend to match.  For example, the regular expression <code><span class="plain">http://www\.example\.com/</span></code> matches both the URL <code><span class="plain">http://www.example.com/</span></code> and the URL <code><span class="plain">http://www.evil.com/http://www.example.com/</span></code>, but the regular expression <code><span class="plain">^http://www\.example\.com/</span></code> matches only the first of those two URLs.
</p><p>See the reference <a href="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp">Core_JavaScript_1.5_Reference:Global_Objects:RegExp</a> for the details of the regular expression syntax valid for generators and the tutorial <a href="en/Creating_regular_expressions_for_a_microsummary_generator">Creating regular expressions for a microsummary generator</a> for step by step instructions to writing regular expressions that match URLs.
</p>
<h2 name="The_.3Cinclude.3E_element">The <code>&lt;include&gt;</code> element</h2>
<p>The <code>&lt;include&gt;</code> element identifies a set of pages that the generator is able to summarize.  It must be a child of the <code>&lt;pages&gt;</code> element, and it must contain a JavaScript-compatible regular expression.
</p><p>For more information about the use of this element, see the entry for <a href="#The_.3Cpages.3E_element">#The_&lt;pages&gt;_element</a>.
</p>
<h2 name="The_.3Cexclude.3E_element">The <code>&lt;exclude&gt;</code> element</h2>
<p>The <code>&lt;exclude&gt;</code> element identifies a set of pages that the generator is not able to summarize.  It must be a child of the <code>&lt;pages&gt;</code> element, and it must contain a JavaScript-compatible regular expression.
</p><p>For more information about the use of this element, see the entry for <a href="#The_.3Cpages.3E_element">#The_&lt;pages&gt;_element</a>.
</p>
<h2 name="The_.3Cupdate.3E_element">The <code>&lt;update&gt;</code> element</h2>
<p>The <code>&lt;update&gt;</code> element lets the generator specify values describing how often Firefox should check to see if there's a newer version of the generator, as well as where to look for the update.  The following attributes are available:
</p>
<dl><dt> <code>interval</code>
</dt><dd> The time interval, in minutes, that should elapse between looking for an updated version of the generator.  The interval must be at least 1 minute.  The interval can include a fractional part (such as 5.5 minutes), although that's not necessarily useful.
</dd></dl>
<p>Microsummaries are checked to see if it's time to refresh them every 15 seconds, so it's possible that the refresh may take place as much as 15 seconds later than the specified interval.
</p>
<h3 name="Conditional_update_intervals">Conditional update intervals</h3>
<p>If you wish to provide conditions under which the update interval can vary, you can do so by placing <code>&lt;condition&gt;</code> tags inside the <code>&lt;interval&gt;</code> section.  These have the following syntax:
</p>
<pre class="eval"> &lt;condition&gt; expression="<i>expr</i>" interval="<i>interval</i>"&lt;/condition&lt;&amp;gt&gt;
</pre>
<dl><dt> <code>expression</code>
</dt><dd> An XPath Boolean expression to evaluate.  If it evaluates to <code>true</code>, the given <code>interval</code> is applied.
</dd><dt> <code>interval</code>
</dt><dd> The interval to apply if <i>expr</i> evaluates to <code>true</code>.
</dd></dl>
<h2 name="The_.3Ctemplate.3E_element">The <code>&lt;template&gt;</code> element</h2>
<p>The <code>&lt;template&gt;</code> element is used to wrap a set of XSLT transform sheets that do the job of translating the document contents into the format to be displayed in the microsummary.  It has the following attributes:
</p>
<dl><dt> <code>match</code>
</dt><dd> Defines the node of the document to which the transform should be applied.
</dd></dl>
<p>The <code>&lt;template&gt;</code> tag should contain the <a href="en/XSLT">XSLT</a> transform.
</p>
<h2 name="See_also">See also</h2>
<ul><li> <a href="en/Creating_a_Microsummary">Creating a Microsummary</a>
</li><li> <a href="en/XSLT">XSLT</a>
</li></ul>
Revert to this revision