Microsummaries

From MozillaWiki
Jump to: navigation, search

OBSOLETE

As of Firefox 6, support for microsummaries has been removed.

Microsummaries are obsolete and not recommended for use. Some issues with microsummary have been documented.

Legacy documentation follows:

Introduction

Microsummaries are regularly-updated short summaries of web pages. They are compact enough to fit in the space available to a bookmark label, they provide more useful information about pages than static page titles, and they get regularly updated as new information becomes available.

Here are examples of possible microsummaries for some common types of pages:

Type of Page Possible Microsummary
auction item Honda Accord - $5000 - 1 minute left
(item name, current highest bid, and time remaining)
product for sale Linksys WRT54G - $60 - in stock
(product name, current price, and availability)
news site BBC: Chirac to sign France's job law
(latest headline)
word of the day flat-hat
(today's word)
stock quote TWX: 16.94 + 0.30
(stock price and movement)
weather report SF: showers likely
(current forecast)
tinderbox 3 burning
(status of the tree)
forum thread my first thread - 37 comments - last by Aaron
(thread name, number of comments, and last commenter)
support ticket tn79217 - in progress - J.Doe - eta: 3hrs
(ticket number, status, owner, and ETA)

Microsummaries are better for labeling bookmarks than static page titles, because they give users quicker access to the most interesting information behind a bookmark, and they give web sites a way to notify users of updates and entice them to revisit the site.

A microsummary can be provided by a page itself (similar to the way pages provide RSS feeds of their contents) or by a microsummary generator, a type of Firefox add-on that contains instructions for extracting information from the contents of the page.

Using Microsummaries

As a user, when you bookmark a web page which provides a microsummary, you can choose to display the microsummary instead of the static page title as the "live title" for the bookmark. Then, when the microsummary changes, the bookmark title will update to reflect those changes, so you can get the latest updates about the information on the page just by looking at the bookmark.

You can also install a microsummary generator to get microsummaries for pages which don't provide their own. Installing generators is as simple as installing search engine add-ons, and you use them the same way you use microsummaries provided by pages themselves.

See Using Microsummaries for detailed instructions on installing generators and using microsummaries. Then try it out with these examples of microsummary-enabled web sites and microsummary generators.


Providing Microsummaries for Your Web Site

If you are a web site developer, you can provide microsummaries for the pages on your web site by creating them using the same tools and languages you already use to generate the pages, then linking to them from within the pages being summarized via <link> tags.

For example, if you use a PHP script index.php to generate the home page for your site, you could add PHP code to the script which outputs a microsummary instead of the normal page content when the view=microsummary URL parameter is present. Then just link to the microsummary within the normal page content using a <link> tag, i.e.:

 <head>
   <link rel="microsummary" href="index.php?view=microsummary">
 </head>

When Firefox encounters a <link> tag whose rel attribute is set to microsummary, it loads the URL in the href attribute and uses its content as the microsummary for the page. If the content is plain text, Firefox uses it as-is. If the content is HTML, however, Firefox first converts it to plain text (Firefox supports only plain text microsummaries at this time).

Note: if the content at the URL is a microsummary generator, Firefox will use the generator to extract the microsummary from the contents of the page itself, so you can write code to generate the microsummary on the client instead of the server. But generating microsummaries on the server-side is generally simpler and more efficient, so we recommend you take that approach. If you do want to write a client-side generator, however, see the Creating a Microsummary tutorial and the Microsummary XML grammar reference.

Note the additional information available in Microsummary topics.

Writing Microsummary Generator Add-ons

If you are an add-ons developer for Firefox with knowledge of XML and XSLT, you can create microsummary generator add-ons which generate microsummaries for sites that don't provide them.

To learn how to create generator add-ons and make them available to Firefox users, see the Creating a Microsummary tutorial. Also see the Creating regular expressions for a microsummary generator tutorial for a step-by-step guide to writing regular expressions that specify the pages to which your generators should apply.

Refer to the Microsummary XML grammar reference for the details of the Microsummary XML grammar, and note the additional information available in Microsummary topics.

Technical Details

Most of the microsummaries code in Firefox is located in the browser/components/microsummaries directory. The MicrosummaryService component and related components are implemented in nsMicrosummaryService.js.in. Public scriptable interfaces are defined in nsIMicrosummaryService.idl.

The microsummary service updates microsummaries when they expire and provides an API for front-end code to access microsummaries register itself to be notified when they get updated.

Like the livemarks service, the microsummary service checks every 15 seconds for microsummaries that need updating. When a microsummary needs updating, the service downloads the necessary content (i.e. the microsummary, the page, the generator), processes it as needed to generate a microsummary, and stores the updated microsummary in the datastore. The bookmarks UI templates/controllers then get notified of those changes and rebuilds the bookmarks UI as appropriate.

Datastore

In Firefox 2, the service stores microsummaries and their meta-data as properties of the RDF resources that represent bookmarks in the bookmarks data source. In Firefox 3 with Places enabled, the service stores the same information as annotations in the annotations datastore via the annotation service. Microsummary data includes:

  • generated title: the content of the microsummary (i.e. what Firefox displays to users);
  • source URI: a unique URI identifying the generator;
  • expiration: the time (in microseconds since the epoch) at which the microsummary will expire.

Bookmarks Dialogs

The Add Bookmark and Bookmark Properties dialogs let the user choose to display a microsummary for the bookmark by turning the Name field into an editable menulist if a microsummary is available. The menulist includes one item for each available microsummary along with an item for the static page title, so the user can choose to display either the static title or a microsummary.

As before, the user can edit the static page title. If the user selects a microsummary and then edits it, the text of the microsummary becomes the static page title. This may prove confusing for users, who expect to be able to edit a microsummary and still have it be a dynamically updating microsummary, so we should monitor user experience of this UI and modify it as appropriate.

The dialog retrieves microsummaries via nsIMicrosummaryService.getMicrosummaries() and updates the datastore per the user's selection via nsIMicrosummaryService.setMicrosummary() and nsIMicrosummaryService.removeMicrosummary().

Bookmarks Toolbar/Sidebar/Menu

When the user chooses a microsummary for a bookmarked page, the bookmarks toolbar, sidebar, and menu display the microsummary instead of the page title as the label for the bookmark. When the microsummary service updates the microsummary, the bookmarks UI updates the label using an implementation-specific mechanism (XUL template observing the bookmarks datasource for the old bookmarks code, controller registered as a microsummary observer for the Places code).

After the microsummary service updates the microsummary and the bookmarks UI updates, we may want the bookmarks toolbar to display some indication that an update has taken place. Perhaps we could subtly throb the label for a short time. We might also want to provide a way for the user to find out when the microsummary was last updated.

[The mechanism by which the bookmarks controller identifies and observes microsummary bookmarks should be extensible (i.e. a generic "metadata observer") so that future code (both native and extensions) can register additional bookmark types with metadata whose observation triggers activity.]

Additional integration points may be defined in the future (f.e. microsummaries might be displayed as tab labels).

Standardization

The microsummary generator dialect and the use of the <link rel> element to specify microsummaries should be standardized by the appropriate bodies, which may include the microformats group and the WHATWG.

Resources

Tutorials

Examples

Generators

Sites

See examples of sites that provide microsummaries at Microsummaries/Sites.

Other Docs

Tools

Extensions