mozilla

Revision 287349 of Microsummary topics

  • Revision slug: Microsummary_topics
  • Revision title: Microsummary topics
  • Revision id: 287349
  • Created:
  • Creator: Sheppy
  • Is current revision? Yes
  • Comment updated since microsummary support is gone in Gecko 6; 15 words added

Revision Content

Warning: Microsummary support was removed in Gecko 6.0 {{ geckoRelease("6.0") }}

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.

Note: When web sites install generators via window.sidebar.addMicrosummaryGenerator(), Firefox sets their uri attribute to urn:source:sourceURL, where sourceURL 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.

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
Note: Because of a technical limitation ({{ Bug(346820) }}), Firefox uses the same cache for both microsummary-related requests and 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

<div class="warning"><strong>Warning:</strong> Microsummary support was removed in Gecko 6.0 {{ geckoRelease("6.0") }}</div>
<h2 id="Programmatically_installing_a_microsummary_generator" name="Programmatically_installing_a_microsummary_generator">Programmatically installing a microsummary generator</h2>
<p>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 <a class="external" href="http://lxr.mozilla.org/mozilla/source/browser/components/microsummaries/public/nsIMicrosummaryService.idl#178"><code>nsIMicrosummaryService</code></a> interface implemented by the <a class="external" href="http://lxr.mozilla.org/mozilla/source/browser/components/microsummaries/src/nsMicrosummaryService.js.in"><code>nsIMicrosummaryService</code></a> component, then call its <code><a class="external" href="http://lxr.mozilla.org/mozilla/source/browser/components/microsummaries/public/nsIMicrosummaryService.idl#191">installGenerator()</a></code> method, 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" title="en/Creating_a_Microsummary">Creating a Microsummary</a> tutorial:</p>
<pre class="brush: js">var generatorText = ' \
  &lt;?xml version="1.0" encoding="UTF-8"?&gt; \
  &lt;generator xmlns="<span class="nowiki">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="nowiki">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;pages&gt;
      &lt;include&gt;<span class="nowiki">http://(www\.)?spreadfirefox\.com/(index\.php)?</span>&lt;/include&gt;
    &lt;/pages&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 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.</p>
<p>When programmatically installing generators, you should specify a unique identifier for the generator in the <code>uri</code> attribute of the <code>&lt;generator&gt;</code> 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 nsUUIDGenerator component. See <a href="/en/XPCOM_Interface_Reference/nsIUUIDGenerator#Generating_a_UUID" title="en/XPCOM_Interface_Reference/nsIUUIDGenerator#Generating_a_UUID">Generating a UUID</a> in the <a href="/en/XPCOM_Interface_Reference/nsIUUIDGenerator" title="en/XPCOM_Interface_Reference/nsIUUIDGenerator">nsIUUIDGenerator</a> documentation.</p>
<p>You may also use another form appropriate to your extension.</p>
<div class="note"><strong>Note:</strong> When web sites install generators via <code>window.sidebar.addMicrosummaryGenerator()</code>, Firefox sets their <code>uri</code> attribute to <code>urn:source:<em>sourceURL</em></code>, where <code><em>sourceURL</em></code> 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.</div>
<h2 id="Differentiating_between_user-initiated_and_microsummary-related_requests" 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 ({{ 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> </p>
<h2 id="Controlling_the_frequency_of_microsummary_requests" 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>
<div class="note"><strong>Note:</strong> Because of a technical limitation ({{ Bug(346820) }}), Firefox uses the same cache for both microsummary-related requests and 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.</div>
<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