mozilla

Revision 287114 of Recursos offline no Firefox

  • Slug da revisão: Recursos_offline_no_Firefox
  • Título da revisão: Recursos offline no Firefox
  • ID da revisão: 287114
  • Criado:
  • Autor: Leandro Mercês Xavier
  • É revisão atual? Sim
  • Comentário page created, 2020 words added

Conteúdo da revisão

{{ gecko_minversion_header("1.9.1") }}

Firefox 3.5 supports the HTML 5 specification for offline caching of web applications' resources; this is done using the application cache -- a collection of resources obtained from a resource manifest provided by the web application.

{{ fx_minversion_note(3, "Parts of this specification were supported by Firefox 3; however, the specification has changed since Firefox 3 shipped, so targeting Firefox 3 for web application support is not covered here.") }}

Terminology

This section defines a few terms that will be helpful to understand while reading this documentation.

cache manifest
A cache manifest is a file that describes the resources that should be cached for offline use.
Client ID
The client ID is the client ID used by the {{ interface("nsICacheService") }} interface when managing the application cache.  This is an opaque string, created when a new application cache is created.
cache group
A cache group is a set of the different versions of a cache for the same cache manifest.
Group ID
The group ID is the URI of a cache manifest file. All caches that share the same manifest are in the same application cache group.

The application cache

Each web application's resource manifest has its own application cache.  Since applications can share resources (and can even share the same manifest URI), each application's cache has a separate copy of each shared resource.  These caches are versioned; each time the site is visited while online, a new version of the application is synched into the application cache.  That new version will be used on the next visit to the site.

How the application cache works

