Skip to content

Commit

Permalink
Modernize and refactor modal dialogs
Browse files Browse the repository at this point in the history 
This contains a small bug fix, in that confirm() and prompt() said
"return" in some cases instead of "return false" or "return null" as
appropriate.

Other notable changes, all editorial, are:

* Factoring out repeated "cannot show modals" steps, which will likely
  expand over time (see e.g. #6297).
* Separating out and explaining the no-argument overload of alert().
* Passing the document through to the "printing steps", instead of just
  having them talk about "this Window object".
  • Loading branch information
@domenic
domenic committed Jan 26, 2021
1 parent 0f26153 commit cc680c3
Showing 1 changed file with 71 additions and 69 deletions.
140 changes: 71 additions & 69 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78763,7 +78763,7 @@ interface <dfn interface>Window</dfn> : <span>EventTarget</span> {
readonly attribute boolean <span data-x="dom-originAgentCluster">originAgentCluster</span>;

// user prompts
undefined <span data-x="dom-alert">alert</span>();
undefined <span data-x="dom-alert-noargs">alert</span>();
undefined <span data-x="dom-alert">alert</span>(DOMString message);
boolean <span data-x="dom-confirm">confirm</span>(optional DOMString message = "");
DOMString? <span data-x="dom-prompt">prompt</span>(optional DOMString message = "", optional DOMString default = "");
Expand Down Expand Up @@ -93431,31 +93431,12 @@ function sendData(data) {

<div w-nodev>

<p>To <dfn>optionally truncate a simple dialog string</dfn> <var>s</var>, return either
<var>s</var> itself or some string derived from <var>s</var> that is shorter. User agents should
not provide UI for displaying the elided portion of <var>s</var>, as this makes it too easy for
abusers to create dialogs of the form "Important security alert! Click 'Show More' for full
details!".</p>

<p class="note">For example, a user agent might want to only display the first 100 characters of a
message. Or, a user agent might replace the middle of the string with "&hellip;". These types of
modifications can be useful in limiting the abuse potential of unnaturally large,
trustworthy-looking system dialogs.</p>

<p>The <dfn method for="Window"><code data-x="dom-alert">alert(<var>message</var>)</code></dfn>
method, when invoked, must run the following steps:</p>
<p>The <dfn method for="Window"><code data-x="dom-alert-noargs">alert()</code></dfn> and <dfn
method for="Window"><code data-x="dom-alert">alert(<var>message</var>)</code></dfn> method steps
are:</p>

<ol>
<li><p>If the <span>event loop</span>'s <span>termination nesting level</span> is nonzero,
optionally return.</p></li>

<li><p>If the <span>active sandboxing flag set</span> of this <code>Window</code> object's <span
data-x="concept-document-window">associated <code>Document</code></span> has the <span>sandboxed
modals flag</span> set, then return.</p></li>

<li><p>Optionally, return. (For example, the user agent might give the user the option
to ignore all alerts, and would thus abort at this step whenever the method was
invoked.)</p></li>
<li><p>If we <span>cannot show modals</span> for <span>this</span>, then return.</p></li>

<li><p>If the method was invoked with no arguments, then let <var>message</var> be the
empty string; otherwise, let <var>message</var> be the method's first
Expand All @@ -93473,21 +93454,17 @@ function sendData(data) {
message.</p></li>
</ol>

<p class="note">This method is defined using two overloads, instead of using an
<!--non-normative-->optional argument, for historical reasons. The practical impact of this is
that <code data-x="" class="js">alert(undefined)</code> is treated as <code data-x=""
class="js">alert("undefined")</code>, but <code data-x="" class="js">alert()</code> is treated as
<code data-x="" class="js">alert("")</code>.</p>

<p>The <dfn method for="Window"><code
data-x="dom-confirm">confirm(<var>message</var>)</code></dfn> method, when invoked, must run the
following steps:</p>
data-x="dom-confirm">confirm(<var>message</var>)</code></dfn> method steps are:</p>

<ol>
<li><p>If the <span>event loop</span>'s <span>termination nesting level</span> is nonzero,
optionally return false.</p></li>

<li><p>If the <span>active sandboxing flag set</span> of this <code>Window</code> object's <span
data-x="concept-document-window">associated <code>Document</code></span> has the <span>sandboxed
modals flag</span> set, then return.</p></li>

<li><p>Optionally, return false. (For example, the user agent might give
the user the option to ignore all prompts, and would thus abort at this step whenever the method
was invoked.)</p></li>
<li><p>If we <span>cannot show modals</span> for <span>this</span>, then return false.</p></li>

<li><p>Set <var>message</var> to the result of <span data-x="normalize newlines">normalizing
newlines</span> given <var>message</var>.</p></li>
Expand All @@ -93505,26 +93482,17 @@ function sendData(data) {
</ol>

<p>The <dfn method for="Window"><code data-x="dom-prompt">prompt(<var>message</var>,
<var>default</var>)</code></dfn> method, when invoked, must run the following steps:</p>
<var>default</var>)</code></dfn> method steps are:</p>

<ol>
<li><p>If the <span>event loop</span>'s <span>termination nesting level</span> is nonzero,
optionally return null.</p></li>
<li><p>If we <span>cannot show modals</span> for <span>this</span>, then return null.</p></li>

<li><p>If the <span>active sandboxing flag set</span> of this <code>Window</code> object's <span
data-x="concept-document-window">associated <code>Document</code></span> has the <span>sandboxed
modals flag</span> set, then return.</p></li>

<li><p>Optionally, return null. (For example, the user agent might give the
user the option to ignore all prompts, and would thus abort at this step whenever the method was
invoked.)</p></li>
<li><p>Set <var>message</var> to the result of <span data-x="normalize newlines">normalizing
newlines</span> given <var>message</var>.</p></li>

<li><p>Set <var>message</var> to the result of <span data-x="optionally truncate a simple dialog
string">optionally truncating</span> <var>message</var>.</p></li>

<li><p>Set <var>message</var> to the result of <span data-x="normalize newlines">normalizing
newlines</span> given <var>message</var>.</p></li>

<li><p>Set <var>default</var> to the result of <span data-x="optionally truncate a simple dialog
string">optionally truncating</span> <var>default</var>.</p></li>

Expand All @@ -93538,6 +93506,36 @@ function sendData(data) {
with.</p></li>
</ol>

<p>To <dfn>optionally truncate a simple dialog string</dfn> <var>s</var>, return either
<var>s</var> itself or some string derived from <var>s</var> that is shorter. User agents should
not provide UI for displaying the elided portion of <var>s</var>, as this makes it too easy for
abusers to create dialogs of the form "Important security alert! Click 'Show More' for full
details!".</p>

<p class="note">For example, a user agent might want to only display the first 100 characters of a
message. Or, a user agent might replace the middle of the string with "&hellip;". These types of
modifications can be useful in limiting the abuse potential of unnaturally large,
trustworthy-looking system dialogs.</p>

<p>We <dfn>cannot show modals</dfn> for a <code>Window</code> <var>window</var> when the
following algorithm returns true:</p>

<ol>
<li><p>If the <span>active sandboxing flag set</span> of <var>window</var>'s <span
data-x="concept-document-window">associated <code>Document</code></span> has the <span>sandboxed
modals flag</span> set, then return true.</p></li>

<li>If <var>window</var>'s <span>relevant agent</span>'s <span
data-x="concept-agent-event-loop">event loop</span>'s <span>termination nesting level</span> is
nonzero, then optionally return true.</li>

<li><p>Optionally, return true. (For example, the user agent might give the
user the option to ignore all modal dialogs, and would thus abort at this step whenever the method was
invoked.)</p></li>

<li><p>Return false.</p></li>
</ol>

</div>


Expand All @@ -93554,17 +93552,24 @@ function sendData(data) {

<div w-nodev>

<p>When the <dfn method for="Window"><code data-x="dom-print">print()</code></dfn> method is
invoked, if the <code>Document</code> is <span>ready for post-load tasks</span>, then the user
agent must run the <span>printing steps</span>. Otherwise, the user agent must only set the
<dfn>print when loaded</dfn> flag on the <code>Document</code>.</p>
<p>The <dfn method for="Window"><code data-x="dom-print">print()</code></dfn> method steps
are:</p>

<ol>
<li><p>Let <var>document</var> be <span>this</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</p></li>

<li><p>If <var>document</var> is <span>ready for post-load tasks</span>, then run the
<span>printing steps</span> for <var>document</var>.</p></li>

<li><p>Otherwise, set <var>document</var>'s <dfn>print when loaded</dfn> flag.</p></li>
</ol>

<p>User agents should also run the <span>printing steps</span> whenever the user asks for the
opportunity to <span>obtain a physical form</span> (e.g. printed copy), or the representation of a
physical form (e.g. PDF copy), of a document.</p>

<p>The <dfn>printing steps</dfn> are as follows:</p>
<p>The <dfn>printing steps</dfn> for a <code>Document</code> <var>document</var> are:</p>

<ol>
<li>
Expand All @@ -93579,8 +93584,7 @@ function sendData(data) {
</li>

<li>
<p>If the <span>active sandboxing flag set</span> of this <code>Window</code> object's <span
data-x="concept-document-window">associated <code>Document</code></span> has the <span>sandboxed
<p>If the <span>active sandboxing flag set</span> of <var>document</var> has the <span>sandboxed
modals flag</span> set, then return.</p>

<p class="note">If the printing dialog is blocked by a <code>Document</code>'s sandbox,
Expand All @@ -93590,28 +93594,26 @@ function sendData(data) {

<li>
<p>The user agent must <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-beforeprint">beforeprint</code> at the <span>relevant global object</span> of the
<code>Document</code> that is being printed, as well as any <span data-x="child browsing
data-x="event-beforeprint">beforeprint</code> at the <span>relevant global object</span> of
<var>document</var>, as well as any <span data-x="child browsing
context">child browsing contexts</span> in it.</p>

<p class="example">The <code data-x="event-beforeprint">beforeprint</code> event can be used to
annotate the printed copy, for instance adding the time at which the document was printed.</p>
</li>

<li>
<p>The user agent should offer the user the opportunity to <span>obtain a physical form</span>
(or the representation of a physical form) of the document. The user agent may wait for the user
to either accept or decline before returning; if so, the user agent must <span>pause</span>
while the method is waiting. Even if the user agent doesn't wait at this point, the user agent
must use the state of the relevant documents as they are at this point in the algorithm if and
when it eventually creates the alternate form.</p>
</li>
<li><p>The user agent should offer the user the opportunity to <span>obtain a physical
form</span> (or the representation of a physical form) of <var>document</var>. The user agent may
wait for the user to either accept or decline before returning; if so, the user agent must
<span>pause</span> while the method is waiting. Even if the user agent doesn't wait at this
point, the user agent must use the state of the relevant documents as they are at this point in
the algorithm if and when it eventually creates the alternate form.</p></li>

<li>
<p>The user agent must <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-afterprint">afterprint</code> at the <span>relevant global object</span> of the
<code>Document</code> that is being printed, as well as any <span data-x="child browsing
context">child browsing contexts</span> in it.</p>
data-x="event-afterprint">afterprint</code> at the <span>relevant global object</span> of
<var>document</var>, as well as any <span data-x="child browsing context">child browsing
contexts</span> in it.</p>

<p class="example">The <code data-x="event-afterprint">afterprint</code> event can be used to
revert annotations added in the earlier event, as well as showing post-printing UI. For
Expand Down

0 comments on commit cc680c3

Please sign in to comment.