A microsummary generator is a set of instructions for creating a microsummary from the content of a page. Web pages can reference generators via <link rel="microsummary"> elements in their <head> elements. Generators can also be independently downloaded and installed by users if they include a list of pages to which they apply.
In this tutorial we're going to create a microsummary generator for the Spread Firefox home page that displays the current Firefox download count along with the label Fx downloads; for example: 174475447 Fx downloads.
We'll build the XSLT transform sheet that converts that page into its microsummary, learn how to specify that the generator applies to that page, and find out how to make the generator available for download and installation.
In each step of revising the transform sheet and other code in this tutorial, new material added will be shown in boldface so you can follow along more easily.
Note: if you are a web site developer, and you want to create microsummaries for pages on your site, you can write generators to do so, but a simpler and more efficient approach is to create the microsummaries on the server-side using the same tools and languages you already use to generate pages.
For example, if you use PHP scripts to generate pages on your site, you could write PHP code to output a microsummary when the view=microsummary URL parameter is present. Then just link to the microsummaries from within the pages themselves using a <link rel="microsummary"> element, f.e.:
<head> <link rel="microsummary" href="index.php?view=microsummary"> </head>
When Firefox encounters a <link rel="microsummary"> element, it loads the URL in the href attribute. If the URL points to a generator, it uses the generator to generate the microsummary for the page. Otherwise, if the URL returns plain text content (or HTML content that can be converted to plain text), Firefox uses the content as the microsummary for the page.
Beginnings
Generators are expressed as XML documents whose root element is the <generator> element in the https://www.mozilla.org/microsummaries/0.1 namespace. To begin building the generator, create a new empty text file and add an XML declaration and empty <generator> tag to it:
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="https://www.mozilla.org/microsummaries/0.1">
</generator>
Giving it a Name
Generators should have name attributes which are arbitrary descriptions of the microsummaries the generator creates. Names should be descriptive enough to give users a good idea what information the microsummaries will provide. Since our generator will be creating microsummaries displaying the Firefox download count, let's give it the name "Firefox Download Count":
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="https://www.mozilla.org/microsummaries/0.1"
name="Firefox Download Count">
</generator>
Adding an XSLT Transform Sheet
Generators must include an XSLT transform sheet (also known as an XSLT stylesheet) which transforms the page content into its microsummary. XSLT is a powerful language for transforming documents into different representations of the same information.
Add the XSLT transform sheet to the generator by including it within a <template> element:
<?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"> </transform> </template> </generator>
Note that while microsummary generators can include arbitrary XSLT, including XSLT that produces rich text output, Firefox currently only displays the text version of the XSLT output.
Specifying the Output Type
Since the XSLT transform sheet will generate a text microsummary, we should indicate this with the XSLT <output> element:
<?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"/> </transform> </template> </generator>
Using a Simple XSLT <template>
The XSLT processor transforms documents by comparing each XSLT <template> element in the transform sheet to a set of nodes in the document. When a <template>'s match attribute matches a node, the processor performs the transformations specified by the content of the element.
This mechanism is powerful, because it lets you traverse the node tree of a document, recursively generating output based on the contents of the document. But for the purposes of generating a microsummary for the Spread Firefox page, we only need to use a single <template> element that matches the root node of the document and is processed once:
<?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="/"> </template> </transform> </template> </generator>
Including the Download Count
To include the download count in the output of the XSLT transform sheet, we need to add an XSLT <value-of> element to the template whose select attribute contains an XPath expression that points to the node containing the count.
XPath is a language for identifying nodes in HTML/XML documents. It also contains basic functions for manipulating those nodes and their content. The easiest way to get an XPath expression that points to the node in question is to use the XPath Checker extension.
Install the extension (restarting Firefox to complete installation) then go to the Spread Firefox home page, find the Firefox download count (a large number at the bottom of the right-hand column), context click on the number, and select View XPath from the context menu.
XPath Checker will open a new window. The new window will include an XPath field that contains this XPath expression pointing to the download count node: id('download-count').
Add a <value-of> element to the XSLT <template> element whose select attribute contains that XPath expression:
<?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')"/> </template> </transform> </template> </generator>
Adding Text
To include the label Fx downloads in the microsummary, we need to add an XSLT <text> element to the XSLT <template> element whose content is the text we want to add.
Add a <text> element to the XSLT template with the content Fx downloads:
<?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> </generator>
Note that white space between XSLT tags is not included in the XSLT output, unlike in HTML where that white space is collapsed to a single space, so make sure to prepend a space to the phrase in order to separate it from the download count.
With this addition, we've finished writing the XSLT transform sheet that converts the Spread Firefox home page to its microsummary.
Specifying the Page to which the Generator Applies
Now that we've written the transform sheet, we have to specify the page to which it applies. If we were the Spread Firefox webmasters, we might simply reference the generator within the page itself by adding a <link rel="microsummary"> tag to its <head> element:
<head> <link rel="microsummary" href="path/to/our/generator.xml"> </head>
Since we're not that site's webmasters, however, we can specify the page to which the generator applies within the generator itself and then make the generator available for download and installation. To specify pages to which a generator applies, we use a <pages> element within the <generator> element:
<?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> </pages> </generator>
The <pages> element can contain a sequence of <include> and <exclude> elements specifying the pages to which a generator does and doesn't apply, respectively.
To make a generator apply to a page, add an <include> element whose content is a regular expression matching the page. To make the generator not apply to a page, add an <exclude> element whose content is a regular expression matching the page.
By default, generators don't apply to any page, so you have to explicitly list the pages they apply to, and you don't have to exclude any pages unless you've previously included them.
Add an <include> element matching the Spread Firefox home page:
<?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>
If you're unfamiliar with regular expressions, see Creating regular expressions for a microsummary generator for a tutorial on writing them.
Making the Generator Available for Download
Now that the generator applies to the Spread Firefox home page, the only thing left to do is to make it downloadable. To do so, we need to put it up on the web and then create a JavaScript link on some web page that calls Firefox's window.sidebar.addMicrosummaryGenerator() method to download and install the generator.
For example, if we put the generator file on the web at https://people.mozilla.com/~myk/micro...-generator.xml, and we wanted users to be able to install it from https://people.mozilla.com/~myk/micro...ial/index.html, we might add the following code to the index.html page:
<button onclick="window.sidebar.addMicrosummaryGenerator('https://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml')">Install the Spread Firefox home page microsummary!</button>
Clicking that button will generate a JavaScript error on browsers that don't support microsummaries, however, so to improve the experience for those users, we should check to see if the user is using a microsummaries-enabled browser and display an explanatory message if not. We might do so via the following code:
<script>
const warning = "Sorry, you need a microsummary-enabled browser like Firefox 2.0 to install and use microsummary generators.";
function addGenerator(url) {
if (typeof window.sidebar == "object" &&
typeof window.sidebar.addMicrosummaryGenerator == "function")
window.sidebar.addMicrosummaryGenerator(url);
else
alert(warning);
}
</script>
<button onclick="addGenerator('https://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml')">Install the Spread Firefox home page microsummary!</button>
Note that due to bug 341283, addMicrosummaryGenerator() will not accept a relative URL.
Conclusion
You should now have a microsummary generator that displays the current Firefox download count when you install it, bookmark the Spread Firefox home page, and select the microsummary from the Summary drop-down menu in the Add Bookmark dialog.
For more information about Microsummaries, see the Microsummaries home page.