Skip to content

Commit

Permalink
Add scroll restoration preference to history traversal
Browse files Browse the repository at this point in the history 
- Define history.scrollRestoration and update IDLs
- Add a new persisted user state restoration algorithm

Fixes https://www.w3.org/Bugs/Public/show_bug.cgi?id=28553.
Closes #278.
  • Loading branch information
@majido @zcorpan
majido authored and zcorpan committed Nov 16, 2015
1 parent c84f4ca commit dd6a34e
Showing 1 changed file with 91 additions and 25 deletions.
116 changes: 91 additions & 25 deletions source
View file
Expand Up @@ -80268,8 +80268,8 @@ x === this; // true</pre>
context</span>'s session history consists of a flat list of <span data-x="session history
entry">session history entries</span>. Each <dfn>session history entry</dfn> consists, at a
minimum, of a <span>URL</span>, and each entry may in addition have a <span>state object</span>, a
title, a <code>Document</code> object, form data, a scroll position, and other information
associated with it.</p>
title, a <code>Document</code> object, form data, a <span>scroll restoration mode</span>, a scroll
position, and other information associated with it.</p>

<p class="note">Each entry, when first created, has a <code>Document</code>. However, when a
<code>Document</code> is not <span data-x="fully active">active</span>, it's possible for it to be
Expand Down Expand Up @@ -80353,6 +80353,9 @@ x === this; // true</pre>
This prevents values from being displayed incorrectly after a history traversal when the user had
originally entered the values with an explicit, non-default directionality.</p>

<p>An entry's <dfn>scroll restoration mode</dfn> indicates whether the user agent should
restore the persisted scroll position (if any) when traversing to it.</p>

<p>Entries that consist of <span data-x="state object">state objects</span> share the same
<code>Document</code> as the entry for the page that was active when they were added.</p>

Expand Down Expand Up @@ -80387,8 +80390,11 @@ x === this; // true</pre>
<!--TOPIC:DOM APIs-->
<h4>The <code>History</code> interface</h4>

