Microsummaries

From MozillaWiki
Revision as of 03:08, 1 April 2006 by Mykmelez (talk | contribs) (expanded with voluminous addl. info, including implementation details)
Jump to navigation Jump to search

Introduction

Microsummaries are regularly-updated succinct compilations of the most important information on web pages. They are compact enough to fit in the space available to a bookmark label, provide more useful information about pages than static page titles, and are regularly updated as new information becomes available.

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

For an overview of microsummaries and their integration into Firefox, see this walkthrough with screenshots showing major elements. For detailed information, read the rest of this document.


Examples

Examples of pages for which microsummaries are useful include:

  • auction items: the item name, the current highest bid, and the time remaining, f.e. Honda Accord - $5000 - 1 minute left;
  • products for sale: the product name, the current price, and whether or not the product is in stock, f.e. Linksys WRT54G - $60 - in stock;
  • news sites: the latest headline, f.e. BBC: Chirac to sign France's job law;
  • "[thing] of the day" pages: today's [thing], f.e. (for Merriam-Webster's word of the day page) flat-hat;
  • stock quotes: the current price of the stock and its movement in the market, f.e. TWX 16.94 + .30;
  • stock portfolios: your current net worth, f.e. net worth: $30k; +$500 today;
  • weather pages: the current forecast, f.e. SF: showers likely;
  • tinderbox: the status of the tree, f.e. 3 tbxn burning;
  • insert your bright idea here.


Microsummary Definitions

Microsummaries can either be extracted from an RSS/Atom feed or generated by processing an XSLT stylesheet against the page being summarized. In the latter case, the XSLT stylesheet and the pages to which it applies are provided by a microsummary definition.

A microsummary definitions is a set of instructions for generating microsummaries. Definitions are expressed via an XML dialect with the namespace http://www.mozilla.org/microsummaries/0.1. A definition consists of a <definition> tag containing the following attributes and child elements:

  • an id attribute that uniquely identifies the definition. The recommended format for the ID attribute is @[author]/[site]/[name], where [author] identifies the developer of the definition, [site] identifies the site to which the definition applies, and [name] describes the definition, for example: @mozilla.org/bbc.co.uk/latest-headline;
  • a name attribute that identifies the definition to users, f.e. Latest BBC Headline;
  • a <pages> child element with one or more <include>/<exclude> child elements containing regular expressions that identify the URIs to which the definition applies;
  • a <template> element containing an XSLT stylesheet which generates a microsummary from a page. The stylesheet can generate not only text but also HTML, graphics, and other rich content.

[Should a definition also contain an update interval or timeout specifying how often to update microsummaries or when to update them next? How should this interval/timeout be specified? Is it worth enabling complex specifications like "update every five minutes from 9:30am-4pm EST and not at all otherwise" for an NYSE stock quote?]

Here is an example microsummary definition: 

 <definition xmlns="http://www.mozilla.org/microsummaries/0.1"
             id="@mozilla.org/bbc.co.uk/latest-headline;1" 
             name="Latest BBC Headline">
 
   <pages>
 
     <include>^http://(www\.)?bbc\.co\.uk/$</include>
 
   </pages>
 
   <template>
 
     <xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    version="1.0">
 
       <xsl:output method="text"/>
 
       <xsl:template match="/">
         <xsl:text>BBC: </xsl:text>
         <xsl:value-of select="normalize-space(id('rightColTable')/div/table[1]/tbody/tr/td[2]/table[2]/tbody/tr/td[3]/div[1]/a)"/>
       </xsl:template>
 
     </xsl:transform>
 
   </template>
 
 </definition>


Specifying Microsummaries

Firefox, its users, the web sites they visit, and independent developers should all be able to specify microsummaries for pages.

Firefox

Firefox should be able to specify microsummaries via bundled microsummary definitions for popular sites.

Users

Users should be able to specify microsummaries via a microsummary builder feature in Firefox that lets users extract text snippets from a rendered page via simple methods like drag-and-drop and string them together along with arbitrary text into a microsummary. Implementation of a microsummary builder is deferred to the future.

Sites

Sites should be able to specify microsummaries by embedding metadata referencing microsummary definitions or RSS/Atom feeds into pages. For example, a site might embed one of the following two <link> elements into an HTML page: 

 <link rel="microsummary" type="application/x.microsummary+xml" href="/index-microsummary.xml">
 <link rel="microsummary" type="application/x.atom+xml" href="/index-microsummary.xml">

