- From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 30 Sep 2009 07:52:34 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/spec
In directory hutz:/tmp/cvs-serv13960
Modified Files:
Overview.html
Log Message:
Make the display of the appcache UI more clearly optional, and elaborate a bit on the thinking behind the design. Also, add a note about how ApplicationCache is always present. (whatwg r4058)
Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.3219
retrieving revision 1.3220
diff -u -d -r1.3219 -r1.3220
--- Overview.html 29 Sep 2009 11:46:06 -0000 1.3219
+++ Overview.html 30 Sep 2009 07:52:30 -0000 1.3220
@@ -215,7 +215,7 @@
<h2 class="no-num no-toc" id="a-vocabulary-and-associated-apis-for-html-and-xhtml">A vocabulary and associated APIs for HTML and XHTML</h2>
<!--ZZZ:-->
<!--<h2 class="no-num no-toc">W3C Working Draft 25 August 2009</h2>-->
- <h2 class="no-num no-toc" id="editor-s-draft-29-september-2009">Editor's Draft 29 September 2009</h2>
+ <h2 class="no-num no-toc" id="editor-s-draft-30-september-2009">Editor's Draft 30 September 2009</h2>
<!--:ZZZ-->
<dl><!-- ZZZ: update the month/day (twice), (un)comment out--><!--
<dt>This Version:</dt>
@@ -317,7 +317,7 @@
track.
<!--ZZZ:-->
<!--This specification is the 25 August 2009 Working Draft.-->
- This specification is the 29 September 2009 Editor's Draft.
+ This specification is the 30 September 2009 Editor's Draft.
<!--:ZZZ-->
</p><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- relationship to other work (required) --><p>This specification is also being produced by the <a href="http://www.whatwg.org/">WHATWG</a>. The two specifications are
identical from the table of contents onwards.</p><!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><!-- context and rationale (required) --><p>This specification is intended to replace (be a new version of)
@@ -47529,7 +47529,23 @@
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
@@ -47592,9 +47608,10 @@
<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
@@ -47602,9 +47619,10 @@
<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>
@@ -47618,10 +47636,10 @@
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>
@@ -47635,12 +47653,12 @@
<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>
@@ -47674,22 +47692,23 @@
<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
@@ -47712,9 +47731,9 @@
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>
@@ -47741,10 +47760,10 @@
<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
@@ -47765,9 +47784,10 @@
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>
@@ -47798,9 +47818,10 @@
<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>
@@ -47854,8 +47875,9 @@
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>
@@ -47994,9 +48016,10 @@
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>
@@ -48062,21 +48085,23 @@
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>
@@ -48105,9 +48130,10 @@
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>
@@ -48116,10 +48142,10 @@
<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>
@@ -48417,7 +48443,12 @@
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
Received on Wednesday, 30 September 2009 07:52:38 UTC