W3C home > Mailing lists > Public > public-html-commits@w3.org > May 2008

html5/spec Overview.html,1.900,1.901

From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
Date: Thu, 29 May 2008 12:08:27 +0000
To: public-html-commits@w3.org
Message-Id: <E1K1gvj-0003X0-6l@lionel-hutz.w3.org>

Update of /sources/public/html5/spec
In directory hutz:/tmp/cvs-serv13543

Modified Files:
	Overview.html 
Log Message:
showNotification() -- first draft. (whatwg r1714)

Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.900
retrieving revision 1.901
diff -u -d -r1.900 -r1.901
--- Overview.html	28 May 2008 12:05:18 -0000	1.900
+++ Overview.html	29 May 2008 12:08:24 -0000	1.901
@@ -58,11 +58,11 @@
    <h2 class="no-num no-toc" id=a-vocabulary>A vocabulary and associated APIs
     for HTML and XHTML</h2>
 
-   <h2 class="no-num no-toc" id=w3c-working>W3C Working Draft 28 May 2008</h2>
+   <h2 class="no-num no-toc" id=w3c-working>W3C Working Draft 29 May 2008</h2>
 
    <dl><!-- ZZZ
     <dt>This Version:</dt>
-    <dd><a href="http://www.w3.org/TR/2008/WD-html5-20080528/">http://www.w3.org/TR/2008/WD-html5-20080528/</a></dd>
+    <dd><a href="http://www.w3.org/TR/2008/WD-html5-20080529/">http://www.w3.org/TR/2008/WD-html5-20080529/</a></dd>
 -->
 
     <dt>Latest Published Version:
@@ -192,7 +192,7 @@
   <p>The W3C <a href="http://www.w3.org/html/wg/">HTML Working Group</a> is
    the W3C working group responsible for this specification's progress along
    the W3C Recommendation track.<!--ZZZ This
-  specification is the 28 May 2008 First Public Working Draft.--></p>
+  specification is the 29 May 2008 First Public Working Draft.--></p>
   <!-- relationship to other work (required) -->
 
   <p>This specification is also being produced by the <a
@@ -1192,6 +1192,9 @@
 
        <li><a href="#dialogs"><span class=secno>4.5.2 </span>Dialogs
         implemented using separate documents</a>
+
+       <li><a href="#notifications"><span class=secno>4.5.3
+        </span>Notifications</a>
       </ul>
 
      <li><a href="#browser"><span class=secno>4.6 </span>Browser state</a>
@@ -2872,7 +2875,7 @@
   <p>The <dfn id=cookie0 title=dom-document-cookie><code>cookie</code></dfn>
    attribute represents the cookies of the resource.
 
-  <p id=sandboxCookies>On getting, if the <a href="#sandboxed1">sandboxed
+  <p id=sandboxCookies>On getting, if the <a href="#sandboxed2">sandboxed
    origin browsing context flag</a> is set on the <a
    href="#browsing1">browsing context</a> of the document, the user agent
    must raise a <a href="#security9">security exception</a>. Otherwise, it
@@ -2881,7 +2884,7 @@
    resource indicated by <span>the document's address</span> over HTTP, as
    per RFC 2109 section 4.3.4. <a href="#references">[RFC2109]</a>
 
-  <p>On setting, if the <a href="#sandboxed1">sandboxed origin browsing
+  <p>On setting, if the <a href="#sandboxed2">sandboxed origin browsing
    context flag</a> is set on the <a href="#browsing1">browsing context</a>
    of the document, the user agent must raise a <a href="#security9">security
    exception</a>. Otherwise, the user agent must act as it would when
@@ -14608,7 +14611,15 @@
      through <a href="#sandboxPluginNavigate">navigation</a> of a <a
      href="#nested0">nested browsing context</a>.</p>
 
-   <dt>The <dfn id=sandboxed1>sandboxed origin browsing context flag</dfn>,
+   <dt>The <dfn id=sandboxed1>sandboxed annoyances browsing context
+    flag</dfn>
+
+   <dd>
+    <p>This flag prevents content from <a
+     href="#sandboxNotifications">showing notifications</a> outside of the <a
+     href="#nested0">nested browsing context</a>.</p>
+
+   <dt>The <dfn id=sandboxed2>sandboxed origin browsing context flag</dfn>,
     unless the <code title=attr-iframe-sandbox><a
     href="#sandbox">sandbox</a></code> attribute's value, when <a
     href="#split" title="split a string on spaces">split on spaces</a>, is
