[html5] r1490 - /

whatwg at whatwg.org whatwg at whatwg.org
Sun Apr 27 01:56:28 PDT 2008


Author: ianh
Date: 2008-04-27 01:56:27 -0700 (Sun, 27 Apr 2008)
New Revision: 1490

Modified:
   index
   source
Log:
[giow] (2) showModalDialog(): first draft. Also, some 'the the' editorial corrections.

Modified: index
===================================================================
--- index	2008-04-25 20:58:06 UTC (rev 1489)
+++ index	2008-04-27 08:56:27 UTC (rev 1490)
@@ -25,7 +25,7 @@
 
    <h1 id=html-5>HTML 5</h1>
 
-   <h2 class="no-num no-toc" id=working>Working Draft — 25 April 2008</h2>
+   <h2 class="no-num no-toc" id=working>Working Draft — 27 April 2008</h2>
 
    <p>You can take part in this work. <a
     href="http://www.whatwg.org/mailing-list">Join the working group's
@@ -1073,7 +1073,14 @@
 
      <li><a href="#user-prompts"><span class=secno>4.4 </span>User
       prompts</a>
+      <ul class=toc>
+       <li><a href="#simple0"><span class=secno>4.4.1 </span>Simple
+        dialogs</a>
 
+       <li><a href="#dialogs"><span class=secno>4.4.2 </span>Dialogs
+        implemented using separate documents</a>
+      </ul>
+
      <li><a href="#browser"><span class=secno>4.5 </span>Browser state</a>
       <ul class=toc>
        <li><a href="#custom-handlers"><span class=secno>4.5.1 </span>Custom
@@ -4240,7 +4247,7 @@
      <var title="">new children</var> be the children of the document,
      preserving their order. Otherwise, the attribute is being set on an
      <code>Element</code> node; let <var title="">new children</var> be the
-     children of the the document's root element, preserving their order.</p>
+     children of the document's root element, preserving their order.</p>
 
    <li>
     <p>If the attribute is being set on a <code>Document</code> node, let
@@ -7891,7 +7898,7 @@
    title=attr-meta-http-equiv><code>http-equiv</code></dfn> attribute is an
    <a href="#enumerated">enumerated attribute</a>. The following table lists
    the keywords defined for this attribute. The states given in the first
-   cell of the the rows with keywords give the states to which those keywords
+   cell of the rows with keywords give the states to which those keywords
    map.<!-- Some of the keywords are non-conforming, as
   noted in the last column.-->
 
@@ -13253,7 +13260,7 @@
 
     <p>The text must be given in the <code title=attr-img-alt><a
      href="#alt">alt</a></code> attribute, and must convey the same message
-     as the the image specified in the <code title=attr-img-src><a
+     as the image specified in the <code title=attr-img-src><a
      href="#src">src</a></code> attribute.</p>
 
     <div class=example>
@@ -19211,9 +19218,9 @@
   <p>The <dfn id=shape title=attr-area-shape><code>shape</code></dfn>
    attribute is an <a href="#enumerated">enumerated attribute</a>. The
    following table lists the keywords defined for this attribute. The states
-   given in the first cell of the the rows with keywords give the states to
-   which those keywords map. Some of the keywords are non-conforming, as
-   noted in the last column.
+   given in the first cell of the rows with keywords give the states to which
+   those keywords map. Some of the keywords are non-conforming, as noted in
+   the last column.
 
   <table>
    <thead>
@@ -26801,6 +26808,9 @@
   DOMString <a href="#prompt" title=dom-prompt>prompt</a>(in DOMString message);
   DOMString <a href="#prompt" title=dom-prompt>prompt</a>(in DOMString message, in DOMString default);
   void <a href="#print" title=dom-print>print</a>();
+  any <a href="#showmodaldialog" title=dom-showModalDialog>showModalDialog</a>(in DOMString url);
+  any <a href="#showmodaldialog" title=dom-showModalDialog>showModalDialog</a>(in DOMString url, in any arguments);
+  any <a href="#showmodaldialog" title=dom-showModalDialog>showModalDialog</a>(in DOMString url, in any arguments, in DOMString features);
 
   // other browsing contexts
   readonly attribute <a href="#window">Window</a> <a href="#frames" title=dom-frames>frames</a>;