<pre class="idl">interface <dfn>History</dfn> {
<pre class="idl">enum <dfn>ScrollRestoration</dfn> { "<span data-x="dom-ScrollRestoration-auto">auto</span>", "<span data-x="dom-ScrollRestoration-manual">manual</span>" };

interface <dfn>History</dfn> {
readonly attribute unsigned long <span data-x="dom-history-length">length</span>;
attribute <span data-x="dom-ScrollRestoration">ScrollRestoration</span> <span data-x="dom-history-scroll-restoration">scrollRestoration</span>;
readonly attribute any <span data-x="dom-history-state">state</span>;
void <span data-x="dom-history-go">go</span>(optional long delta = 0);
void <span data-x="dom-history-back">back</span>();
Expand All @@ -80407,6 +80413,14 @@ x === this; // true</pre>

</dd>

<dt><var>window</var> . <code data-x="dom-history">history</code> . <code subdfn data-x="dom-history-scroll-restoration">scrollRestoration</code></dt>

<dd>

<p>The <span>scroll restoration mode</span> of the current entry in the <span>session history</span>.</p>

</dd>

<dt><var>window</var> . <code data-x="dom-history">history</code> . <code subdfn data-x="dom-history-state">state</code></dt>

<dd>
Expand Down Expand Up @@ -80510,6 +80524,22 @@ x === this; // true</pre>

<p>The actual entries are not accessible from script.</p>

<p>The <dfn><code data-x="dom-history-scroll-restoration">scrollRestoration</code></dfn> attribute
of the History interface, on getting, must return the <span>scroll restoration mode</span> of the
current entry in the <span>session history</span>. On setting, the <span>scroll restoration mode
</span> of the current entry in the <span>session history</span> must be set to the new
value. <span>Scroll restoration mode</span> may be one of the following:</p>
<dl>
<dt>"<dfn><code subdfn data-x="dom-ScrollRestoration-auto">auto</code></dfn>"</dt>
<dd>The user agent is responsible for restoring the scroll position upon navigation.</dd>
<dt>"<dfn><code subdfn data-x="dom-ScrollRestoration-manual">manual</code></dfn>"</dt>
<dd>The page is responsible for restoring the scroll position and the user agent does not attempt
to do so automatically</dd>
</dl>

<p>If unspecified, the <span>scroll restoration mode</span> of a new entry must be set to
"<code data-x="dom-ScrollRestoration-auto">auto</code>".</p>

<p>The <dfn><code data-x="dom-history-state">state</code></dfn> attribute of the
<code>History</code> interface must return the last value it was set to by the user agent.
Initially, its value must be null.</p>
Expand Down Expand Up @@ -80713,8 +80743,9 @@ x === this; // true</pre>

<li><p>Add a <span>state object</span> entry to the session history, after the <span>current
entry</span>, with <var>cloned data</var> as the <span>state object</span>, the given
<var>title</var> as the title, and <var>new URL</var> as the <span>URL</span>
of the entry.</p></li>
<var>title</var> as the title, <var>new URL</var> as the <span>URL</span>
of the entry, and the <span>scroll restoration mode</span> of the current entry in the
<span>session history</span> as the scroll restoration mode.</p></li>

<li><p>Update the <span>current entry</span> to be this newly added entry.</p></li>

Expand Down Expand Up @@ -80863,6 +80894,23 @@ State: &lt;OUTPUT NAME=I>1&lt;/OUTPUT> &lt;INPUT VALUE="Increment" TYPE=BUTTON O

</div>

<div class="example">
<p>Most applications want to use the same <span>scroll restoration mode</span> value for all of
their history entries. To achieve this they should set the <code
data-x="dom-history-scroll-restoration">scrollRestoration</code> attribute as soon as possible
(e.g., in the first <code>script</code> element in the document's <code>head</code> element) to
ensure that any entry added to the history session gets the desired scroll restoration mode.</p>

<pre>&lt;head&gt;
&lt;script&gt;
if ('scrollRestoration' in history)
history.scrollRestoration = 'manual';
&lt;/script&gt;
&lt;/head&gt;
</pre>
</div>




<h4>The <code>Location</code> interface</h4>
Expand Down Expand Up @@ -82302,7 +82350,8 @@ State: &lt;OUTPUT NAME=I>1&lt;/OUTPUT> &lt;INPUT VALUE="Increment" TYPE=BUTTON O
</li>

<li><p>Append a new entry at the end of the <code>History</code> object representing the new
resource and its <code>Document</code> object and related state.</p></li>
resource and its <code>Document</code> object, related state, and the default <span>scroll
restoration mode</span> of "<code data-x="dom-ScrollRestoration-auto">auto</code>".</p></li>

<li><p><span>Traverse the history</span> to the new entry. If the navigation was initiated
with <span>replacement enabled</span>, then the traversal must itself be initiated with
Expand Down Expand Up @@ -82642,9 +82691,9 @@ State: &lt;OUTPUT NAME=I>1&lt;/OUTPUT> &lt;INPUT VALUE="Increment" TYPE=BUTTON O
<span>top-level browsing context</span>'s <span>document family</span>.</p></li>

<li><p>Append a new entry at the end of the <code>History</code> object representing the new
resource and its <code>Document</code> object and related state. Its <span>URL</span> must be set
to the address to which the user agent was <span data-x="navigate">navigating</span>. The title
must be left unset.</p></li>
resource and its <code>Document</code> object, related state, and current history <span>scroll
restoration preference</span>. Its <span>URL</span> must be set to the address to which the user
agent was <span data-x="navigate">navigating</span>. The title must be left unset.</p></li>

<li><p><span>Traverse the history</span> to the new entry, with the <i>non-blocking events</i> flag
set. This will <span>scroll to the fragment
Expand Down Expand Up @@ -82904,27 +82953,15 @@ State: &lt;OUTPUT NAME=I>1&lt;/OUTPUT> &lt;INPUT VALUE="Increment" TYPE=BUTTON O
entry</var>. Otherwise, let <var>hash changed</var> be false.</p></li>

<li><p>If the traversal was initiated with <dfn>replacement enabled</dfn>, remove the entry
immediately before the <var>specified entry</var> in the session history.</p>
immediately before the <var>specified entry</var> in the session history.</p></li>

<li><p>If the <var>specified entry</var> is not <span>an entry with persisted user
state</span>, but its URL has a fragment identifier, <span>scroll to the fragment
identifier</span>.</p></li>

<li>

<p>If the entry is <span>an entry with persisted user state</span>, the user agent may update
aspects of the document and its rendering, for instance the scroll position or values of form
fields, that it had previously recorded.</p>

<!-- see similar paragraphs in the textarea and input sections -->
<p class="note">This can even include updating the <code data-x="attr-dir">dir</code> attribute
of <code>textarea</code> elements or <code>input</code> elements whose <code
data-x="attr-input-type">type</code> attribute is in either the <span
data-x="attr-input-type-text">Text</span> state or the <span
data-x="attr-input-type-search">Search</span> state, if the persisted state includes the
directionality of user input in such controls.</p>

</li>
<li><p>If the entry is <span>an entry with persisted user state</span>, the user agent may
<span>restore persisted user state</span> and update
aspects of the document and its rendering.</p></li>

<li><p>If the entry is a <span>state object</span> entry, let <var>state</var> be a
<span>structured clone</span> of that state object. Otherwise, let <var>state</var> be
Expand Down Expand Up @@ -82972,6 +83009,35 @@ State: &lt;OUTPUT NAME=I>1&lt;/OUTPUT> &lt;INPUT VALUE="Increment" TYPE=BUTTON O

</div>

<h5>Persisted user state restoration</h5>
<div w-nodev>

<p>When the user agent is to <dfn>restore persisted user state</dfn> from a history entry, it must
run the following steps immediately:</p>

<ol>

<li><p>If the entry has a <span>scroll restoration mode</span>, let <var>scrollRestoration</var>
be that. Otherwise let <var>scrollRestoration</var> be "<code
data-x="dom-ScrollRestoration-auto">auto</code>"</p></li>

<li><p>If <var>scrollRestoration</var> is "<code
data-x="dom-ScrollRestoration-manual">manual</code>" the user agent should not restore the scroll
position for the document otherwise it may.</p></li>

<li><p>Optionally, update other aspects of the document and its rendering, for instance values of
form fields, that the user agent had previously recorded.</p></li>

</ol>
</div>

<!-- see similar paragraphs in the textarea and input sections -->
<p class="note">This can even include updating the <code data-x="attr-dir">dir</code> attribute
of <code>textarea</code> elements or <code>input</code> elements whose <code
data-x="attr-input-type">type</code> attribute is in either the <span
data-x="attr-input-type-text">Text</span> state or the <span
data-x="attr-input-type-search">Search</span> state, if the persisted state includes the
directionality of user input in such controls.</p>

<h5>The <code>PopStateEvent</code> interface</h5>

Expand Down

0 comments on commit dd6a34e

Please sign in to comment.