@@ -14640,7 +14651,7 @@
       site, using the database APIs to store data, etc.</p>
     </div>
 
-   <dt>The <dfn id=sandboxed2>sandboxed forms browsing context flag</dfn>,
+   <dt>The <dfn id=sandboxed3>sandboxed forms browsing context flag</dfn>,
     unless the <code title=attr-iframe-sandbox><a
     href="#sandbox">sandbox</a></code> attribute's value, when <a
     href="#split" title="split a string on spaces">split on spaces</a>, is
@@ -14651,7 +14662,7 @@
    <dd>
     <p>This flag <a href="#sandboxSubmitBlocked">blocks form submission</a>.</p>
 
-   <dt>The <dfn id=sandboxed3>sandboxed scripts browsing context flag</dfn>,
+   <dt>The <dfn id=sandboxed4>sandboxed scripts browsing context flag</dfn>,
     unless the <code title=attr-iframe-sandbox><a
     href="#sandbox">sandbox</a></code> attribute's value, when <a
     href="#split" title="split a string on spaces">split on spaces</a>, is
@@ -23373,7 +23384,7 @@
    for now
 
   <p class=big-issue id=sandboxSubmitBlocked>If a form is in a browsing
-   context whose <a href="#sandboxed2">sandboxed forms browsing context
+   context whose <a href="#sandboxed3">sandboxed forms browsing context
    flag</a> is set, it must not be submitted.
 
   <h3 id=scripting0><span class=secno>3.15 </span>Scripting</h3>
@@ -25783,7 +25794,7 @@
     href="#initially-closed">initially-closed</a></code> class applies to the
     row, then it must be initially closed. Otherwise, if neither class
     applies to the row, or if the row is not openable, then the initial state
-    of the row is entirely up to the UA.</dd>
+    of the row should be based on platform conventions.</dd>
    <!-- XXXPA
    <dt>To establish whether a row is deletable</dt>
 
@@ -28718,7 +28729,7 @@
   readonly attribute <a href="#storage0">Storage</a> <a href="#localstorage" title=dom-localStorage>localStorage</a>;
   <a href="#database0">Database</a> <a href="#opendatabase" title=dom-opendatabase>openDatabase</a>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize);
 
-  // modal user prompts
+  // user prompts
   void <a href="#alert" title=dom-alert>alert</a>(in DOMString message);
   boolean <a href="#confirm" title=dom-confirm>confirm</a>(in DOMString message);
   DOMString <a href="#prompt" title=dom-prompt>prompt</a>(in DOMString message);
@@ -28727,6 +28738,8 @@
   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 <span title="dom-showModalDialog">showModalDialog</span>(in DOMString url, in any arguments, in DOMString features);-->
+  void <a href="#shownotification" title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description);
+  void <a href="#shownotification" title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description, in VoidCallback onclick);
 
   // other browsing contexts
   readonly attribute <a href="#window">Window</a> <a href="#frames" title=dom-frames>frames</a>;
@@ -29136,7 +29149,7 @@
     <dl class=switch>
      <dt id=sandboxOrigin>If a <code>Document</code> is in a <a
       href="#browsing1">browsing context</a> whose <a
-      href="#sandboxed1">sandboxed origin browsing context flag</a> is set
+      href="#sandboxed2">sandboxed origin browsing context flag</a> is set
 
      <dd>The <a href="#origin0">origin</a> is a globally unique identifier
       assigned when the <code>Document</code> is created.
@@ -29419,7 +29432,7 @@
 
    <li id=sandboxScriptBlocked>The <a href="#script2">script execution
     context</a>'s associated <a href="#browsing1">browsing context</a> has
-    the <a href="#sandboxed3">sandboxed scripts browsing context flag</a>
+    the <a href="#sandboxed4">sandboxed scripts browsing context flag</a>
     set.
   </ul>
 
@@ -30279,6 +30292,187 @@
    of its browsing context, and on setting, must set the <a
    href="#return">return value</a> to the given new value.
 