@@ -27909,6 +27919,8 @@
 
   <h3 id=user-prompts><span class=secno>4.4 </span>User prompts</h3>
 
+  <h4 id=simple0><span class=secno>4.4.1 </span>Simple dialogs</h4>
+
   <p>The <dfn id=alert title=dom-alert><code>alert(<var
    title="">message</var>)</code></dfn> method, when invoked, must show the
    given <var title="">message</var> to the user. The user agent may make the
@@ -27920,15 +27932,15 @@
    title="">message</var>)</code></dfn> method, when invoked, must show the
    given <var title="">message</var> to the user, and ask the user to respond
    with a positive or negative response. The user agent must then <a
-   href="#pause">pause</a> as the the method waits for the user's response.
-   If the user responds positively, the method must return true, and if the
-   user responds negatively, the method must return false.
+   href="#pause">pause</a> as the method waits for the user's response. If
+   the user responds positively, the method must return true, and if the user
+   responds negatively, the method must return false.
 
   <p>The <dfn id=prompt title=dom-prompt><code>prompt(<var
    title="">message</var>, <var title="">default</var>)</code></dfn> method,
    when invoked, must show the given <var title="">message</var> to the user,
    and ask the user to either respond with a string value or abort. The user
-   agent must then <a href="#pause">pause</a> as the the method waits for the
+   agent must then <a href="#pause">pause</a> as the method waits for the
    user's response. The second argument is optional. If the second argument
    (<var title="">default</var>) is present, then the response must be
    defaulted to the value given by <var title="">default</var>. If the user
@@ -27944,6 +27956,137 @@
    <em>always</em> offering the user with the opportunity to convert the
    document to whatever media the user might want.)
 