Or it might embed one of the following two XML processing instructions into an XML document: 

 <?microsummary type="application/x.microsummary+xml" href="/index-microsummary.xml"?>
 <?microsummary type="application/x.atom+xml" href="/index-microsummary.xml"?>

For RSS/Atom feed-based microsummaries, Firefox will use profiles of the RSS and Atom specifications to extract microsummaries via the following rules:

  • if the rss:channel/atom:feed element contains no items/entries, the microsummary is the value of the rss:description/atom:subtitle element;
  • if the rss:channel/atom:feed element contains one item/entry, the microsummary is the value of the item's/entry's rss:description/atom:summary element;
  • if the rss:channel/atom:feed element contains more than one item/entry:
    • if the items/entries are dated via rss:pubDate/atom:published/atom:updated elements, the microsummary is the value of the rss:description/atom:summary element of the most recent item/entry;
    • if the items/entries are not dated, the microsummary is the value of the rss:description/atom:summary element of the first item/entry.

[If a page points to a microsummary definition whose <pages> list does not include the page, should the microsummary service ignore the <pages> list and apply the definition to the page anyway?]

Independent Developers

Independent developers should be able to specify microsummaries by packaging microsummary definitions into addons that users can acquire from a directory of such addons similar to the extensions/themes directory at addons.mozilla.org. Microsummary definitions packaged in this way are called microsummary support packs. Developers should be able to package multiple definitions into a single pack. Packs should be automatically updatable.

[Should packs use the extensions model, i.e. packaged as XPIs and subject to origin restrictions, or should they use the search engines model, i.e. no origin restrictions?

If packs use the extensions model, the XPIs might contain a definitions.xml file, a directory of such files, or both, i.e.: 

 XPI
   install.rdf
   [definitions.xml]
   [definitions/
     *.xml]

]


Back-end Implementation

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

Like the livemarks service, the microsummary service checks every 15 seconds for microsummaries that need updating. If a microsummary needs updating, the service downloads the necessary content (i.e. the page or its feed), processes it to generate an updated microsummary, and stores the updated microsummary in the datastore.

nsIMicrosummaryService

 [scriptable, uuid(c5e9c390-beb0-4eb4-90ab-529efc817632)]
 interface nsIMicrosummaryService : nsISupports
 {
     /**
      * Retrieves a list of available microsummaries for a given URI.
      * The aDoc argument is optional.  If present, this method will use it
      * to generate the microsummaries.  Otherwise, microsummary content
      * may not be available, in which case this method will return microsummary
      * objects without content.  Callers who receive such objects should use
      * the microsummary definition name in lieu of microsummary content.
      *
      * @param aURI  the URI of the microsummarized page
      * @param aDoc  the document to which the URI refers
      * @returns an enumerator of nsIMicrosummary objects
      */
     nsISimpleEnumerator getMicrosummaries(in nsIURI aURI, in nsIDOMNode aDoc);
 
     /**
      * Manually updates the microsummary for a given URI.  The aDoc argument
      * is optional.  If present, this method will use it to update the microsummary
      * Otherwise it will download the document asynchronously.
      *
      * @param aURI  the URI of the microsummarized page
      * @param aDoc  the document to which the URI refers
      *
      */
     void updateMicrosummary(in nsIURI aURI, in nsIDOMNode aDoc);
 
     /**
      * Sets the microsummary for a given URI.
      *
      * @param aURI           the URI of the microsummarized page
      * @param aMicrosummary  the microsummary to set
      *
      */
     void setMicrosummary(in nsIURI aURI, in nsIMicrosummary aMicrosummary);
 
     /**
      * Removes the microsummary for a given URI.
      *
      * @param aURI           the URI of the microsummarized page
      *
      */
     void removeMicrosummary(in nsIURI aURI);
 
     /**
      * Adds a microsummary observer.
      *
      */
     void addObserver(in nsIAnnotationObserver aObserver);
 
     /**
      * Removes a microsummary observer previously registered by addObserver.
      *
      */
     void removeObserver(in nsIAnnotationObserver aObserver);
 };

