Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[r] (0) showNotification() -- first draft.
git-svn-id: http://svn.whatwg.org/webapps@1714 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
Hixie committed May 29, 2008
1 parent 028a9d9 commit ae6d365
Show file tree
Hide file tree
Showing 2 changed files with 415 additions and 14 deletions.
216 changes: 205 additions & 11 deletions index
Expand Up @@ -25,7 +25,7 @@

<h1 id=html-5>HTML 5</h1>

<h2 class="no-num no-toc" id=draft>Draft Recommendation &mdash; 28 May
<h2 class="no-num no-toc" id=draft>Draft Recommendation &mdash; 29 May
2008</h2>

<p>You can take part in this work. <a
Expand Down Expand Up @@ -1108,6 +1108,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>
Expand Down Expand Up @@ -2788,7 +2791,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
Expand All @@ -2797,7 +2800,7 @@
resource indicated by <span>the document's address</span> over HTTP, as
per RFC 2109 section 4.3.4. <a href="#refsRFC2109">[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
Expand Down Expand Up @@ -14524,7 +14527,15 @@ the time Marco had stuck his tongue out...&lt;/p></pre>
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
Expand Down Expand Up @@ -14556,7 +14567,7 @@ the time Marco had stuck his tongue out...&lt;/p></pre>
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
Expand All @@ -14567,7 +14578,7 @@ the time Marco had stuck his tongue out...&lt;/p></pre>
<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
Expand Down Expand Up @@ -23289,7 +23300,7 @@ XXXDVT (also check for '- -' bits in the part above) -->
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>
Expand Down Expand Up @@ -25699,7 +25710,7 @@ https://www.google.com/base/settings
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>

Expand Down Expand Up @@ -28634,7 +28645,7 @@ never reset. This is nice and consistent.)
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);
Expand All @@ -28643,6 +28654,8 @@ never reset. This is nice and consistent.)
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>;
Expand Down Expand Up @@ -29052,7 +29065,7 @@ never reset. This is nice and consistent.)
<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.
Expand Down Expand Up @@ -29335,7 +29348,7 @@ never reset. This is nice and consistent.)

<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>

Expand Down Expand Up @@ -30195,6 +30208,187 @@ JSURI: http://ietfreport.isoc.org/all-ids/draft-hoehrmann-javascript-scheme-00.t
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>
Expand Down

0 comments on commit ae6d365

Please sign in to comment.