The application cache modifies the process of loading a document; items in the application cache are now loaded directly from the cache, without accessing the network (other than to update the copy of the web application in the cache; this is done in the background and doesn't affect performance significantly).

Application caches can also become obsolete.  If the manifest is removed from the server, Firefox now removes all application caches that use that manifest, then sends an "obsoleted" event to the application cache object.  Then the application cache's status is set to OBSOLETE.

Example work flow

This section offers an example of the work flow of how loading a page works with the cache.  If you're an end user of the caching mechanism, you don't really need to know this, but it's useful if you're developing Firefox or embedding Gecko.

Let's assume you have a cache manifest located at http://www.foo.com/cache.manifest, which includes two resources: test.html and test.png.  Loading test.html results in the following steps being taken:

The HTTP channel calls the {{ interface("nsIApplicationCacheService") }} method {{ ifmethod("nsIApplicationCacheService", "chooseApplicationCache") }} to select the appropriate group ID for the requested resource:

appCache = nsIApplicationCacheService::ChooseApplicationCache("http://www.foo.com/test.html");

This returns the most recent application cache in the group identified by group ID "http://www.foo.com/cache.manifest".  Then, the HTTP channel does something similar to the following:

cacheSession = nsICacheSerivce::CreateSession(appCache.clientID, STORAGE_OFFLINE, true);
cacheEntry = cacheSession.openCacheEntry("http://www.foo.com/test.html");

This creates a cache session and opens the requested resource from within the cache.  From this point on, it loads the data from cacheEntry, but without validation.

When test.html is loading, the docshell tells sub-loads to use the same application cache that was found by the call to chooseApplicationCache(), so that any resources loaded by test.html will also be loaded from the same cache.

Application cache states

Each application cache has a state, which indicates the current condition of the cache.  Caches that share the same manifest URI share the same cache state, which will be one of the following:

UNCACHED
A special value that indicates that an application cache object is not fully initialized.
IDLE
The application cache is not currently in the process of being updated.
CHECKING
The manifest is being fetched and checked for updates.
DOWNLOADING
Resources are being downloaded to be added to the cache, due to a changed resource manifest.
UPDATEREADY
There is a new version of the application cache available.  There is a corresponding updateready event, which is fired instead of the cached event when a new update has been downloaded but not yet activated using the swapCache() method.
OBSOLETE
The application cache group is now obsolete.

Resources in the application cache

The cache always includes at least one resource, identified by URI.  All resources fit into one of the following categories:

Master entries
These are resources added to the cache because a browsing context visited by the user included a document that indicated that it was in this cache using its manifest attribute.
The manifest
This is the resource manifest itself, loaded from the URI specified in an implicit entry's html element's manifest attribute. The manifest is downloaded and processed during the application cache update process. Implicit entries must have the same scheme, host, and port as the manifest.
Explicit entries
These are resources listed in the cache's manifest.
Fallback entries
These are resources that were listed in the cache's manifest as fallback entries. {{ fx_minversion_inline(3.5) }}
Note: Resources can be tagged with multiple categories, and can therefore be categorized as multiple entries.  For example, an entry can be both an explicit entry and a fallback entry.

Master entries

Master entries are any HTML files that include a manifest attribute in their <html> element.  For example, let's say we have the HTML file http://www.foo.bar/entry.html, which looks like this:

<html manifest="foo.manifest">
<h1>Entry</h1>
</html>

If entry.html isn't included in the manifest, visiting the entry.html page causes entry.html to be added to the application cache as a master entry.

Fallback entries

Fallback entries are used when an attempt to load a resource fails.  For example, imagine that there is a cache manifest located at http://www.foo.bar/test.manifest, with the following contents:

CACHE MANIFEST
FALLBACK:
foo/bar/ foo.html

Any request to http://www.foo.bar/foo/bar/ or its subdirectories and their contents will cause a network request to attempt to load the requested resource.  If the attempt fails, either due to a network failure or a server error of some kind, the contents of the file foo.html are loaded instead.

The online whitelist

The online whitelist may contain zero or more URIs of resources that the web application will need to access off the server rather than the offline cache. This lets the browser's security model protect the user from potential security breaches by limiting access only to approved resources.

Note: The online whitelist is ignored in versions of Firefox prior to 3.5.

This lets you ensure that, for example, scripts and other code is loaded and executed from the server instead of the cache:

CACHE MANIFEST
NETWORK:
/api

This ensures that requests to load resources contained in the http://www.foo.bar/api/ subtree will always go to the network without attempting to access them from the cache.

The cache manifest

Cache manifest files must be served with the text/cache-manifest MIME type, and all resources served using this MIME type must follow the syntax for an application cache manifest, as defined here. Cache manifests are UTF-8 format text files and may, optionally, include a BOM character. Newlines may be represented by line feed (U+000A), carriage return (U+000D), or carriage return and line feed both.

The first line of the cache manifest must consist of the string "CACHE MANIFEST" (with a single U+0020 space between the two words), followed by zero or more space or tab characters. Any other text on the line will be ignored.

The remainder of the cache manifest must be comprised of zero or more of the following lines:

Blank line
You may use blank lines comprised of zero or more space and tab characters.
Comment
Comments consist of zero or more tabs or spaces followed by a single "#" character, followed by zero or more characters of comment text. Comments may only be used on their own lines, and cannot be appended to other lines.
Section header
Section headers specify which section of the cache manifest is being manipulated. There are three possible section headers:
Section header Description
CACHE: Switches to the explicit section. This is the default section.
FALLBACK: Switches to the fallback section.

{{ fx_minversion_note(3.5, "The fallback section is ignored by versions of Firefox prior to 3.5.") }}

NETWORK: Switches to the online whitelist section.

{{ fx_minversion_note(3.5, "The online whitelist section is ignored by versions of Firefox prior to 3.5.") }}

The section header line may include whitespaces, but must include the colon in the section name.
Data for the current section
The format of data lines varies from section to section. In the explicit section, each line is a valid URI or IRI reference to a resource to cache. Whitespace is allowed before and after the URI or IRI on each line.

Cache manifests may switch back and forth from section to section at will (so each section header can be used more than once), and sections are allowed to be empty.

Note: Relative URIs are relative to the cache manifest's URI, not to the URI of the document referencing the manifest.

A sample cache manifest

This is a simple cache manifest for an imaginary web site at foo.com.

CACHE MANIFEST
# v1
# This is a comment.
http://www.foo.com/index.html
http://www.foo.com/header.png
http://www.foo.com/blah/blah

In this example, there is no section header, so all data lines are assumed to be in the explicit section.

The "v1" comment is there for a good reason. Because the cache is only updated when the manifest changes, if you change the resources (for example, updating the header.png image with new content), you need to change the manifest file in order to let the browser know that it needs to refresh the cache. You can do this by any tweak to the manifest, but having a version number is a good way to do it.

Specifying a cache manifest

To tell Firefox to use offline application caching for a given web site, the site needs to use the manifest attribute on the html element, like this:

<html manifest="http://www.foo.com/cache-manifest">
  ...
</html>

The update process

  1. When Firefox visits a document that includes a manifest attribute, it sends a checking event to the window.applicationCache object, then fetches the manifest file, following the appropriate HTTP caching rules. If the currently-cached copy of the manifest is up-to-date, the noupdate event is sent to the applicationCache, and the update process is complete.
  2. If the manifest file hasn't changed since the last update check, again, the noupdate event is sent to the applicationCache, and the update process is complete. Again, this is why if you change the resources, you need to change the manifest file so Firefox knows it needs to re-cache the resources.
  3. If the manifest file has changed, all files in the manifest -- as well as those added to the cache by calling applicationCache.add() -- are fetched into a temporary cache, following the appropriate HTTP caching rules. For each file fetched into the cache, a progress event is sent to the applicationCache object. If any errors occur, an error event is sent, and the update halts.
  4. Once all the files have been successfully retrieved, they are moved into the real offline cache atomically, and a cached event is sent to the applicationCache object.

See also

{{ languages( { "es": "es/Recursos_en_modo_desconectado_en_Firefox", "fr": "fr/Ressources_hors_ligne_dans_Firefox", "ja": "ja/Offline_resources_in_Firefox", "pl": "pl/Zasoby_offline_w_Firefoksie", "zh-tw": "zh_tw/Offline_resources_on_Firefox" } ) }}

Fonte da revisão

<p>{{ gecko_minversion_header("1.9.1") }}</p>
<p>Firefox 3.5 supports the HTML 5 specification for offline caching of web applications' resources; this is done using the <em>application cache</em> -- a collection of resources obtained from a <strong>resource manifest</strong> provided by the web application.</p>
<p>{{ fx_minversion_note(3, "Parts of this specification were supported by Firefox 3; however, the specification has changed since Firefox 3 shipped, so targeting Firefox 3 for web application support is not covered here.") }}</p>
<h2 id="Terminology">Terminology</h2>
<p>This section defines a few terms that will be helpful to understand while reading this documentation.</p>
<dl><dt>cache manifest<br>
</dt><dd>A cache manifest is a file that describes the resources that should be cached for offline use.<br>
</dd><dt>Client ID</dt><dd>The client ID is the client ID used by the {{ interface("nsICacheService") }} interface when managing the application cache.  This is an opaque string, created when a new application cache is created.<br>
</dd><dt>cache group</dt><dd>A cache group is a set of the different versions of a cache for the same cache manifest.<br>
</dd><dt>Group ID</dt><dd>The group ID is the URI of a cache manifest file. All caches that share the same manifest are in the same application cache group.</dd></dl>
<h2 id="The_application_cache">The application cache</h2>
<p>Each web application's resource manifest has its own application cache.  Since applications can share resources (and can even share the same manifest URI), each application's cache has a separate copy of each shared resource.  These caches are versioned; each time the site is visited while online, a new version of the application is synched into the application cache.  That new version will be used on the next visit to the site.</p>
<h3 id="How_the_application_cache_works">How the application cache works</h3>
<p>The application cache modifies the process of loading a document; items in the application cache are now loaded directly from the cache, without accessing the network (other than to update the copy of the web application in the cache; this is done in the background and doesn't affect performance significantly).</p>
<p>Application caches can also become obsolete.  If the manifest is removed from the server, Firefox now removes all application caches that use that manifest, then sends an "obsoleted" event to the application cache object.  Then the application cache's status is set to <code>OBSOLETE</code>.</p>
<h4 id="Example_work_flow">Example work flow</h4>
<p>This section offers an example of the work flow of how loading a page works with the cache.  If you're an end user of the caching mechanism, you don't really need to know this, but it's useful if you're developing Firefox or embedding Gecko.</p>
<p>Let's assume you have a cache manifest located at <a class=" external" href="http://www.foo.com/cache.manifest" rel="freelink">http://www.foo.com/cache.manifest</a>, which includes two resources: <code>test.html</code> and <code>test.png</code>.  Loading <code>test.html</code> results in the following steps being taken:</p>
<p>The HTTP channel calls the {{ interface("nsIApplicationCacheService") }} method {{ ifmethod("nsIApplicationCacheService", "chooseApplicationCache") }} to select the appropriate group ID for the requested resource:</p>
<pre>appCache = nsIApplicationCacheService::ChooseApplicationCache("http://www.foo.com/test.html");
</pre>
<p>This returns the most recent application cache in the group identified by group ID "<a class=" external" href="http://www.foo.com/cache.manifest" rel="freelink">http://www.foo.com/cache.manifest</a>".  Then, the HTTP channel does something similar to the following:</p>
<pre>cacheSession = nsICacheSerivce::CreateSession(appCache.clientID, STORAGE_OFFLINE, true);
cacheEntry = cacheSession.openCacheEntry("http://www.foo.com/test.html");
</pre>
<p>This creates a cache session and opens the requested resource from within the cache.  From this point on, it loads the data from <code>cacheEntry</code>, but without validation.</p>
<p>When <code>test.html</code> is loading, the docshell tells sub-loads to use the same application cache that was found by the call to <code>chooseApplicationCache()</code>, so that any resources loaded by <code>test.html</code> will also be loaded from the same cache.</p>
<h3 id="Application_cache_states">Application cache states</h3>
<p>Each application cache has a <strong>state</strong>, which indicates the current condition of the cache.  Caches that share the same manifest URI share the same cache state, which will be one of the following:</p>
<dl><dt><code>UNCACHED</code></dt><dd>A special value that indicates that an application cache object is not fully initialized.</dd><dt><code>IDLE</code></dt><dd>The application cache is not currently in the process of being updated.</dd><dt><code>CHECKING</code></dt><dd>The manifest is being fetched and checked for updates.</dd><dt><code>DOWNLOADING</code></dt><dd>Resources are being downloaded to be added to the cache, due to a changed resource manifest.<br>
</dd><dt><code>UPDATEREADY</code></dt><dd>There is a new version of the application cache available.  There is a corresponding <code>updateready</code> event, which is fired instead of the <code>cached</code> event when a new update has been downloaded but not yet activated using the <code>swapCache()</code> method.<br>
</dd><dt><code>OBSOLETE</code></dt><dd>The application cache group is now obsolete.</dd></dl>
<h3 id="Resources_in_the_application_cache">Resources in the application cache</h3>
<p>The cache always includes at least one resource, identified by URI.  All resources fit into one of the following categories:</p>
<dl><dt>Master entries </dt><dd>These are resources added to the cache because a browsing context visited by the user included a document that indicated that it was in this cache using its <code>manifest</code> attribute. </dd><dt>The manifest </dt><dd>This is the resource manifest itself, loaded from the URI specified in an implicit entry's <code>html</code> element's <code>manifest</code> attribute. The manifest is downloaded and processed during the application cache update process. Implicit entries must have the same scheme, host, and port as the manifest. </dd><dt>Explicit entries </dt><dd>These are resources listed in the cache's manifest. </dd><dt>Fallback entries </dt><dd>These are resources that were listed in the cache's manifest as fallback entries. {{ fx_minversion_inline(3.5) }} </dd></dl>
<div class="note"><strong>Note:</strong> Resources can be tagged with multiple categories, and can therefore be categorized as multiple entries.  For example, an entry can be both an explicit entry and a fallback entry.</div>
<h4 id="Master_entries">Master entries</h4>
<p>Master entries are any HTML files that include a manifest attribute in their <code>&lt;html&gt;</code> element.  For example, let's say we have the HTML file <code><a class=" external" href="http://www.foo.bar/entry.html" rel="freelink">http://www.foo.bar/entry.html</a></code>, which looks like this:</p>
<pre>&lt;html manifest="foo.manifest"&gt;
&lt;h1&gt;Entry&lt;/h1&gt;
&lt;/html&gt;
</pre>
<p>If <code>entry.html</code> isn't included in the manifest, visiting the <code>entry.html</code> page causes <code>entry.html</code> to be added to the application cache as a master entry.</p>
<h4 id="Fallback_entries">Fallback entries</h4>
<p>Fallback entries are used when an attempt to load a resource fails.  For example, imagine that there is a cache manifest located at <code><a class=" external" href="http://www.foo.bar/test.manifest" rel="freelink">http://www.foo.bar/test.manifest</a></code>, with the following contents:</p>
<pre>CACHE MANIFEST
FALLBACK:
foo/bar/ foo.html
</pre>
<p>Any request to <code><a class=" external" href="http://www.foo.bar/foo/bar/" rel="freelink">http://www.foo.bar/foo/bar/</a></code> or its subdirectories and their contents will cause a network request to attempt to load the requested resource.  If the attempt fails, either due to a network failure or a server error of some kind, the contents of the file <code>foo.html</code> are loaded instead.</p>
<h4 id="The_online_whitelist">The online whitelist</h4>
<p>The online whitelist may contain zero or more URIs of resources that the web application will need to access off the server rather than the offline cache. This lets the browser's security model protect the user from potential security breaches by limiting access only to approved resources.</p>
<div class="note"><strong>Note:</strong> The online whitelist is ignored in versions of Firefox prior to 3.5.</div>
<p>This lets you ensure that, for example, scripts and other code is loaded and executed from the server instead of the cache:</p>
<pre>CACHE MANIFEST
NETWORK:
/api
</pre>
<p>This ensures that requests to load resources contained in the <code><a class=" external" href="http://www.foo.bar/api/" rel="freelink">http://www.foo.bar/api/</a></code> subtree will always go to the network without attempting to access them from the cache.</p>
<h2 id="The_cache_manifest">The cache manifest</h2>
<p>Cache manifest files must be served with the <code>text/cache-manifest</code> MIME type, and all resources served using this MIME type must follow the syntax for an application cache manifest, as defined here. Cache manifests are UTF-8 format text files and may, optionally, include a BOM character. Newlines may be represented by line feed (U+000A), carriage return (U+000D), or carriage return and line feed both.</p>
<p>The first line of the cache manifest must consist of the string "CACHE MANIFEST" (with a single U+0020 space between the two words), followed by zero or more space or tab characters. Any other text on the line will be ignored.</p>
<p>The remainder of the cache manifest must be comprised of zero or more of the following lines:</p>
<dl><dt>Blank line </dt><dd>You may use blank lines comprised of zero or more space and tab characters. </dd><dt>Comment </dt><dd>Comments consist of zero or more tabs or spaces followed by a single "#" character, followed by zero or more characters of comment text. Comments may only be used on their own lines, and cannot be appended to other lines. </dd><dt>Section header </dt><dd>Section headers specify which section of the cache manifest is being manipulated. There are three possible section headers: </dd></dl> <blockquote>
<table class="standard-table"> <tbody> <tr> <th>Section header</th> <th>Description</th> </tr> <tr> <td><code>CACHE:</code></td> <td>Switches to the explicit section. This is the default section.</td> </tr> <tr> <td><code>FALLBACK:</code></td> <td>Switches to the fallback section. <p>{{ fx_minversion_note(3.5, "The fallback section is ignored by versions of Firefox prior to 3.5.") }}</p> </td> </tr> <tr> <td><code>NETWORK:</code></td> <td>Switches to the online whitelist section. <p>{{ fx_minversion_note(3.5, "The online whitelist section is ignored by versions of Firefox prior to 3.5.") }}</p> </td> </tr> </tbody>
</table>
</blockquote> <dl><dd>The section header line may include whitespaces, but must include the colon in the section name. </dd><dt>Data for the current section </dt><dd>The format of data lines varies from section to section. In the explicit section, each line is a valid URI or IRI reference to a resource to cache. Whitespace is allowed before and after the URI or IRI on each line. </dd></dl>
<p>Cache manifests may switch back and forth from section to section at will (so each section header can be used more than once), and sections are allowed to be empty.</p>
<div class="note"><strong>Note: </strong>Relative URIs are relative to the cache manifest's URI, not to the URI of the document referencing the manifest.</div>
<h4 id="A_sample_cache_manifest" name="A_sample_cache_manifest">A sample cache manifest</h4>
<p>This is a simple cache manifest for an imaginary web site at <span class="nowiki">foo.com</span>.</p>
<pre class="eval">CACHE MANIFEST
# v1
# This is a comment.
<span class="nowiki">http://www.foo.com/index.html</span>
<span class="nowiki">http://www.foo.com/header.png</span>
<span class="nowiki">http://www.foo.com/blah/blah</span>
</pre>
<p>In this example, there is no section header, so all data lines are assumed to be in the explicit section.</p>
<p>The "v1" comment is there for a good reason. Because the cache is only updated when the manifest changes, if you change the resources (for example, updating the <code>header.png</code> image with new content), you need to change the manifest file in order to let the browser know that it needs to refresh the cache. You can do this by any tweak to the manifest, but having a version number is a good way to do it.</p>
<h2 id="Specifying_a_cache_manifest">Specifying a cache manifest</h2>
<p>To tell Firefox to use offline application caching for a given web site, the site needs to use the <code>manifest</code> attribute on the <code>html</code> element, like this:</p>
<pre class="eval"><span class="nowiki">&lt;html manifest="http://www.foo.com/cache-manifest"&gt;</span>
  ...
&lt;/html&gt;
</pre>
<h2 id="The_update_process">The update process</h2>
<ol> <li>When Firefox visits a document that includes a <code>manifest</code> attribute, it sends a <code>checking</code> event to the <code><a href="/en/DOM/window.applicationCache" title="en/DOM/window.applicationCache">window.applicationCache</a></code> object, then fetches the manifest file, following the appropriate HTTP caching rules. If the currently-cached copy of the manifest is up-to-date, the <code>noupdate</code> event is sent to the <code>applicationCache</code>, and the update process is complete.</li> <li>If the manifest file hasn't changed since the last update check, again, the <code>noupdate</code> event is sent to the <code>applicationCache</code>, and the update process is complete. Again, this is why if you change the resources, you need to change the manifest file so Firefox knows it needs to re-cache the resources.</li> <li>If the manifest file has changed, all files in the manifest -- as well as those added to the cache by calling <code><a href="/en/nsIDOMOfflineResourceList#add.28.29" title="en/nsIDOMOfflineResourceList#add.28.29">applicationCache.add()</a></code> -- are fetched into a temporary cache, following the appropriate HTTP caching rules. For each file fetched into the cache, a <code>progress</code> event is sent to the <code>applicationCache</code> object. If any errors occur, an <code>error</code> event is sent, and the update halts.</li> <li>Once all the files have been successfully retrieved, they are moved into the real offline cache atomically, and a <code>cached</code> event is sent to the <code>applicationCache</code> object.</li>
</ol>
<h2 id="See_also">See also</h2>
<ul> <li><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#offline" title="http://www.whatwg.org/specs/web-apps/current-work/#offline">HTML 5 working draft: Offline web applications</a> </li> <li>{{ interface("nsIApplicationCache") }}</li> <li>{{ interface("nsIApplicationCacheNamespace") }}</li> <li>{{ interface("nsIApplicationCacheContainer") }}</li> <li>{{ interface("nsIApplicationCacheChannel") }}</li> <li>{{ interface("nsIApplicationCacheService") }}</li> <li>{{ interface("nsIDOMOfflineResourceList") }}</li> <li><a class="external" href="http://www.ibm.com/developerworks/web/library/wa-ffox3/">Get ready for Firefox 3.0 - A Web developer's guide to the many new features in this popular browser, especially the offline application features</a> (IBM developerWorks)</li>
</ul>
<p>{{ languages( { "es": "es/Recursos_en_modo_desconectado_en_Firefox", "fr": "fr/Ressources_hors_ligne_dans_Firefox", "ja": "ja/Offline_resources_in_Firefox", "pl": "pl/Zasoby_offline_w_Firefoksie", "zh-tw": "zh_tw/Offline_resources_on_Firefox" } ) }}</p>
Reverter para esta revisão