+  <h4 id=dialogs><span class=secno>4.4.2 </span>Dialogs implemented using
+   separate documents</h4>
+
+  <p>The <dfn id=showmodaldialog
+   title=dom-showModalDialog><code>showModalDialog(<var title="">url</var>,
+   <var title="">arguments</var>, <var title="">features</var>)</code></dfn>
+   method, when invoked, must cause the user agent to run the following
+   steps:
+
+  <ol>
+   <li>
+    <p>If the user agent is configured such that this invocation of <code
+     title=dom-showModalDialog><a
+     href="#showmodaldialog">showModalDialog()</a></code> is somehow
+     disabled, then the method returns the empty string; abort these steps.</p>
+
+    <p class=note>User agents are expected to disable this method in certain
+     cases to avoid user annoyance. For instance, a user agent could require
+     that a site be white-listed before enabling this method, or the user
+     agent could be configured to only allow one modal dialog at a time.</p>
+
+   <li>
+    <p>Let <var title="">the list of background browsing contexts</var> be a
+     list of all the browsing contexts that:</p>
+
+    <ul>
+     <li>are part of the same <a href="#unit-of">unit of related browsing
+      contexts</a> as the browsing context of the <code><a
+      href="#window">Window</a></code> object on which the <code
+      title=dom-showModalDialog><a
+      href="#showmodaldialog">showModalDialog()</a></code> method was called,
+      and that
+
+     <li>have an <a href="#active">active document</a> whose origin is the
+      same as the origin of the script that called the <code
+      title=dom-showModalDialog><a
+      href="#showmodaldialog">showModalDialog()</a></code> method at the time
+      the method was called,</li>
+     <!-- XXX document.domain
+     breaks this. when fixing it, er on the side of including more
+     browsing contexts rather than less. -->
+    </ul>
+
+    <p>...as well as any browsing contexts that are nested inside any of the
+     browsing contexts matching those conditions.</p>
+
+   <li>
+    <p>Disable the user interface for all the browsing contexts in <var
+     title="">the list of background browsing contexts</var>. This should
+     prevent the user from navigating those browsing contexts, causing events
+     to to be sent to those browsing context, or editing any content in those
+     browsing contexts. However, it does not prevent those browsing contexts
+     from receiving events from sources other than the user, from running
+     scripts, from running animations, and so forth.</p>
+
+   <li>
+    <p>Create a new <a href="#auxiliary0">auxiliary browsing context</a>,
+     with the <a href="#opener">opener browsing context</a> being the
+     browsing context of the <code><a href="#window">Window</a></code> object
+     on which the <code title=dom-showModalDialog><a
+     href="#showmodaldialog">showModalDialog()</a></code> method was called.
+     The new auxiliary browsing context has no name.</p>
+
+    <p class=note>This browsing context implements the <code><a
+     href="#modalwindow">ModalWindow</a></code> interface.</p>
+
+   <li>
+    <p>Let the <a href="#dialog0">dialog arguments</a> of the new browsing
+     context be set to the value of <var title="">arguments</var>.</p>
+
+   <li>
+    <p>Let the <a href="#dialog1">dialog arguments' origin</a> be the origin
+     of the script that called the <code title=dom-showModalDialog><a
+     href="#showmodaldialog">showModalDialog()</a></code> method.</p>
+
+   <li>
+    <p><a href="#navigate">Navigate</a> the new browsing context to <var
+     title="">url</var>, with <a href="#replacement">replacement enabled</a>.</p>
+
+   <li>
+    <p>Wait for the browsing context to be closed. (The user agent must allow
+     the user to indicate that the browsing context is to be closed.)</p>
+
+   <li>
+    <p>Reenable the user interface for all the browsing contexts in <var
+     title="">the list of background browsing contexts</var>.</p>
+
+   <li>
+    <p>Return the <a href="#auxiliary0">auxiliary browsing context</a>'s <a
+     href="#return">return value</a>.</p>
+  </ol>
+
+  <p>Browsing contexts created by the above algorithm must implement the
+   <code><a href="#modalwindow">ModalWindow</a></code> interface:
+
+  <pre class=idl>[XXX] interface <dfn id=modalwindow>ModalWindow</dfn> {
+  readonly attribute any <a href="#dialogarguments" title=dom-modalWindow-dialogArguments>dialogArguments</a>;
+           attribute DOMString <a href="#returnvalue" title=dom-modalWindow-returnValue>returnValue</a>;
+};</pre>
+
+  <p>Such browsing contexts have associated <dfn id=dialog0>dialog
+   arguments</dfn>, which are stored along with the <dfn id=dialog1>dialog
+   arguments' origin</dfn>. These values are set by the <code
+   title=dom-showModalDialog><a
+   href="#showmodaldialog">showModalDialog()</a></code> method in the
+   algorithm above, when the browsing context is created, based on the
+   arguments provided to the method.
+
+  <p>The <dfn id=dialogarguments
+   title=dom-modalWindow-dialogArguments><code>dialogArguments</code></dfn>
+   DOM attribute, on getting, must check whether its browsing context's <a
+   href="#active">active document</a>'s <a href="#origin0">origin</a> is the
+   same as the <a href="#dialog1">dialog arguments' origin</a>. If it is,
+   then the browsing context's <a href="#dialog0">dialog arguments</a> must
+   be returned unchanged. Otherwise, if the <a href="#dialog0">dialog
+   arguments</a> are an object, then the empty string must be returned, and
+   if the <a href="#dialog0">dialog arguments</a> are not an object, then the
+   stringification of the <a href="#dialog0">dialog arguments</a> must be
+   returned.
+
+  <p>These browsing contexts also have an associated <dfn id=return>return
+   value</dfn>. The <a href="#return">return value</a> of a browsing context
+   must be initialised to the empty string when the browsing context is
+   created.
+
+  <p>The <dfn id=returnvalue
+   title=dom-modalWindow-returnValue><code>returnValue</code></dfn> DOM
+   attribute, on getting, must return the <a href="#return">return value</a>
+   of its browsing context, and on setting, must set the <a
+   href="#return">return value</a> to the given new value.
+
   <h3 id=browser><span class=secno>4.5 </span>Browser state</h3>
 
   <p>The <dfn id=navigator title=dom-navigator><code>navigator</code></dfn>
@@ -30800,8 +30943,8 @@
    ifragment? XXX -->
 
    <li>
