Skip to content

Commit

Permalink
[] (0) Make the display of the appcache UI more clearly optional, and…
Browse files Browse the repository at this point in the history 
… elaborate a bit on the thinking behind the design. Also, add a note about how ApplicationCache is always present.

git-svn-id: http://svn.whatwg.org/webapps@4058 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed Sep 30, 2009
1 parent 229be4f commit 60a2e57
Show file tree
Hide file tree
Showing 2 changed files with 194 additions and 126 deletions.
157 changes: 94 additions & 63 deletions index
View file
Expand Up @@ -112,7 +112,7 @@
<div class=head>
<p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG src=/images/logo></a></p>
<h1>HTML5</h1>
<h2 class="no-num no-toc" id=draft-standard-&mdash;-29-september-2009>Draft Standard &mdash; 29 September 2009</h2>
<h2 class="no-num no-toc" id=draft-standard-&mdash;-30-september-2009>Draft Standard &mdash; 30 September 2009</h2>
<p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
<p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
<!--<p class="impl"><strong>Implementors!</strong> We have a <a href="http://www.whatwg.org/mailing-list#implementors">mailing list</a> for you too!</p>-->
Expand Down Expand Up @@ -52749,7 +52749,23 @@ NETWORK:
a <a href=#concept-appcache-manifest title=concept-appcache-manifest>manifest</a>, or for an
<a href=#application-cache-group>application cache group</a>, potentially given a particular
<a href=#cache-host>cache host</a>, and potentially given a new <a href=#concept-appcache-master title=concept-appcache-master>master</a> resource, the user
agent must run the following steps:</p>
agent must run the steps below.</p>

<p>Some of these steps have requirements that only apply if the user
agent <dfn id=shows-caching-progress>shows caching progress</dfn>. Support for this is
optional. Caching progress UI could consist of a progress bar or
message panel in the user agent's interface, or an overlay, or
something else. Certain events fired during the <a href=#application-cache-update-process>application
cache update process</a> allow the script to override the display
of such an interface. The goal of this is to allow Web applications
to provide more seamless update mechanisms, hiding from the user the
mechanics of the application cache mechanism. User agents may
display user interfaces independent of this, but are encouraged to
not show prominent update progress notifications for applications
that cancel the relevant events.</p>

<p>The <a href=#application-cache-update-process>application cache update process</a> steps are as
follows:

<ol><li><p>Optionally, wait until the permission to start the cache
update process has been obtained from the user. This could include
Expand Down Expand Up @@ -52812,19 +52828,21 @@ NETWORK:
<i>downloading</i>, then <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire
a simple event</a> called <code title=event-appcache-checking><a href=#event-appcache-checking>checking</a></code> at the
<code><a href=#applicationcache>ApplicationCache</a></code> singleton of that <a href=#cache-host>cache
host</a>. The default action of this event should be the
display of some sort of user interface indicating to the user
that the user agent is checking to see if it can download the
host</a>. The default action of this event must be, if the
user agent <a href=#shows-caching-progress>shows caching progress</a>, the display of
some sort of user interface indicating to the user that the user
agent is checking to see if it can download the
application.</li>

<li><p>If these steps were invoked with a <a href=#cache-host>cache
host</a>, and the <a href=#concept-appcache-status title=concept-appcache-status>status</a> of <var title="">cache group</var> is <i>downloading</i>, then also
<a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple event</a>
called <code title=event-appcache-downloading><a href=#event-appcache-downloading>downloading</a></code> that is
cancelable at the <code><a href=#applicationcache>ApplicationCache</a></code> singleton of that
<a href=#cache-host>cache host</a>. The default action of this event should
be the display of some sort of user interface indicating to the
user the application is being downloaded.</li>
<a href=#cache-host>cache host</a>. The default action of this event must
be, if the user agent <a href=#shows-caching-progress>shows caching progress</a>, the
display of some sort of user interface indicating to the user the
application is being downloaded.</li>

