Programmatically installing a microsummary generator

To programmatically install a microsummary generator -- for example, in an extension that helps users create custom generators for their favorite sites -- obtain a reference to the nsIMicrosummaryService interface implemented by the nsIMicrosummaryService component, then call its installGenerator() method, passing it an XML document containing the generator.

For example, the following code snippet installs the microsummary generator from the Creating a Microsummary tutorial:

var generatorText = ' \
  <?xml version="1.0" encoding="UTF-8"?> \
  <generator xmlns="http://www.mozilla.org/microsummaries/0.1" \
             name="Firefox Download Count" \
             uri="urn:{835daeb3-6760-47fa-8f4f-8e4fdea1fb16}"> \
    <template> \
      <transform xmlns="http://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>http://(www\.)?spreadfirefox\.com/(index\.php)?</include>
    </pages>
  </generator> \
';

var domParser =
  Components.classes["@mozilla.org/xmlextras/domparser;1"].
  createInstance(Components.interfaces.nsIDOMParser);

var generatorDoc = domParser.parseFromString(generatorText, "text/xml");

var microsummaryService =
  Components.classes["@mozilla.org/microsummary/service;1"].
  getService(Components.interfaces.nsIMicrosummaryService);

var generator = microsummaryService.installGenerator(generatorDoc);

The service installs the generator by serializing its XML to a file in the user's profile directory and adding the generator to the service's in-memory generator cache.

When programmatically installing generators, you should specify a unique identifier for the generator in the uri attribute of the <generator> element. The value of the attribute must be a valid URI, but you can specify an arbitrary identifier using a URN, for example:

urn:{835daeb3-6760-47fa-8f4f-8e4fdea1fb16}

To guarantee uniqueness, use URNs containing UUIDs generated by the nsUUIDGenerator component. See Generating a UUID in the nsIUUIDGenerator documentation.

You may also use another form appropriate to your extension.

Differentiating between user-initiated and microsummary-related requests

When Firefox updates a microsummary generated by a microsummary generator add-on, it automatically downloads the HTML content of the page being summarized. It does not generally download related content like embedded images and JavaScript scripts referenced by the page. However, because of a technical limitation (bug 340746), it does download CSS stylesheets referenced by the page.

Firefox includes the X-Moz request header with these requests. It sets the value of the header to the string microsummary. Thus, to differentiate requests initiated manually by users for the purpose of viewing a web page from those initiated automatically by Firefox for the purpose of summarizing that page, check for the presence and value of the X-Moz request header.

If the X-Moz header is present, and its value is microsummary, then the request is a microsummary-related request. Otherwise, it is a user-initiated request.

Controlling the frequency of microsummary requests

When Firefox downloads content in order to update a microsummary, it honors cache-related HTTP response headers. Thus, if you would like to control how frequently Firefox initiates microsummary-related requests to your web server, you can do so by including an HTTP Expires or Cache-Control header in your response to a microsummary-related request.

For example, you might include the following header in your response to prevent Firefox from making another microsummary-related request for one hour:

Cache-Control: max-age=3600

To mitigate this effect, only return microsummary-specific cache headers in response to microsummary-related requests. Then only microsummary users will be affected by those headers.