-    <p>If <i>fragid</i> is the empty string, then the the indicated part of
-     the document is the top of the document.
+    <p>If <i>fragid</i> is the empty string, then the indicated part of the
+     document is the top of the document.
 
    <li>
     <p>If there is an element in the DOM that has an ID exactly equal to
@@ -30914,7 +31057,7 @@
 
    <li>
     <p>If <var title="">official type</var> ends in "+xml", or if it is
-     either "text/xml" or "application/xml", then the the sniffed type of the
+     either "text/xml" or "application/xml", then the sniffed type of the
      resource is <var title="">official type</var>; return that and abort
      these steps.
    </li>
@@ -32849,7 +32992,7 @@
    href="#navigate">navigate</a> a <a href="#browsing0">browsing context</a>
    to the URI of the hyperlink.
 
-  <p>The URI of the hyperlink is URI given by resolving the the <code
+  <p>The URI of the hyperlink is URI given by resolving the <code
    title=attr-hyperlink-href><a href="#href6">href</a></code> attribute of
    that hyperlink relative to the hyperlink's element. In the case of
    server-side image maps, the URI of the hyperlink must further have its
@@ -37221,8 +37364,8 @@
 
    <dd>
     <p><a href="#processField">Process the field</a> using the steps
-     described below, using the the whole line as the field name, and the
-     empty string as the field value.</p>
+     described below, using the whole line as the field name, and the empty
+     string as the field value.</p>
   </dl>
 
   <p>Once the end of the file is reached, the user agent must <a

Modified: source
===================================================================
--- source	2008-04-25 20:58:06 UTC (rev 1489)
+++ source	2008-04-27 08:56:27 UTC (rev 1490)
@@ -2639,7 +2639,7 @@
     let <var title="">new children</var> be the children of the
     document, preserving their order. Otherwise, the attribute is
     being set on an <code>Element</code> node; let <var title="">new
-    children</var> be the children of the the document's root element,
+    children</var> be the children of the document's root element,
     preserving their order.</p>
 
    </li>
@@ -6303,7 +6303,7 @@
   title="attr-meta-http-equiv"><code>http-equiv</code></dfn> attribute
   is an <span>enumerated attribute</span>. The following table lists
   the keywords defined for this attribute. The states given in the
-  first cell of the the rows with keywords give the states to which
+  first cell of the rows with keywords give the states to which
   those keywords map.<!-- Some of the keywords are non-conforming, as
   noted in the last column.--></p>
 
@@ -11232,7 +11232,7 @@
 
     <p>The text must be given in the <code
     title="attr-img-alt">alt</code> attribute, and must convey the
-    same message as the the image specified in the <code
+    same message as the image specified in the <code
     title="attr-img-src">src</code> attribute.</p>
 
     <div class="example">
@@ -16925,7 +16925,7 @@
   <p>The <dfn title="attr-area-shape"><code>shape</code></dfn>
   attribute is an <span>enumerated attribute</span>. The following
   table lists the keywords defined for this attribute. The states
-  given in the first cell of the the rows with keywords give the
+  given in the first cell of the rows with keywords give the
   states to which those keywords map. Some of the keywords are
   non-conforming, as noted in the last column.</p>
 
@@ -24508,6 +24508,9 @@
   DOMString <span title="dom-prompt">prompt</span>(in DOMString message);
   DOMString <span title="dom-prompt">prompt</span>(in DOMString message, in DOMString default);
   void <span title="dom-print">print</span>();
+  any <span title="dom-showModalDialog">showModalDialog</span>(in DOMString url);
+  any <span title="dom-showModalDialog">showModalDialog</span>(in DOMString url, in any arguments);
+  any <span title="dom-showModalDialog">showModalDialog</span>(in DOMString url, in any arguments, in DOMString features);
 
   // other browsing contexts
   readonly attribute <span>Window</span> <span title="dom-frames">frames</span>;
@@ -25609,6 +25612,8 @@
 
   <h3>User prompts</h3>
 
+  <h4>Simple dialogs</h4>
+
   <p>The <dfn title="dom-alert"><code>alert(<var
   title="">message</var>)</code></dfn> method, when invoked, must show
   the given <var title="">message</var> to the user. The user agent
