- From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 29 May 2008 12:08:27 +0000
- To: public-html-commits@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 UTC