<li><p>If the <a href=#concept-appcache-status title=concept-appcache-status>status</a>
of the <var title="">cache group</var> is either <i>checking</i>
Expand All @@ -52838,10 +52856,10 @@ NETWORK:
group</var>, <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple
event</a> that is cancelable called <code title=event-appcache-checking><a href=#event-appcache-checking>checking</a></code> at the
<code><a href=#applicationcache>ApplicationCache</a></code> singleton of the <a href=#cache-host>cache
host</a>. The default action of these events should be the
display of some sort of user interface indicating to the user
that the user agent is checking for the availability of
updates.</li>
host</a>. The default action of these events must be, if the
user agent <a href=#shows-caching-progress>shows caching progress</a>, the display of
some sort of user interface indicating to the user that the user
agent is checking for the availability of updates.</li>

</ol><p>The remainder of the steps run asynchronously.</p>

Expand All @@ -52855,12 +52873,12 @@ NETWORK:
<li><p>If this is a <a href=#concept-appcache-cache title=concept-appcache-cache>cache
attempt</a>, then this algorithm was invoked with a <a href=#cache-host>cache
host</a>; <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple
event</a> called <code title=event-appcache-checking><a href=#event-appcache-checking>checking</a></code>
that is cancelable at the <code><a href=#applicationcache>ApplicationCache</a></code> singleton
of that <a href=#cache-host>cache host</a>. The default action of this event
should be the display of some sort of user interface indicating to
the user that the user agent is checking for the availability of
updates.</li>
event</a> called <code title=event-appcache-checking><a href=#event-appcache-checking>checking</a></code> that is cancelable
at the <code><a href=#applicationcache>ApplicationCache</a></code> singleton of that <a href=#cache-host>cache
host</a>. The default action of this event must be, if the user
agent <a href=#shows-caching-progress>shows caching progress</a>, the display of some sort
of user interface indicating to the user that the user agent is
checking for the availability of updates.</li>

<li>

Expand Down Expand Up @@ -52894,22 +52912,23 @@ NETWORK:
<li><p>For each <a href=#cache-host>cache host</a> associated with an
<a href=#application-cache>application cache</a> in <var title="">cache
group</var>, <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple
event</a> called <code title=event-appcache-obsolete><a href=#event-appcache-obsolete>obsolete</a></code>
that is cancelable at the <code><a href=#applicationcache>ApplicationCache</a></code> singleton
of the <a href=#cache-host>cache host</a>. The default action of these
events should be the display of some sort of user interface
indicating to the user that the application is no longer
available for offline use.</li>
event</a> called <code title=event-appcache-obsolete><a href=#event-appcache-obsolete>obsolete</a></code> that is
cancelable at the <code><a href=#applicationcache>ApplicationCache</a></code> singleton of the
<a href=#cache-host>cache host</a>. The default action of these events must
be, if the user agent <a href=#shows-caching-progress>shows caching progress</a>, the
display of some sort of user interface indicating to the user
that the application is no longer available for offline
use.</li>

<li><p>For each entry in <var title="">cache group</var>'s <a href=#concept-appcache-pending-masters title=concept-appcache-pending-masters>list of pending master
entries</a>, <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple
event</a> that is cancelable called <code title=event-appcache-error><a href=#event-appcache-error>error</a></code> (not <code title=event-appcache-obsolete><a href=#event-appcache-obsolete>obsolete</a></code>!) at the
<code><a href=#applicationcache>ApplicationCache</a></code> singleton of the <a href=#cache-host>cache
host</a> the <code>Document</code> for this entry, if there
still is one. The default action of this event should be the
display of some sort of user interface indicating to the user
that the user agent failed to save the application for offline
use.</li>
still is one. The default action of this event must be, if the
user agent <a href=#shows-caching-progress>shows caching progress</a>, the display of
some sort of user interface indicating to the user that the user
agent failed to save the application for offline use.</li>

<li><p>If <var title="">cache group</var> has an
<a href=#application-cache>application cache</a> whose <a href=#concept-appcache-completeness title=concept-appcache-completeness>completeness flag</a> is
Expand All @@ -52932,9 +52951,9 @@ NETWORK:
there is a DNS error, or the connection times out, or the user
cancels the download, or the parser for manifests fails when
checking the magic signature), or if the server returned a
redirect, or if the resource is labeled with a <a href=#mime-type>MIME type</a> other
than <code><a href=#text/cache-manifest>text/cache-manifest</a></code>, then run the <a href=#cache-failure-steps>cache
failure steps</a>.</p>
redirect, or if the resource is labeled with a <a href=#mime-type>MIME
type</a> other than <code><a href=#text/cache-manifest>text/cache-manifest</a></code>, then run
the <a href=#cache-failure-steps>cache failure steps</a>.</p>