+  <h4 id=notifications><span class=secno>4.5.3 </span>Notifications</h4>
+  <!-- v2 feature requests:
+
+   - ability to snooze a notification so it comes again later
+      - shouldn't be on all messages, only those for which it makes
+        sense
+      - possibly just provide a new argument that takes an array of
+        (label, callback) tuples so that sites can implement this
+        themselves
+
+  -->
+
+  <p>Notifications are short, transient messages that bring the user's
+   attention to new information, or remind the user of scheduled events.
+
+  <p>Since notifications can be annoying if abused, this specification
+   defines a mechanism that scopes notifications to a site's existing
+   rendering area unless the user explicitly indicates that the site can be
+   trusted.
+
+  <p>To this end, each <a href="#origin0">origin</a> can be flagged as being
+   a <dfn id=trusted>trusted notification source</dfn>. By default no origin
+   should be flagged as such, but user agents may allow users to whitelist
+   origins or groups of origins as being <a href="#trusted" title="trusted
+   notification source">trusted notification sources</a>. Only origins
+   flagged as trusted in this way are allowed to show notification UI outside
+   of their tab.
+
+  <p class=example>For example, a user agent could allow a user to mark all
+   subdomains and ports of example.org as trusted notification sources. Then,
+   mail.example.org and calendar.example.org would both be able to show
+   notifications, without the user having to flag them individually.
+
+  <p>The <dfn id=shownotification
+   title=dom-showNotification><code>showNotification(<var
+   title="">title</var>, <var title="">subtitle</var>, <var
+   title="">description</var>, <var title="">onclick</var>)</code></dfn>
+   method, when invoked, must cause the user agent to show a notification.
+
+  <p id=sandboxNotifications>If the method was invoked from a script whose <a
+   href="#script2">script execution context</a>'s associated <a
+   href="#browsing1">browsing context</a> has the <a
+   href="#sandboxed1">sandboxed annoyances browsing context flag</a> set,
+   then the notification must be shown within that <a
+   href="#browsing1">browsing context</a>. The notification is said to be a
+   <dfn id=sandboxed5>sandboxed notification</dfn>.
+
+  <p>Otherwise, if the <a href="#origin0">origin</a> of the <a
+   href="#browsing1">browsing context</a> associated with the <a
+   href="#script2">script execution context</a> of the script that invoked
+   the method is <em>not</em> flagged as being a <a href="#trusted">trusted
+   notification source</a>, then the notification should be rendered within
+   the <a href="#top-level">top-level browsing context</a> of the <a
+   href="#browsing1">browsing context</a> associated with the <a
+   href="#script2">script execution context</a> of the script that invoked
+   the method. The notification is said to be a <dfn id=normal>normal
+   notification</dfn>. User agents should provide a way to set the origin's
+   <a href="#trusted">trusted notification source</a> flag from the
+   notification, so that the user can benefit from notifications even when
+   the user agent is not the active application.
+
+  <p>Otherwise, the <a href="#origin0">origin</a> is flagged as a <a
+   href="#trusted">trusted notification source</a>, and the notification
+   should be shown using the platform conventions for system-wide
+   notifications. The notification is said to be a <dfn id=trusted0>trusted
+   notification</dfn>. User agents may provide a way to unset the origin's <a
+   href="#trusted">trusted notification source</a> flag from within the
+   notification, so as to allow users to easily disable notifications from
+   sites that abuse the privilege.
+
+  <div class=example>
+   <p>For example, if a site contains a gadget of a mail application in a
+    sandboxed <code><a href="#iframe">iframe</a></code> and that frame
+    triggers a notification upon the receipt of a new e-mail message, that
+    notification would be displayed on top of the gadget only.</p>
+
+   <p>However, if the user then goes to the main site of that mail
+    application, the notification would be displayed over the entire
+    rendering area of the tab for the site.</p>
+
+   <p>The notification, in this case, would have a button on it to let the
+    user indicate that he trusts the site. If the user clicked this button,
+    the next notification would use the system-wide notification system,
+    appearing even if the tab for the mail application was burried deep
+    inside a minimised window.</p>
+  </div>
+
+  <div class=example>
+   <p>The style of notifications varies from platform to platform. On some,
+    it is typically displayed as a "toast" window that slides in from the
+    bottom right corner. In others, notifications are shown as
+    semi-transparent white-on-grey overlays centered over the screen. Other
+    schemes could include simulated ticker tapes, and speech-synthesis
+    playback.</p>
+  </div>
+
+  <p>When a <a href="#normal">normal notification</a> (but not a <a
+   href="#sandboxed5">sandboxed notification</a>) is shown, the user agent
+   may bring the user's attention to the <a href="#top-level">top-level
+   browsing context</a> of the <a href="#browsing1">browsing context</a>
+   associated with the <a href="#script2">script execution context</a> of the
+   script that invoked the method, if that would be useful; but user agents
+   should not use system-wide notification mechanisms to do so.
+
+  <p>When a <a href="#trusted0">trusted notification</a> is shown, the user
+   agent should bring the user's attention to the notification and the <a
+   href="#browsing1">browsing context</a> associated with the <a
+   href="#script2">script execution context</a> of the script that invoked
+   the method, as per the platform conventions for attracting the user's
+   attention to applications.
+
+  <div class=example>
+   <p>In the case of <a href="#normal" title="normal notification">normal
+    notifications</a>, typically the only attention-grabbing device that
+    would be employed would be something like flashing the tab's caption, or
+    making it bold, or some such.</p>
+
+   <p>In addition, in the case of a <a href="#trusted0">trusted
+    notification</a>, the entire window could flash, or the browser's
+    application icon could bounce or flash briefly, or a short sound effect
+    could be played.</p>
+  </div>
+
+  <p>Notifications should include the following content:
+
+  <ul>
+   <li>The <var title="">title</var>, <var title="">subtitle</var>, and <var
+    title="">description</var> strings passed to the method. They may be
+    truncated or abbreviated if necessary.
+
+   <li>The <a href="#application-name"
+    title=meta-application-name>application name</a>, if available, or else
+    the <a href="#document.title" title=dom-document-title>document
+    title</a>, of the <a href="#active">active document</a> of the <a
+    href="#browsing1">browsing context</a> associated with the <a
+    href="#script2">script execution context</a> of the script that invoked
+    the method.
+
+   <li>An icon chosen from the <a href="#links1" title="external resource
+    link">external resource links</a> of type <code title=rel-icon><a
+    href="#icon3">icon</a></code>, if any are available.
+  </ul>
+
+  <p>If a new notification from one <a href="#browsing1">browsing context</a>
+   has <var title="">title</var>, <var title="">subtitle</var>, and <var
+   title="">description</var> strings that are identical to the <var
+   title="">title</var>, <var title="">subtitle</var>, and <var
+   title="">description</var> strings of an already-active notification from
+   the same <a href="#browsing1">browsing context</a> or another <a
+   href="#browsing1" title="browsing context">browsing context</a> with the
+   same <a href="#origin0">origin</a>, the user agent should not display the
+   new notification, but should instead add an indicator to the
+   already-active notification that another identical notification would
+   otherwise have been shown.
+
+  <div class=example>
+   <p>For instance, if a user has his mail application open in three windows,
+    and thus the same "New Mail" notification is fired three times each time
+    a mail is received, instead of displaying three identical notifications
+    each time, the user agent could just shown one, with the title "New Mail
+    x3".</p>
+  </div>
+
+  <p>Notifications should have a lifetime based on the platform conventions
+   for notifications. However, the lifetime of a notification should not
+   begin until the user has had the opportunity to see it, so if a
+   notification is spawned for a <a href="#browsing1">browsing context</a>
+   that is hidden, it should be shown for its complete lifetime once the user
+   brings that <a href="#browsing1">browsing context</a> into view.
+
+  <p>User agents should support multiple notifications at once.
+
+  <p>User agents should support user interaction with notifications, if and
+   as appropriate given the platform conventions. If a user activates a
+   notification, and the <var title="">onclick</var> callback argument was
+   present and is not null, then the <a href="#browsing1">browsing
+   context</a> associated with the <a href="#script2">script execution
+   context</a> of the function given by <var title="">onclick</var> should be
+   brought to the user's attention, and the <var title="">onclick</var>
+   callback should then be invoked.
+
   <h3 id=browser><span class=secno>4.6 </span>Browser state</h3>
 
   <p>The <dfn id=navigator title=dom-navigator><code>navigator</code></dfn>
Received on Thursday, 29 May 2008 12:09:06 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 9 October 2008 20:32:56 GMT