nsIMicrosummaryObserver

 [scriptable, uuid(de8ac63a-3867-4dad-a631-ba1d8869d733)]
 interface nsIMicrosummaryObserver : nsISupports
 {
     /**
      * Called when the microsummary service starts updating a microsummary.
      *
      * @param aURI  the URI of the microsummarized page
      *
      */
     void onStartUpdate(in nsIURI aURI);
 
     /**
      * Called when the microsummary service stops updating a microsummary.
      *
      * @param aURI  the URI of the microsummarized page
      *
      */
     void onStopUpdate(in nsIURI aURI);
 };

nsIMicrosummary

 [scriptable, uuid(f9d1a73c-e147-46f3-ba61-4f0bd33f5d47)]
 interface nsIMicrosummary : nsISupports
 {
     // for microsummaries specified via a bundled or installed definition,
     // the nsIMicrosummaryDefinition for this microsummary
     readonly attribute nsIMicrosummaryDefinition definition;
 
     // for microsummaries specified via a <link> element pointing to
     // a microsummary definition or RSS/Atom feed, the URI of the resource
     readonly attribute nsIURI uri;
 
     // the URI of the page being summarized
     // XXX Should this be the ID of the page in the history datastore?
     readonly attribute nsIURI page;
 
     // the content of the microsummary
     readonly attribute nsIDOMNode content;
 };

nsIMicrosummaryDefinition

 [scriptable, uuid(ff3eba15-81de-4c24-bfcf-c8180dc3c00a)]
 interface nsIMicrosummaryDefinition : nsISupports
 {
     // the unique identifier for this microsummary definition;
     // corresponds to the 'id' attribute of the <definition> element
     readonly attribute string id;
 
     // the user-friendly name for this microsummary definition;
     // corresponds to the 'name' attribute of the <definition> element
     readonly attribute string name;
 
     // the XSLT stysheet by which we generate the microsummary;
     // corresponds to the <template> child of the <definition> element
     readonly attribute nsIDOMNode template;
 };

Datastore

The microsummary service stores microsummaries and their meta-data as annotations in the annotations datastore via the annotation service. Microsummary annotations include:

  • microsummary/content: the microsummary content (i.e. what Firefox displays to users);
  • microsummary/id: for microsummaries specified by bundled or installed definitions, the unique identifier of the microsummary definition containing the template;
  • microsummary/uri: for microsummaries specified by <link rel="microsummary"> elements embedded in page headers, the URI of the resource identified by the <link> element.
  • microsummary/expiration: the time in microseconds since the epoch at which the microsummary will expire.


Front-end Implementation

The initial integration points are the bookmark properties dialog and the bookmarks toolbar.

Since microsummaries can contain HTML and other unsafe content, they should be inserted into the UI inside untrusted iframes wherever they appear.

Bookmark Properties Dialog

The bookmark properties dialog lets the user choose to display a microsummary for the bookmark. If multiple microsummaries are available, the dialog lets users choose between them. The dialog retrieves microsummaries via nsIMicrosummaryService.getMicrosummariesForURI() and updates the datastore per the user's selection via nsIMicrosummaryService.setMicrosummary() and nsIMicrosummaryService.removeMicrosummary().

Bookmarks Toolbar

When a microsummary is set for a bookmarked URI, the bookmarks toolbar displays the microsummary instead of the page title as the label of the bookmark. When the microsummary service updates the microsummary, the bookmarks toolbar updates the label. While the microsummary service is in the process of updating the microsummary, the bookmarks toolbar displays some UI indicating that an update is underway (f.e. it replaces the favicon with a throbber for the duration of the update).

The toolbar displays microsummaries via a template rule that applies only to bookmarks with microsummaries. The toolbar controller registers itself with the microsummary service as a microsummary observer in order to be notified when a microsummary gets updated.

[Is the annotation observer interface sufficient for this task? I.e. is it sufficient for the toolbar controller to merely register itself as an annotation observer of the microsummary/content annotation? Probably not, since the annotation observer doesn't let you observe that an update to the annotation is underway.]

[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 definition dialect and the use of the <link rel> element to specify microsummaries should be standardized by appropriate bodies. Appropriate bodies for standardization may include the microformats group and the WHATWG.

Retrieved from "https://wiki.allizom.org/index.php?title=Microsummaries&oldid=23266"