</li>

Expand All @@ -52961,10 +52980,10 @@ NETWORK:
<a href=#fire-a-simple-event>fire a simple event</a> that is cancelable called <code title=event-appcache-error><a href=#event-appcache-error>error</a></code> at the
<code><a href=#applicationcache>ApplicationCache</a></code> singleton of the <a href=#cache-host>cache
host</a> the <code>Document</code> for this entry, if there
still is one. The default action of this event should be the
display of some sort of user interface indicating to the user
that the user agent failed to save the application for offline
use.</p>
still is one. The default action of this event must be, if the
user agent <a href=#shows-caching-progress>shows caching progress</a>, the display of
some sort of user interface indicating to the user that the user
agent failed to save the application for offline use.</p>

<p>Otherwise, associate the <code>Document</code> for this entry
with <var title="">cache</var>; store the resource for this
Expand All @@ -52985,9 +53004,10 @@ NETWORK:
group</var>, <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple
event</a> that is cancelable called <code title=event-appcache-noupdate><a href=#event-appcache-noupdate>noupdate</a></code> at the
<code><a href=#applicationcache>ApplicationCache</a></code> singleton of the <a href=#cache-host>cache
host</a>. The default action of these events should be the
display of some sort of user interface indicating to the user
that the application is up to date.</li>
host</a>. The default action of these events must be, if the
user agent <a href=#shows-caching-progress>shows caching progress</a>, the display of
some sort of user interface indicating to the user that the
application is up to date.</li>

<li><p>Empty <var title="">cache group</var>'s <a href=#concept-appcache-pending-masters title=concept-appcache-pending-masters>list of pending master
entries</a>.</li>
Expand Down Expand Up @@ -53018,9 +53038,10 @@ NETWORK:
<a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple event</a> that
is cancelable called <code title=event-appcache-downloading><a href=#event-appcache-downloading>downloading</a></code> at the
<code><a href=#applicationcache>ApplicationCache</a></code> singleton of the <a href=#cache-host>cache
host</a>. The default action of these events should be the
display of some sort of user interface indicating to the user that
a new version is being downloaded.</li>
host</a>. The default action of these events must be, if the
user agent <a href=#shows-caching-progress>shows caching progress</a>, the display of some
sort of user interface indicating to the user that a new version is
being downloaded.</li>

<li><p>Let <var title="">file list</var> be an empty list of
URLs with flags.</li>
Expand Down Expand Up @@ -53074,8 +53095,9 @@ NETWORK:
set to the number of files in <var title="">file list</var>, and
the <code title=dom-ProgressEvents-loaded>loaded</code>
attribute must be set to the number of number of files in <var title="">file list</var> that have been downloaded so far. The
default action of these events should be the display of some sort
of user interface indicating to the user that a file is being
default action of these events must be, if the user agent
<a href=#shows-caching-progress>shows caching progress</a>, the display of some sort of
user interface indicating to the user that a file is being
downloaded in preparation for updating the application.</li>

<li>
Expand Down Expand Up @@ -53214,9 +53236,10 @@ NETWORK:
event</a> that is cancelable called <code title=event-appcache-error><a href=#event-appcache-error>error</a></code> at the
<code><a href=#applicationcache>ApplicationCache</a></code> singleton of the
<code>Document</code> for this entry, if there still is one. The
default action of this event should be the display of some sort
of user interface indicating to the user that the user agent
failed to save the application for offline use.</p>
default action of this event must be, if the user agent
<a href=#shows-caching-progress>shows caching progress</a>, the display of some sort of
user interface indicating to the user that the user agent failed
to save the application for offline use.</p>

<li>

