Microsummaries: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(update description of microsummaries and add links to various other pages)
(Firefox 6 dropped support for proprietary microsummary format, now obsolete)
 
(18 intermediate revisions by 8 users not shown)
Line 1: Line 1:
== Introduction ==
== OBSOLETE ==
'''As of Firefox 6, [https://bugzilla.mozilla.org/show_bug.cgi?id=524091 support for microsummaries has been removed].'''


Microsummaries are regularly-updated succinct summaries of 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 obsolete and not recommended for use. Some [http://microformats.org/wiki/page-summary-formats#Issues_2 issues with microsummary] have been documented.


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.
Legacy documentation follows:


This document outlines technical details of microsummaries and their functionality in Firefox.  To learn more about how to install and use microsummaries, check out these [[Microsummaries/Using|instructions]].  To learn how to create microsummaries, read this [http://developer.mozilla.org/en/docs/Creating_a_Microsummary tutorial].  Also see these collections of example [http://people.mozilla.com/~myk/microsummaries/generators/ microsummary generators] and [http://people.mozilla.com/~myk/microsummaries/sites/ microsummary-enabled web sites].
== Introduction ==


== Examples ==
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.


Examples of pages for which microsummaries are useful include:
Here are examples of possible microsummaries for some common types of pages:


* '''auction items:''' the item name, the current highest bid, and the time remaining, f.e. '''Honda Accord - $5000 - 1 minute left''';
{| valign="top" style="border-collapse: collapse;"
* '''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''';
|- style="font-weight: bold; background-color: #efefef; border-bottom: 1px solid black;"
* '''news sites:''' the latest headline, f.e. '''BBC: Chirac to sign France's job law''';
| Type of Page
* '''"[thing] of the day" pages:''' today's [thing], f.e. (for Merriam-Webster's word of the day page) '''flat-hat''';
| Possible Microsummary
* '''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''';
|- style="border-bottom: 1px solid black;"
* '''weather pages:''' the current forecast, f.e. '''SF: showers likely''';
| auction item
* '''tinderbox:''' the status of the tree, f.e. '''3 tbxn burning''';
| '''Honda Accord - $5000 - 1 minute left'''<br>''(item name, current highest bid, and time remaining)''
* '''insert your bright idea here'''.
|- style="border-bottom: 1px solid black;"
| product for sale
| '''Linksys WRT54G - $60 - in stock'''<br>''(product name, current price, and availability)''
|- style="border-bottom: 1px solid black;"
| news site
| '''BBC: Chirac to sign France's job law'''<br>''(latest headline)''
|- style="border-bottom: 1px solid black;"
| word of the day
| '''flat-hat'''<br>''(today's word)''
|- style="border-bottom: 1px solid black;"
| stock quote
| '''TWX: 16.94 + 0.30'''<br>''(stock price and movement)''
|- style="border-bottom: 1px solid black;"
| weather report
| '''SF: showers likely'''<br>''(current forecast)''
|- style="border-bottom: 1px solid black;"
| tinderbox
| '''3 burning'''<br>''(status of the tree)''
|- style="border-bottom: 1px solid black;"
| forum thread
| '''my first thread - 37 comments - last by Aaron'''<br>''(thread name, number of comments, and last commenter)''
|- style="border-bottom: 1px solid black;"
| support ticket
| '''tn79217 - in progress - J.Doe - eta: 3hrs'''<br>''(ticket number, status, owner, and ETA)''
|-
|}


== Microsummary Generators ==
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.


Microsummaries can either be provided by the page being summarized or generated by processing an XSLT stylesheet against the page.  In the latter case, the XSLT stylesheet and the page(s) to which it applies are provided by a microsummary generator.
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.


A microsummary generator is a set of instructions for generating microsummaries.  Generators are expressed via an XML dialect with the namespace '''<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>'''.  A generator consists of a <generator> tag containing the following attributes and child elements:
== Using Microsummaries ==


* a '''name''' attribute that identifies the generator to users, f.e. '''Latest BBC Headline''';
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.
* a '''<pages>''' child element with one or more <include>/<exclude> child elements containing regular expressions that identify the URIs to which the generator applies; URIs are excluded by default and must be explicitly included for a generator to apply to them;
* 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 generator 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? Maybe use Cron-notation for specifying update interval?]
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.


Here is an example microsummary generator:
See [[Microsummaries/Using|Using Microsummaries]] for detailed instructions on installing generators and using microsummaries.  Then try it out with these examples of [http://people.mozilla.com/~myk/microsummaries/sites/ microsummary-enabled web sites] and [http://people.mozilla.com/~myk/microsummaries/generators/ microsummary generators].


  <?xml version="1.0" encoding="UTF-8"?>
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>" name="Yahoo! Finance Stock Quote">
    <pages>
      <include><nowiki>http://finance.yahoo.com/q\?.*s=[a-zA-Z]+</nowiki></include>
    </pages>
    <template>
      <xsl:transform xmlns:xsl="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
        <xsl:output method="text"/>
        <xsl:template match="/">
          <xsl:value-of select="substring-before(substring-after(string(id('yfncsubtit')/tbody/tr/td[1]/b), '('), ')')"/>
          <xsl:text>: </xsl:text>
          <xsl:value-of select="id('yfncsumtab')/tbody/tr/td/table[3]/tbody/tr[2]/td[1]/table/tbody/tr/td/table/tbody/tr[1]/td[2]/big/b"/>
        </xsl:template>
      </xsl:transform>
    </template>
  </generator>


== Specifying Microsummaries ==
== Providing Microsummaries for Your Web Site ==


Firefox, its users, the web sites they visit, and independent developers should all be able to specify microsummaries for pages.
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 <code>&lt;link&gt;</code> tags.


=== Firefox ===
For example, if you use a PHP script <code>index.php</code> 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 <code>view=microsummary</code> URL parameter is present.  Then just link to the microsummary within the normal page content using a <code>&lt;link&gt;</code> tag, i.e.:


Firefox should be able to specify microsummaries via bundled microsummary generators for popular sites.
  &lt;head&gt;
    ''&lt;link rel="microsummary" href="index.php?view=microsummary"&gt;''
  &lt;/head&gt;


=== Users ===
When Firefox encounters a <code>&lt;link&gt;</code> tag whose <code>rel</code> attribute is set to <code>microsummary</code>, it loads the URL in the <code>href</code> 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).


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 currently deferred to the future.
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 [http://developer.mozilla.org/en/docs/Creating_a_Microsummary Creating a Microsummary tutorial] and the [http://developer.mozilla.org/en/docs/Microsummary_XML_grammar_reference Microsummary XML grammar reference].


=== Sites ===
Note the additional information available in [http://developer.mozilla.org/en/docs/Microsummary_topics Microsummary topics].


Sites should be able to specify microsummaries by embedding metadata referencing microsummary generators into pages.  For example, a site might embed the following <link> element into an HTML page:
== Writing Microsummary Generator Add-ons ==


  <link rel="microsummary" type="application/x.microsummary+xml" href="/index-microsummary.xml">
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.


Or it might embed the following two XML processing instruction into an XML document:
To learn how to create generator add-ons and make them available to Firefox users, see the [http://developer.mozilla.org/en/docs/Creating_a_Microsummary Creating a Microsummary tutorial].  Also see the [http://developer.mozilla.org/en/docs/Creating_regular_expressions_for_a_microsummary_generator 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.


  <?microsummary type="application/x.microsummary+xml" href="/index-microsummary.xml"?>
Refer to the [http://developer.mozilla.org/en/docs/Microsummary_XML_grammar_reference Microsummary XML grammar reference] for the details of the Microsummary XML grammar, and note the additional information available in [http://developer.mozilla.org/en/docs/Microsummary_topics Microsummary topics].


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


=== Independent Developers ===
Most of the microsummaries code in Firefox is located in the [http://lxr.mozilla.org/mozilla/source/browser/components/microsummaries/ browser/components/microsummaries] directory.  The <code>MicrosummaryService</code> component and related components are implemented in [http://lxr.mozilla.org/mozilla/source/browser/components/microsummaries/src/nsMicrosummaryService.js.in nsMicrosummaryService.js.in].  Public scriptable interfaces are defined in [http://lxr.mozilla.org/mozilla/source/browser/components/microsummaries/public/nsIMicrosummaryService.idl nsIMicrosummaryService.idl].


Independent developers should be able to specify microsummaries by distributing generators that users can acquire from a directory similar to the search engines directory at addons.mozilla.org.  Generators should have simple search engine-like installation and management UI and update themselves automatically.
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.


== Back-end Implementation ==
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.


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.
=== Datastore ===


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, the generator), processes it to generate an updated microsummary, and stores the updated microsummary in the 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:


=== nsIMicrosummaryService ===
* 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.


  [scriptable, uuid(c5e9c390-beb0-4eb4-90ab-529efc817632)]
=== Bookmarks Dialogs ===
  interface nsIMicrosummaryService : nsISupports
  {
      /**
      * Install the microsummary generator from the resource at the supplied URI.
      * Callable by content via the addMicrosummaryGenerator() sidebar method.
      *
      * @param  generatorURI
      *          the URI of the resource providing the generator
      *
      */
      void addGenerator(in nsIURI generatorURI);
 
      /**
      * Get the set of microsummaries available for a given page.  The set
      * might change after this method returns, since this method will trigger
      * an asynchronous load of the page in question (if it isn't already loaded)
      * to see if it references any page-specific microsummaries.
      *
      * If the caller passes a bookmark ID, and one of the microsummaries
      * is the current one for the bookmark, this method will retrieve content
      * from the datastore for that microsummary, which is useful when callers
      * want to display a list of microsummaries for a page that isn't loaded,
      * and they want to display the actual content of the selected microsummary
      * immediately (rather than after the content is asynchronously loaded).
      *
      * @param  pageURI
      *          the URI of the page for which to retrieve available microsummaries
      *
      * @param  bookmarkID (optional)
      *          the ID of the bookmark for which this method is being called
      *
      * @returns an nsIMicrosummarySet of nsIMicrosummaries for the given page
      *
      */
      nsIMicrosummarySet getMicrosummaries(in nsIURI pageURI,
                                          in nsISupports bookmarkID);
 
      /**
      * Get the current microsummary for the given bookmark.
      *
      * @param  bookmarkID
      *          the bookmark for which to get the current microsummary
      *
      * @returns the current microsummary for the bookmark, or null
      *          if the bookmark does not have a current microsummary
      *
      */
      nsIMicrosummary getMicrosummary(in nsISupports bookmarkID);
 
      /**
      * Set the current microsummary for the given bookmark.
      *
      * @param  bookmarkID
      *          the bookmark for which to set the current microsummary
      *
      * @param  microsummary
      *          the microsummary to set as the current one
      *
      */
      void setMicrosummary(in nsISupports bookmarkID,
                          in nsIMicrosummary microsummary);
 
      /**
      * Remove the current microsummary for the given bookmark.
      *
      * @param  bookmarkID
      *          the bookmark for which to remove the current microsummary
      *
      */
      void removeMicrosummary(in nsISupports bookmarkID);
 
      /**
      * Whether or not the given bookmark has a current microsummary.
      *
      * @param  bookmarkID
      *          the bookmark for which to set the current microsummary
      *
      * @returns a boolean representing whether or not the given bookmark
      *          has a current microsummary
      *
      */
      boolean hasMicrosummary(in nsISupports bookmarkID);
 
      /**
      * Whether or not the given microsummary is the current microsummary
      * for the given bookmark.
      *
      * @param  bookmarkID
      *          the bookmark to check
      *
      * @param  microsummary
      *          the microsummary to check
      *
      * @returns whether or not the microsummary is the current one
      *          for the bookmark
      *
      */
      boolean isMicrosummary(in nsISupports bookmarkID,
                            in nsIMicrosummary microsummary);
  };


=== nsIMicrosummaryObserver ===
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.


  [scriptable, uuid(cb284a83-1ca5-4000-9841-ce345ce84915)]
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.
  interface nsIMicrosummaryObserver : nsISupports
  {
      /**
      * Called when an observed microsummary updates its content.
      * Since an observer might watch multiple microsummaries at the same time,
      * the microsummary whose content has been updated gets passed
      * to this handler.
      * XXX Should this be onContentUpdated?
      *
      * @param microsummary
      *        the microsummary whose content has just been updated
      *
      */
      void onContentLoaded(in nsIMicrosummary microsummary);
 
      /**
      * Called when an element is appended to a microsummary set.
      * XXX Should this be in a separate nsICollectionObserver interface?
      *
      * @param microsummary
      *        the microsummary that has just been appended to the set
      *
      */
      void onElementAppended(in nsIMicrosummary microsummary);
  };


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


  [scriptable, uuid(f9d1a73c-e147-46f3-ba61-4f0bd33f5d47)]
=== Bookmarks Toolbar/Sidebar/Menu ===
  interface nsIMicrosummary : nsISupports
  {
      // the URI of the page being summarized
      readonly attribute nsIURI pageURI;
 
      // The URI of the generator that generates this microsummary.
      readonly attribute nsIURI generatorURI;
 
      // The generator that generates this microsummary.
      // Since generators can be remote resources, this may not always be available.
      attribute nsIMicrosummaryGenerator generator;
 
      // The content of the microsummary.
      // Since generators and pages can be remote resources, and we need them
      // to generate the content, this may not always be available.
      readonly attribute AString content;
 
      /**
      * Add a microsummary observer to this microsummary.
      *
      * @param observer
      *        the microsummary observer to add
      *
      */
      void addObserver(in nsIMicrosummaryObserver observer);
 
      /**
      * Remove a microsummary observer from this microsummary.
      *
      * @param observer
      *        the microsummary observer to remove
      *
      */
      void removeObserver(in nsIMicrosummaryObserver observer);
 
      /**
      * Update the microsummary, first loading its generator and page content
      * as necessary.  If you want know when a microsummary finishes updating,
      * add an observer before calling this method.
      *
      */
      void update();
  };


=== nsIMicrosummarySet ===
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).


  [scriptable, uuid(7111e88d-fecd-4b17-b7a9-1fa74e23153f)]
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.
  interface nsIMicrosummarySet : nsISupports
  {
      /**
      * Add a microsummary observer to this microsummary set.  Adding an observer
      * to a set is the equivalent of adding it to each constituent microsummary.
      *
      * @param observer
      *        the microsummary observer to add
      *
      */
      void addObserver(in nsIMicrosummaryObserver observer);
 
      /**
      * Remove a microsummary observer from this microsummary.
      *
      * @param observer
      *        the microsummary observer to remove
      *
      */
      void removeObserver(in nsIMicrosummaryObserver observer);
 
      /**
      * Retrieve a enumerator of microsummaries in the set.
      *
      * @returns an enumerator of nsIMicrosummary objects
      *
      */
      nsISimpleEnumerator Enumerate();
  };


=== nsIMicrosummaryGenerator ===
[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.]


  [scriptable, uuid(ff3eba15-81de-4c24-bfcf-c8180dc3c00a)]
Additional integration points may be defined in the future (f.e. microsummaries might be displayed as tab labels).
  interface nsIMicrosummaryGenerator : nsISupports
  {
      // An arbitrary descriptive name for this microsummary generator.
      readonly attribute AUTF8String name;
 
      // The canonical location and unique identifier of the generator.
      // It tells us where the generator comes from and where to go for updates.
      // For generators referenced by web pages via <link> tags, this URI
      // is the one specified by the tag. For generators installed by users,
      // this URI is the remote location from which we installed the generator.
      // For generators bundled with the browser, this URI is a reference
      // to the latest version of this generator available on Mozilla Add-ons.
      readonly attribute nsIURI uri;
 
      // Whether or not this generator needs page content to generate
      // a microsummary. Microsummaries generated by XSLT templates need page
      // content, while those which represent the actual microsummary content
      // do not.
      readonly attribute boolean needsPageContent;
 
      /**
      * Generate a microsummary by processing the generator template
      * against the page content.  If a generator doesn't need content,
      * pass null as the parameter to this method.
      *
      * XXX In the future, this should support returning rich text content,
      * so perhaps we should make it return a DOM node now and have the caller
      * convert that to text if it doesn't support rich content.
      *
      * @param  pageContent
      *          the content of the page being summarized
      * @returns the text result of processing the template
      *
      */
      AString generateMicrosummary(in nsIDOMNode aPageContent);
  };


=== Datastore ===
== Standardization ==


In Firefox 2 the microsummary service stores microsummaries and their meta-data as properties of the RDF resources that represent bookmarks in the bookmarks data source.  In Firefox 3 the service stores the same date as annotations in the annotations datastore via the annotation service. Microsummary data includes:
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.


* bookmarks/generatedTitle: the content of the microsummary (i.e. what Firefox displays to users);
== Resources ==
* microsummary/generatorURI: the canonical source of the generator;
* microsummary/expiration: the time in microseconds since the epoch at which the microsummary will expire.


== Front-end Implementation ==
=== Tutorials ===
* [http://developer.mozilla.org/en/docs/Creating_a_Microsummary Creating a Microsummary]
* [http://developer.mozilla.org/en/docs/Creating_regular_expressions_for_a_microsummary_generator Creating regular expressions for a microsummary generator]


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


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


=== Bookmark Properties Dialog ===
* [http://people.mozilla.com/~myk/microsummaries/generators/ microsummary generators]
* [http://www.etf.cuni.cz/~tomasek/pub/microsummaries/install.html generators for Czech sites]
* [http://userstyles.org/livetitle/ Live Titles] - microsummary generators repository


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.getMicrosummaries() and updates the datastore per the user's selection via nsIMicrosummaryService.setMicrosummary() and nsIMicrosummaryService.removeMicrosummary().
==== Sites ====


=== Bookmarks Toolbar ===
See examples of sites that provide microsummaries at [[Microsummaries/Sites]].


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. Once the microsummary service has updated the microsummary, the bookmarks toolbar may display some UI indicating that an update is underway (f.e. it may replace the favicon with a throbber for the duration of the update).
=== Other Docs ===
* [[Microsummaries/Using|Using Microsummaries]]
* [http://developer.mozilla.org/en/docs/Microsummary_XML_grammar_reference Microsummary XML grammar reference]
* [http://developer.mozilla.org/en/docs/Microsummary_topics Microsummary topics]


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.
== Tools ==
 
[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 appropriate bodies. Appropriate bodies for standardization may include the [http://microformats.org/wiki/Main_Page microformats group] and the WHATWG.
=== Extensions ===
* [https://addons.mozilla.org/firefox/3639/ Microsummary Buddy] - display an icon in the location bar when a microsummary is available for a page
* [https://addons.mozilla.org/firefox/3741/ Microsummary Generator Builder] - build a Microsummary Generator, based on a selection on the current web page
* [https://addons.mozilla.org/firefox/4248/ Microsummary Manager] - shows installed Microsummaries in the Add-ons manager and provides UI for deleting them

Latest revision as of 15:21, 4 August 2011

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

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