@@ -25620,7 +25625,7 @@
   title="">message</var>)</code></dfn> method, when invoked, must show
   the given <var title="">message</var> to the user, and ask the user
   to respond with a positive or negative response. The user agent must
-  then <span>pause</span> as the the method waits for the user's
+  then <span>pause</span> as the method waits for the user's
   response. If the user responds positively, the method must return
   true, and if the user responds negatively, the method must return
   false.</p>
@@ -25630,7 +25635,7 @@
   method, when invoked, must show the given <var
   title="">message</var> to the user, and ask the user to either
   respond with a string value or abort. The user agent must then
-  <span>pause</span> as the the method waits for the user's
+  <span>pause</span> as the method waits for the user's
   response. The second argument is optional. If the second argument
   (<var title="">default</var>) is present, then the response must be
   defaulted to the value given by <var title="">default</var>. If the
@@ -25648,6 +25653,169 @@
 
 
 
+  <h4>Dialogs implemented using separate documents</h4>
+
+  <p>The <dfn title="dom-showModalDialog"><code>showModalDialog(<var
+  title="">url</var>, <var title="">arguments</var>, <var
+  title="">features</var>)</code></dfn> method, when invoked, must
+  cause the user agent to run the following steps:</p>
+
+  <ol>
+
+   <li>
+
+    <p>If the user agent is configured such that this invocation of
+    <code title="dom-showModalDialog">showModalDialog()</code> is
+    somehow disabled, then the method returns the empty string; abort
+    these steps.</p>
+
+    <p class="note">User agents are expected to disable this method in
+    certain cases to avoid user annoyance. For instance, a user agent
+    could require that a site be white-listed before enabling this
+    method, or the user agent could be configured to only allow one
+    modal dialog at a time.</p>
+
+   </li>
+
+   <li>
+
+    <p>Let <var title="">the list of background browsing
+    contexts</var> be a list of all the browsing contexts that:</p>
+
+    <ul>
+
+     <li>are part of the same <span>unit of related browsing
+     contexts</span> as the browsing context of the
+     <code>Window</code> object on which the <code
+     title="dom-showModalDialog">showModalDialog()</code> method was
+     called, and that</p>
+
+     <li>have an <span>active document</span> whose origin is the same
+     as the origin of the script that called the <code
+     title="dom-showModalDialog">showModalDialog()</code> method at
+     the time the method was called,</li> <!-- XXX document.domain
+     breaks this. when fixing it, er on the side of including more
+     browsing contexts rather than less. -->
+
+    </ul>
+
+    <p>...as well as any browsing contexts that are nested inside any
+    of the browsing contexts matching those conditions.</p>
+
+   </li>
+
+   <li>
+
+    <p>Disable the user interface for all the browsing contexts in
+    <var title="">the list of background browsing contexts</var>. This
+    should prevent the user from navigating those browsing contexts,
+    causing events to to be sent to those browsing context, or editing
+    any content in those browsing contexts. However, it does not
+    prevent those browsing contexts from receiving events from sources
+    other than the user, from running scripts, from running
+    animations, and so forth.</p>
+
+   </li>
+
+   <li>
+
+    <p>Create a new <span>auxiliary browsing context</span>, with the
+    <span>opener browsing context</span> being the browsing context of
+    the <code>Window</code> object on which the <code
+    title="dom-showModalDialog">showModalDialog()</code> method was
+    called. The new auxiliary browsing context has no name.</p>
+
+    <p class="note">This browsing context implements the
+    <code>ModalWindow</code> interface.</p>
+
+   </li>
+
+   <li>
+
+    <p>Let the <span>dialog arguments</span> of the new browsing
+    context be set to the value of <var title="">arguments</var>.</p>
+
+   </li>
+
+   <li>
+
+    <p>Let the <span>dialog arguments' origin</span> be the origin of
+    the script that called the <code
+    title="dom-showModalDialog">showModalDialog()</code> method.</p>
+
+   </li>
+
+   <li>
+
+    <p><span>Navigate</span> the new browsing context to <var
+    title="">url</var>, with <span>replacement enabled</span>.</p>
+
+   </li>
+
+   <li>
+
+    <p>Wait for the browsing context to be closed. (The user agent
+    must allow the user to indicate that the browsing context is to be
+    closed.)</p>
+
+   </li>
+
+   <li>
+
+    <p>Reenable the user interface for all the browsing contexts in
+    <var title="">the list of background browsing contexts</var>.</p>
+
+   </li>
+
+   <li>
+
+    <p>Return the <span>auxiliary browsing context</span>'s
+    <span>return value</span>.</p>
+
+   </li>
+
+  </ol>
+
+  <p>Browsing contexts created by the above algorithm must implement
+  the <code>ModalWindow</code> interface:</p>
+
+  <pre class="idl">[XXX] interface <dfn>ModalWindow</dfn> {
+  readonly attribute any <span title="dom-modalWindow-dialogArguments">dialogArguments</span>;
+           attribute DOMString <span title="dom-modalWindow-returnValue">returnValue</span>;
+};</pre>
+
+  <p>Such browsing contexts have associated <dfn>dialog
+  arguments</dfn>, which are stored along with the <dfn>dialog
+  arguments' origin</dfn>. These values are set by the <code
+  title="dom-showModalDialog">showModalDialog()</code> method in the
+  algorithm above, when the browsing context is created, based on the
+  arguments provided to the method.</p>
+
+  <p>The <dfn
+  title="dom-modalWindow-dialogArguments"><code>dialogArguments</code></dfn>
+  DOM attribute, on getting, must check whether its browsing context's
+  <span>active document</span>'s <span>origin</span> is the same as
+  the <span>dialog arguments' origin</span>. If it is, then the
+  browsing context's <span>dialog arguments</span> must be returned
+  unchanged. Otherwise, if the <span>dialog arguments</span> are an
+  object, then the empty string must be returned, and if the
+  <span>dialog arguments</span> are not an object, then the
+  stringification of the <span>dialog arguments</span> must be
+  returned.
+
+  <p>These browsing contexts also have an associated <dfn>return
+  value</dfn>. The <span>return value</span> of a browsing context
+  must be initialised to the empty string when the browsing context is
+  created.</p>
+
+  <p>The <dfn
+  title="dom-modalWindow-returnValue"><code>returnValue</code></dfn>
+  DOM attribute, on getting, must return the <span>return value</span>
+  of its browsing context, and on setting, must set the <span>return
+  value</span> to the given new value.</p>
+
+
+
   <h3>Browser state</h3>
 
   <p>The <dfn title="dom-navigator"><code>navigator</code></dfn>