Expand Down Expand Up @@ -53282,21 +53305,23 @@ NETWORK:
group</var>, <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple
event</a> that is cancelable called <code title=event-appcache-cached><a href=#event-appcache-cached>cached</a></code> at the
<code><a href=#applicationcache>ApplicationCache</a></code> singleton of the <a href=#cache-host>cache
host</a>. The default action of these events should be the
display of some sort of user interface indicating to the user that
the application has been cached and that they can now use it
host</a>. The default action of these events must be, if the
user agent <a href=#shows-caching-progress>shows caching progress</a>, the display of
some sort of user interface indicating to the user that the
application has been cached and that they can now use it
offline.</p>

<p>Otherwise, it is an <a href=#concept-appcache-upgrade title=concept-appcache-upgrade>upgrade attempt</a>. For each
<a href=#cache-host>cache host</a> associated with an <a href=#application-cache>application
cache</a> in <var title="">cache group</var>, <a href=#queue-a-task>queue a
task</a> to <a href=#fire-a-simple-event>fire a simple event</a> that is cancelable
called <code title=event-appcache-updateready><a href=#event-appcache-updateready>updateready</a></code> at the
<code><a href=#applicationcache>ApplicationCache</a></code> singleton of the <a href=#cache-host>cache
host</a>. The default action of these events should be the
display of some sort of user interface indicating to the user that
a new version is available and that they can activate it by
reloading the page.</p>
called <code title=event-appcache-updateready><a href=#event-appcache-updateready>updateready</a></code>
at the <code><a href=#applicationcache>ApplicationCache</a></code> singleton of the <a href=#cache-host>cache
host</a>. The default action of these events must be, if the
user agent <a href=#shows-caching-progress>shows caching progress</a>, the display of
some sort of user interface indicating to the user that a new
version is available and that they can activate it by reloading
the page.</p>

</li>

Expand Down Expand Up @@ -53325,9 +53350,10 @@ NETWORK:
event</a> that is cancelable called <code title=event-appcache-error><a href=#event-appcache-error>error</a></code> at the
<code><a href=#applicationcache>ApplicationCache</a></code> singleton of the
<code>Document</code> for this entry, if there still is one. The
default action of these events should be the display of some sort
of user interface indicating to the user that the user agent
failed to save the application for offline use.</p>
default action of these events must be, if the user agent
<a href=#shows-caching-progress>shows caching progress</a>, the display of some sort of
user interface indicating to the user that the user agent failed
to save the application for offline use.</p>

</ol></li>

Expand All @@ -53336,10 +53362,10 @@ NETWORK:
<a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple event</a> that
is cancelable called <code title=event-appcache-error><a href=#event-appcache-error>error</a></code> at the
<code><a href=#applicationcache>ApplicationCache</a></code> singleton of the <a href=#cache-host>cache
host</a>. The default action of these events should be the
display of some sort of user interface indicating to the user that
the user agent failed to save the application for offline
use.</li>
host</a>. The default action of these events must be, if the
user agent <a href=#shows-caching-progress>shows caching progress</a>, the display of some
sort of user interface indicating to the user that the user agent
failed to save the application for offline use.</li>

<li><p>Empty <var title="">cache group</var>'s <a href=#concept-appcache-pending-masters title=concept-appcache-pending-masters>list of pending master
entries</a>.</li>
Expand Down Expand Up @@ -53652,7 +53678,12 @@ NETWORK:
return the <code><a href=#applicationcache>ApplicationCache</a></code> object associated with the
worker. <a href=#refsWEBWORKERS>[WEBWORKERS]</a></p>

<p>The <dfn id=dom-appcache-status title=dom-appcache-status><code>status</code></dfn>
<p class=note>A <code><a href=#window>Window</a></code> or
<code>SharedWorkerGlobalScope</code> object has an associated
<code><a href=#applicationcache>ApplicationCache</a></code> object even if that <a href=#cache-host>cache
host</a> has no actual <a href=#application-cache>application cache</a>.</p>

<hr><p>The <dfn id=dom-appcache-status title=dom-appcache-status><code>status</code></dfn>
attribute, on getting, must return the current state of the
<a href=#application-cache>application cache</a> that the
<code><a href=#applicationcache>ApplicationCache</a></code> object's <a href=#cache-host>cache host</a> is
Expand Down

0 comments on commit 60a2e57

Please sign in to comment.