Skip to content

Commit

Permalink
Add domintro blocks for “Web storage” interfaces
Browse files Browse the repository at this point in the history 
This change adds domintro blocks in the “Web storage” section and adds
markup to cause more implementor-specific parts of that section of the
spec to be supressed in the developer edition.
  • Loading branch information
@sideshowbarker
sideshowbarker committed Oct 31, 2017
1 parent a1c7bf0 commit 5323e66
Showing 1 changed file with 118 additions and 6 deletions.
124 changes: 118 additions & 6 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98143,7 +98143,7 @@ interface <dfn>WorkerLocation</dfn> {
-->

<p>The second storage mechanism is designed for storage that spans multiple windows, and lasts
beyond the current session. In particular, Web applications may wish to store megabytes of user
beyond the current session. In particular, Web applications might wish to store megabytes of user
data, such as entire user-authored documents or a user's mailbox, on the client side for
performance reasons.</p>

Expand Down Expand Up @@ -98211,6 +98211,62 @@ interface <dfn>Storage</dfn> {
implementing the <code>Storage</code> interface can all be associated with the same list of
key/value pairs simultaneously.</p>

<dl class="domintro">

<dt><var>localStorage</var> . <code subdfn data-x="dom-Storage-length">length</code></dt>
<dt><var>sessionStorage</var> . <code data-x="">length</code></dt>
<dd>
<p>Returns the number of key/value pairs currently present in the list associated with the
object.</p>
<dd>

<dt><var>localStorage</var> . <code subdfn data-x="dom-Storage-key">key</code> ( <var>n</var> )</dt>
<dt><var>sessionStorage</var> . <code data-x="">key</code> ( <var>n</var> )</dt>
<dd>
<p>Returns the name of the <var>n</var>th key in the list, or null if <var>n</var> is greater
than or equal to the number of key/value pairs in the object</p>
<dd>

<dt><var>localStorage</var> . <code subdfn data-x="dom-Storage-getItem">getItem</code> ( <var>key</var> )</dt>
<dt><var>sessionStorage</var> . <code data-x="">getItem</code> ( <var>key</var> )</dt>
<dd>
<p>Returns the current value associated with the given <var>key</var>, or null if the given
<var>key</var> does not exist in the list associated with the object.</p>
<dd>

<dt><var>localStorage</var> . <code subdfn data-x="dom-Storage-setItem">setItem</code> ( <var>key</var>, <var>value</var> )</dt>
<dt><var>sessionStorage</var> . <code data-x="">setItem</code> ( <var>key</var>, <var>value</var> )</dt>
<dd>
<p>Checks if a key/value pair with the given <var>key</var> already exists in the list associated
with the object.</p>

<p>If the given <var>key</var> does not exist, then adds a new key/value pair to the list, with
the given <var>key</var> and with its value set to <var>value</var>.</p>

<p>If the given <var>key</var> <em>does</em> exist in the list, and its value is not
equal to <var>value</var>, then updates its value to <var>value</var>.</p>

<p>Throws a <span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code> exception
if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage
for the site, or if the quota has been exceeded.)</p>

<dt><var>localStorage</var> . <code subdfn data-x="dom-Storage-removeItem">removeItem</code> ( <var>key</var> )</dt>
<dt><var>sessionStorage</var> . <code data-x="">removeItem</code> ( <var>key</var> )</dt>
<dd>
<p>Removes the key/value pair with the given <var>key</var> from the list associated with the
object, if a key/value pair with the given <var>key</var> exists.</p>
</dd>

<dt><var>localStorage</var> . <code subdfn data-x="dom-Storage-clear">clear</code>()</dt>
<dt><var>sessionStorage</var> . <code data-x="">clear</code>()</dt>
<dd>
<p>Empties the list associated with the object of all key/value pairs, if there are any.</p>
</dd>

</dl>

<div w-nodev>

<p>The <dfn><code data-x="dom-Storage-length">length</code></dfn> attribute must return the number
of key/value pairs currently present in the list associated with the object.</p>

Expand Down Expand Up @@ -98242,8 +98298,7 @@ interface <dfn>Storage</dfn> {
the method must do nothing.</p>

<p>If it couldn't set the new value, the method must throw a
<span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code> exception. (Setting could
fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.)</p>
<span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code> exception.</p>

<p>The <dfn><code data-x="dom-Storage-removeItem">removeItem(<var>key</var>)</code></dfn>
method must cause the key/value pair with the given <var>key</var> to be removed from the
Expand All @@ -98259,6 +98314,8 @@ interface <dfn>Storage</dfn> {
list associated with the object to be emptied of all key/value pairs, if there are any. If there
are none, then the method must do nothing.</p>

</div>

<p class="note">When the <code data-x="dom-Storage-setItem">setItem()</code>, <code
data-x="dom-Storage-removeItem">removeItem()</code>, and <code
data-x="dom-Storage-clear">clear()</code> methods are invoked, events are fired on the
Expand Down Expand Up @@ -98288,6 +98345,8 @@ interface <dfn>WindowSessionStorage</dfn> {
<p>Each <span>top-level browsing context</span> has a unique set of session storage areas, one for
each <span>origin</span>.</p>

<div w-nodev>

<p>User agents should not expire data from a browsing context's session storage areas, but may do
so when the user requests that such data be deleted, or when the UA detects that it has limited
storage space, or for security reasons. User agents should always avoid deleting data while a
Expand Down Expand Up @@ -98326,6 +98385,8 @@ interface <dfn>WindowSessionStorage</dfn> {
<code>Window</code> object's <code data-x="dom-sessionStorage">sessionStorage</code> attribute's
<code>Storage</code> object is associated with the same storage area, other than <var>x</var>, <span>send a storage notification</span>.</p>

</div>


<h4>The <code data-x="dom-localStorage">localStorage</code> attribute</h4>

Expand All @@ -98341,6 +98402,8 @@ interface <dfn>WindowLocalStorage</dfn> {
<!--INSERT FINGERPRINT-->
</p>

<div w-nodev>

<p>User agents must have a set of local storage areas, one for each <span>origin</span>.</p>

<p>User agents should expire data from the local storage areas only for security reasons or when
Expand Down Expand Up @@ -98383,6 +98446,8 @@ interface <dfn>WindowLocalStorage</dfn> {
<code>Window</code> object's <code data-x="dom-localStorage">localStorage</code> attribute's
<code>Storage</code> object is associated with the same storage area, other than <var>x</var>, <span>send a storage notification</span>.

</div>

<p class="warning">The <code data-x="dom-localStorage">localStorage</code> attribute provides
access to shared state. This specification does not define the interaction with other browsing
contexts in a multiprocess user agent, and authors are encouraged to assume that there is no
Expand All @@ -98395,9 +98460,11 @@ interface <dfn>WindowLocalStorage</dfn> {
<h4>The <code data-x="event-storage">storage</code> event</h4>

<p>The <code data-x="event-storage">storage</code> event is fired on a <code>Document</code>'s
<code>Window</code> object when a storage area changes, as described in the previous two sections
(<a href="#sessionStorageEvent">for session storage</a>, <a href="#localStorageEvent">for local
storage</a>).</p>
<code>Window</code> object when a storage area changes<span w-nodev>, as described in the previous
two sections (<a href="#sessionStorageEvent">for session storage</a>, <a
href="#localStorageEvent">for local storage</a>)</span>.</p>

<div w-nodev>

<p>When a user agent is to <dfn>send a storage notification</dfn> for a <code>Document</code>, the
user agent must <span>queue a task</span> to <span data-x="concept-event-fire">fire an
Expand Down Expand Up @@ -98433,6 +98500,8 @@ interface <dfn>WindowLocalStorage</dfn> {
<code>Document</code> that represents the same kind of <code>Storage</code> area as was affected
(i.e. session or local).</p>

</div>


<h5>The <code>StorageEvent</code> interface</h5>

Expand All @@ -98454,6 +98523,42 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
<span>Storage</span>? storageArea = null;
};</pre>

<dl class="domintro">

<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-key">key</code></dt>

<dd>
<p>Returns the key being changed.</p>
</dd>

<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-oldValue">oldValue</code></dt>

<dd>
<p>Returns the old value of the key being changed.</p>
</dd>

<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-newValue">newValue</code></dt>

<dd>
<p>Returns the new value of the key being changed.</p>
</dd>

<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-url">url</code></dt>

<dd>
<p>Returns the <span>URL</span> of the document whose key changed.</p>
</dd>

<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-storageArea">storageArea</code></dt>

<dd>
<p>Returns the <code>Storage</code> object that was affected.</p>
</dd>

</dl>

<div w-nodev>

<p>The <dfn><code data-x="dom-StorageEvent-key">key</code></dfn> attribute must return the value
it was initialized to. It represents the key being changed.</p>

Expand All @@ -98471,6 +98576,7 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
affected.</p>



<h3>Disk space</h3>

<p>User agents should limit the total amount of space allowed for storage areas, because hostile
Expand Down Expand Up @@ -98610,6 +98716,8 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
<p>To this end, user agents should ensure that when deleting data, it is promptly deleted from the
underlying storage.</p>

</div>


<!--ADD-TOPIC:Security-->
<h3 id="security-storage">Security</h3>
Expand All @@ -98635,6 +98743,8 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
path.</p>


<div w-nodev>

<h4>Implementation risks</h4>

<p>The two primary risks when implementing these persistent storage features are letting hostile
Expand All @@ -98655,6 +98765,8 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
important for user security.</p>
<!--REMOVE-TOPIC:Security-->

</div>



<h2 split-filename="syntax" id="syntax"><dfn>The HTML syntax</dfn></h2>
Expand Down

0 comments on commit 5323e66

Please sign in to comment.