Microsummary topics

  • Revision slug: Microsummary_topics
  • Revision title: Microsummary topics
  • Revision id: 87549
  • Created:
  • Creator: MykMelez
  • Is current revision? No
  • Comment typo fix

Revision Content

Programmatically installing a microsummary generator

To programmatically install a microsummary generator (e.g. in an extension that helps users create custom generators for their favorite sites), obtain a reference to the nsIMicrosummaryService interface implemented by the nsMicrosummaryService 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> \
  </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 will install 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 to 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 via its nsIUUIDGenerator interface:

var uuidGenerator = 
  Components.classes["@mozilla.org/uuid-generator;1"].
  getService(Components.interfaces.nsIUUIDGenerator);

var uuid = uuidGenerator.generateUUID();

var uri = "urn:" + uuid.toString();

You may also use another form appropriate to your extension.

Note: when web sites install generators via window.sidebar.addMicrosummaryGenerator(), Firefox sets their uri attribute to urn:source:<source URL>, where <source URL> is the URL from which the generator was downloaded. In the future, Firefox may access source URLs to download updated versions of generators, so unless you are installing generators which are available from URLs, you should not use this form for your programmatically-installed generators.

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 ({{template.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

Note: because of a technical limitation ({{template.Bug(346820)}}), Firefox uses the same cache for microsummary-related requests as for user-initiated requests, so the cache headers you return apply to both. Thus if your cache headers tell Firefox not to refresh a page on your site more than once per hour, and the user reloads the page within that time period, the user will see the cached version of your page, which may not be what you want.

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.

Revision Source

<h2 name="Programmatically_installing_a_microsummary_generator"> Programmatically installing a microsummary generator </h2>
<p>To programmatically install a microsummary generator (e.g. in an extension that helps users create custom generators for their favorite sites), obtain a reference to the <a class="external" href="http://lxr.mozilla.org/mozilla/source/browser/components/microsummaries/public/nsIMicrosummaryService.idl#178">nsIMicrosummaryService interface</a> implemented by the <a class="external" href="http://lxr.mozilla.org/mozilla/source/browser/components/microsummaries/src/nsMicrosummaryService.js.in">nsMicrosummaryService component</a>, then call its <a class="external" href="http://lxr.mozilla.org/mozilla/source/browser/components/microsummaries/public/nsIMicrosummaryService.idl#191">installGenerator() method</a>, passing it an XML document containing the generator.
</p><p>For example, the following code snippet installs the microsummary generator from the <a href="en/Creating_a_Microsummary">Creating a Microsummary</a> tutorial:
</p>
<pre class="eval">var generatorText = ' \
  &lt;?xml version="1.0" encoding="UTF-8"?&gt; \
  &lt;generator xmlns="<span class="plain">http://www.mozilla.org/microsummaries/0.1</span>" \
             name="Firefox Download Count" \
             uri="urn:{835daeb3-6760-47fa-8f4f-8e4fdea1fb16}"&gt; \
    &lt;template&gt; \
      &lt;transform xmlns="<span class="plain">http://www.w3.org/1999/XSL/Transform</span>" version="1.0"&gt; \
        &lt;output method="text"/&gt; \
        &lt;template match="/"&gt; \
          &lt;value-of select="id(\'download-count\')"/&gt; \
          &lt;text&gt; Fx downloads&lt;/text&gt; \
        &lt;/template&gt; \
      &lt;/transform&gt; \
    &lt;/template&gt; \
  &lt;/generator&gt; \
';

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);
</pre>
<p>The service will install 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.
</p><p>When programmatically installing generators, you should specify a unique identifier for the generator in the "uri" attribute to 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:
</p>
<pre class="eval">urn:{835daeb3-6760-47fa-8f4f-8e4fdea1fb16}
</pre>
<p>To guarantee uniqueness, use URNs containing UUIDs generated by the <a class="external" href="http://lxr.mozilla.org/mozilla/source/xpcom/base/nsUUIDGenerator.cpp">nsUUIDGenerator component</a> via its <a class="external" href="http://lxr.mozilla.org/mozilla/source/xpcom/base/nsIUUIDGenerator.idl">nsIUUIDGenerator interface</a>:
</p>
<pre class="eval">var uuidGenerator = 
  Components.classes["@mozilla.org/uuid-generator;1"].
  getService(Components.interfaces.nsIUUIDGenerator);

var uuid = uuidGenerator.generateUUID();

var uri = "urn:" + uuid.toString();
</pre>
<p>You may also use another form appropriate to your extension.
</p><p>Note: when web sites install generators via window.sidebar.addMicrosummaryGenerator(), Firefox sets their <code>uri</code> attribute to <code>urn:source:&lt;source URL&gt;</code>, where &lt;source URL&gt; is the URL from which the generator was downloaded.  In the future, Firefox may access source URLs to download updated versions of generators, so unless you are installing generators which are available from URLs, you should not use this form for your programmatically-installed generators.
</p>
<h2 name="Differentiating_between_user-initiated_and_microsummary-related_requests"> Differentiating between user-initiated and microsummary-related requests </h2>
<p>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 ({{template.Bug(340746)}}), it does download CSS stylesheets referenced by the page.)
</p><p>Firefox includes the <code>X-Moz</code> request header with these requests.  It sets the value of the header to the string <code>microsummary</code>.  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 <code>X-Moz</code> request header.
</p><p>If the <code>X-Moz</code> header is present, and its value is <code>microsummary</code>, then the request is a microsummary-related request.  Otherwise, it is a user-initiated request.
</p><p><br>
</p>
<h2 name="Controlling_the_frequency_of_microsummary_requests"> Controlling the frequency of microsummary requests </h2>
<p>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 <code>Expires</code> or <code>Cache-Control</code> header in your response to a microsummary-related request.
</p><p>For example, you might include the following header in your response to prevent Firefox from making another microsummary-related request for one hour:
</p>
<pre class="eval">Cache-Control: max-age=3600
</pre>
<p>Note: because of a technical limitation ({{template.Bug(346820)}}), Firefox uses the same cache for microsummary-related requests as for user-initiated requests, so the cache headers you return apply to both.  Thus if your cache headers tell Firefox not to refresh a page on your site more than once per hour, and the user reloads the page within that time period, the user will see the cached version of your page, which may not be what you want.
</p><p>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.
</p>
Revert to this revision