[html5] r4989 - [e] (0) Add some exposition about state objects.

[whatwg at whatwg.org]

Author: ianh
Date: 2010-04-08 18:52:17 -0700 (Thu, 08 Apr 2010)
New Revision: 4989

Modified:
   complete.html
   index
   source
Log:
[e] (0) Add some exposition about state objects.

Modified: complete.html
===================================================================
--- complete.html	2010-04-09 00:26:02 UTC (rev 4988)
+++ complete.html	2010-04-09 01:52:17 UTC (rev 4989)
@@ -55093,7 +55093,30 @@
   (or script) goes back in the history, thus enabling authors to use
   the "navigation" metaphor even in one-page applications.</p>
 
-  <p>At any point, one of the entries in the session history is the
+  <div class=note>
+
+   <p><a href=#state-object title="state object">State objects</a> are intended to
+   be used for two main purposes: first, storing a preparsed
+   description of the state in the <a href=#url>URL</a> so that in the
+   simple case an author doesn't have to do the parsing (though one
+   would still need the parsing for handling <a href=#url title=URL>URLs</a> passed around by users, so it's only a minor
+   optimization), and second, so that the author can store state that
+   one wouldn't store in the URL because it only applies to the current
+   <code><a href=#document>Document</a></code> instance and it would have to be reconstructed
+   if a new <code><a href=#document>Document</a></code> were opened.</p>
+
+   <p>An example of the latter would be something like keeping track of
+   the precise coordinate from which a popup <code><a href=#the-div-element>div</a></code> was made
+   to animate, so that if the user goes back, it can be made to animate
+   to the same location. Or alternatively, it could be used to keep a
+   pointer into a cache of data that would be fetched from the server
+   based on the information in the <a href=#url>URL</a>, so that when going
+   back and forward, the information doesn't have to be fetched
+   again.</p>
+
+  </div>
+
+  <hr><p>At any point, one of the entries in the session history is the
   <dfn id=current-entry>current entry</dfn>. This is the entry representing the
   <a href=#active-document>active document</a> of the <a href=#browsing-context>browsing
   context</a>. The <a href=#current-entry>current entry</a> is usually an entry

Modified: index
===================================================================
--- index	2010-04-09 00:26:02 UTC (rev 4988)
+++ index	2010-04-09 01:52:17 UTC (rev 4989)
@@ -54994,7 +54994,30 @@
   (or script) goes back in the history, thus enabling authors to use
   the "navigation" metaphor even in one-page applications.</p>
 
-  <p>At any point, one of the entries in the session history is the
+  <div class=note>
+
+   <p><a href=#state-object title="state object">State objects</a> are intended to
+   be used for two main purposes: first, storing a preparsed
+   description of the state in the <a href=#url>URL</a> so that in the
+   simple case an author doesn't have to do the parsing (though one
+   would still need the parsing for handling <a href=#url title=URL>URLs</a> passed around by users, so it's only a minor
+   optimization), and second, so that the author can store state that
+   one wouldn't store in the URL because it only applies to the current
+   <code><a href=#document>Document</a></code> instance and it would have to be reconstructed
+   if a new <code><a href=#document>Document</a></code> were opened.</p>
+
+   <p>An example of the latter would be something like keeping track of
+   the precise coordinate from which a popup <code><a href=#the-div-element>div</a></code> was made
+   to animate, so that if the user goes back, it can be made to animate
+   to the same location. Or alternatively, it could be used to keep a
+   pointer into a cache of data that would be fetched from the server
+   based on the information in the <a href=#url>URL</a>, so that when going
+   back and forward, the information doesn't have to be fetched
+   again.</p>
+
+  </div>
+
+  <hr><p>At any point, one of the entries in the session history is the
   <dfn id=current-entry>current entry</dfn>. This is the entry representing the
   <a href=#active-document>active document</a> of the <a href=#browsing-context>browsing
   context</a>. The <a href=#current-entry>current entry</a> is usually an entry

Modified: source
===================================================================
--- source	2010-04-09 00:26:02 UTC (rev 4988)
+++ source	2010-04-09 01:52:17 UTC (rev 4989)
@@ -61987,6 +61987,32 @@
   (or script) goes back in the history, thus enabling authors to use
   the "navigation" metaphor even in one-page applications.</p>
 
+  <div class="note">
+
+   <p><span title="state object">State objects</span> are intended to
+   be used for two main purposes: first, storing a preparsed
+   description of the state in the <span>URL</span> so that in the
+   simple case an author doesn't have to do the parsing (though one
+   would still need the parsing for handling <span
+   title="URL">URLs</span> passed around by users, so it's only a minor
+   optimization), and second, so that the author can store state that
+   one wouldn't store in the URL because it only applies to the current
+   <code>Document</code> instance and it would have to be reconstructed
+   if a new <code>Document</code> were opened.</p>
+
+   <p>An example of the latter would be something like keeping track of
+   the precise coordinate from which a popup <code>div</code> was made
+   to animate, so that if the user goes back, it can be made to animate
+   to the same location. Or alternatively, it could be used to keep a
+   pointer into a cache of data that would be fetched from the server
+   based on the information in the <span>URL</span>, so that when going
+   back and forward, the information doesn't have to be fetched
+   again.</p>
+
+  </div>
+
+  <hr>
+
   <p>At any point, one of the entries in the session history is the
   <dfn>current entry</dfn>. This is the entry representing the
   <span>active document</span> of the <span>browsing