@@ -28572,7 +28740,7 @@
    URI. <a href="#refsRFC3987">[RFC3987]</a></p></li> <!-- IRI,
    ifragment? XXX -->
 
-   <li><p>If <i>fragid</i> is the empty string, then the the indicated
+   <li><p>If <i>fragid</i> is the empty string, then the indicated
    part of the document is the top of the document.</p></li>
 
    <li><p>If there is an element in the DOM that has an ID exactly
@@ -28671,7 +28839,7 @@
    labelled "text/html". --></li>
 
    <li><p>If <var title="">official type</var> ends in "+xml", or if
-   it is either "text/xml" or "application/xml", then the the sniffed
+   it is either "text/xml" or "application/xml", then the sniffed
    type of the resource is <var title="">official type</var>; return
    that and abort these steps.</p></li> <!-- we don't want
    image/svg+xml going through the next step -->
@@ -30588,7 +30756,7 @@
   <span>navigate</span> a <span>browsing context</span> to the URI of
   the hyperlink.
 
-  <p>The URI of the hyperlink is URI given by resolving the the <code
+  <p>The URI of the hyperlink is URI given by resolving the <code
   title="attr-hyperlink-href">href</code> attribute of that hyperlink
   relative to the hyperlink's element. In the case of server-side
   image maps, the URI of the hyperlink must further have its
@@ -34692,7 +34860,7 @@
    <dd>
 
     <p><a href="#processField">Process the field</a> using the steps
-    described below, using the the whole line as the field name, and
+    described below, using the whole line as the field name, and
     the empty string as the field value.</p>
 
    </dd>




More information about the Commit-Watchers mailing list