Skip to content
Permalink
Browse files

[] (0) Remove the showNotification() API due to lack of interest from…

… implementors.

git-svn-id: http://svn.whatwg.org/webapps@2597 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information...
Hixie committed Dec 28, 2008
1 parent 8001668 commit 242b7dd4f11dfb7dc58b7196076dd3a63291490f
Showing with 135 additions and 107 deletions.
  1. +102 −80 index
  2. +33 −27 source
182 index
@@ -674,8 +674,7 @@
<ol>
<li><a href=#simple-dialogs><span class=secno>5.5.1 </span>Simple dialogs</a></li>
<li><a href=#printing><span class=secno>5.5.2 </span>Printing</a></li>
<li><a href=#dialogs-implemented-using-separate-documents><span class=secno>5.5.3 </span>Dialogs implemented using separate documents</a></li>
<li><a href=#notifications><span class=secno>5.5.4 </span>Notifications</a></ol></li>
<li><a href=#dialogs-implemented-using-separate-documents><span class=secno>5.5.3 </span>Dialogs implemented using separate documents</a></ol></li>
<li><a href=#system-state-and-capabilities><span class=secno>5.6 </span>System state and capabilities</a>
<ol>
<li><a href=#client-identification><span class=secno>5.6.1 </span>Client identification</a></li>

</dd>


<dt>The <dfn id=sandboxed-annoyances-browsing-context-flag>sandboxed annoyances browsing context flag</dfn></dt>
<!-- XXX-NOTIFY
<dt>The <dfn>sandboxed annoyances browsing context flag</dfn></dt>

<dd>

<p>This flag prevents content from <a href=#sandboxNotifications>showing notifications</a> outside of
the <a href=#nested-browsing-context>nested browsing context</a>.</p>
<p>This flag prevents content from <a
href="#sandboxNotifications">showing notifications</a> outside of
the <span>nested browsing context</span>.</p>

</dd>
-->


<dt>The <dfn id=sandboxed-origin-browsing-context-flag>sandboxed origin browsing context flag</dfn>, unless
void <a href=#dom-print title=dom-print>print</a>();
any <a href=#dom-showmodaldialog title=dom-showModalDialog>showModalDialog</a>(in DOMString url);
any <a href=#dom-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=#dom-shownotification title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description);
void <a href=#dom-shownotification title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description, in VoidCallback onclick);
any <span title="dom-showModalDialog">showModalDialog</span>(in DOMString url, in any arguments, in DOMString features);--><!-- XXX-NOTIFY
void <span title="dom-showNotification">showNotification</span>(in DOMString title, in DOMString subtitle, in DOMString description);
void <span title="dom-showNotification">showNotification</span>(in DOMString title, in DOMString subtitle, in DOMString description, in VoidCallback onclick);-->

// <a href=#crossDocumentMessages>cross-document messaging</a>
void <a href=#dom-window-postmessage-2 title=dom-window-postMessage-2>postMessage</a>(in any message, in DOMString targetOrigin);
close the browsing context.</p>


<h4 id=notifications><span class=secno>5.5.4 </span>Notifications</h4>
<!-- XXX-NOTIFY
<h4>Notifications</h4>

<!-- v2 feature requests:
<!- - 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
- full HTML notifications

-->
- ->

<p>Notifications are short, transient messages that bring the user's
attention to new information, or remind the user of scheduled
rendering area unless the user explicitly indicates that the site
can be trusted.</p>

<p>To this end, each <a href=#origin-0>origin</a> can be flagged as being a
<dfn id=trusted-notification-source>trusted notification source</dfn>. By default origins should
<p>To this end, each <span>origin</span> can be flagged as being a
<dfn>trusted notification source</dfn>. By default origins should
not be flagged as such, but user agents may allow users to whitelist
origins or groups of origins as being <a href=#trusted-notification-source title="trusted
notification source">trusted notification sources</a>. Only
origins or groups of origins as being <span title="trusted
notification source">trusted notification sources</span>. Only
origins flagged as trusted in this way are allowed to show
notification UI outside of their tab.</p>

<p class=example>For example, a user agent could allow a user to
<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>

<p>The <dfn id=dom-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
<p>The <dfn 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>

<p id=sandboxNotifications>If the method was invoked from a <a href=#concept-script title=concept-script>script</a>
whose <a href="#script's-browsing-context" title="script's browsing context">browsing
context</a> has the <a href=#sandboxed-annoyances-browsing-context-flag>sandboxed annoyances browsing context
flag</a> set, then the notification must be shown within that
<a href=#browsing-context>browsing context</a>. The notification is said to be a
<dfn id=sandboxed-notification>sandboxed notification</dfn>.</p>

<p>Otherwise, if the <a href=#origin-0>origin</a> of the <a href="#script's-browsing-context" title="script's browsing context">browsing context</a> of the
<a href=#concept-script title=concept-script>script</a> that invoked the method is <em>not</em> flagged as being a
<a href=#trusted-notification-source>trusted notification source</a>, then the notification
should be rendered within the <a href=#top-level-browsing-context>top-level browsing
context</a> of the <a href="#script's-browsing-context">script's browsing context</a>. The
notification is said to be a <dfn id=normal-notification>normal notification</dfn>. User
agents should provide a way to set the origin's <a href=#trusted-notification-source>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>

<p>Otherwise, the <a href=#origin-0>origin</a> is flagged as a <a href=#trusted-notification-source>trusted
notification source</a>, and the notification should be shown
<p id="sandboxNotifications">If the method was invoked from a <span
title="concept-script">script</span> whose <span title="script's
browsing context">browsing context</span> has the <span>sandboxed
annoyances browsing context flag</span> set, then the notification
must be shown within that <span>browsing context</span>. The
notification is said to be a <dfn>sandboxed notification</dfn>.</p>

<p>Otherwise, if the <span>origin</span> of the <span
title="script's browsing context">browsing context</span> of the
<span title="concept-script">script</span> that invoked the method
is <em>not</em> flagged as being a <span>trusted notification
source</span>, then the notification should be rendered within the
<span>top-level browsing context</span> of the <span>script's
browsing context</span>. The notification is said to be a
<dfn>normal notification</dfn>. User agents should provide a way to
set the origin's <span>trusted notification source</span> flag from
the notification, so that the user can benefit from notifications
even when the user agent is not the active application.</p>

<p>Otherwise, the <span>origin</span> is flagged as a <span>trusted
notification source</span>, and the notification should be shown
using the platform conventions for system-wide notifications. The
notification is said to be a <dfn id=trusted-notification>trusted notification</dfn>. User
agents may provide a way to unset the origin's <a href=#trusted-notification-source>trusted
notification source</a> flag from within the notification, so as
notification is said to be a <dfn>trusted notification</dfn>. User
agents may provide a way to unset the origin's <span>trusted
notification source</span> flag from within the notification, so as
to allow users to easily disable notifications from sites that abuse
the privilege.</p>

<div class=example>
<div class="example">

<p>For example, if a site contains a gadget of a mail application
in a sandboxed <code><a href=#the-iframe-element>iframe</a></code> and that frame triggers a
in a sandboxed <code>iframe</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>


</div>

<div class=example>
<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

</div>

<p>When a <a href=#normal-notification>normal notification</a> (but not a
<a href=#sandboxed-notification>sandboxed notification</a>) is shown, the user agent may
bring the user's attention to the <a href=#top-level-browsing-context>top-level browsing
context</a> of the <a href="#script's-browsing-context" title="script's browsing
context">browsing context</a> of the <a href=#concept-script title=concept-script>script</a> that invoked the
method, if that would be useful; but user agents should not use
system-wide notification mechanisms to do so.</p>
<p>When a <span>normal notification</span> (but not a
<span>sandboxed notification</span>) is shown, the user agent may
bring the user's attention to the <span>top-level browsing
context</span> of the <span title="script's browsing
context">browsing context</span> of the <span
title="concept-script">script</span> that invoked the method, if
that would be useful; but user agents should not use system-wide
notification mechanisms to do so.</p>

<p>When a <span>trusted notification</span> is shown, the user agent
should bring the user's attention to the notification and the <span
title="script's browsing context">browsing context</span> of the
<span title="concept-script">script</span> that invoked the method,
as per the platform conventions for attracting the user's attention
to applications.</p>

<p>When a <a href=#trusted-notification>trusted notification</a> is shown, the user agent
should bring the user's attention to the notification and the <a href="#script's-browsing-context" title="script's browsing context">browsing context</a> of the
<a href=#concept-script title=concept-script>script</a> that invoked the method, as per the platform conventions for
attracting the user's attention to applications.</p>

<div class=example>
<div class="example">

<p>In the case of <a href=#normal-notification title="normal notification">normal
notifications</a>, typically the only attention-grabbing device
<p>In the case of <span title="normal notification">normal
notifications</span>, 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=#trusted-notification>trusted notification</a>,
<p>In addition, in the case of a <span>trusted notification</span>,
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>

<p>Notifications should include the following content:</p>

<ul><li>The <var title="">title</var>, <var title="">subtitle</var>,
<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>

<li>The <a href=#meta-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-document>active document</a> of the <a href="#script's-browsing-context" title="script's browsing
context">browsing context</a> of the <a href=#concept-script title=concept-script>script</a> that invoked the
method.</li>

<li>An icon chosen from the <a href=#external-resource-link title="external resource
link">external resource links</a> of type <code title=rel-icon><a href=#rel-icon>icon</a></code>, if any are available.</li>

</ul><p>If a new notification from one <a href=#browsing-context>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=#browsing-context>browsing context</a> or another <a href=#browsing-context title="browsing context">browsing context</a> with the same
<a href=#origin-0>origin</a>, the user agent should not display the new
<li>The <span title="meta-application-name">application
name</span>, if available, or else the <span
title="dom-document-title">document title</span>, of the
<span>active document</span> of the <span title="script's browsing
context">browsing context</span> of the <span
title="concept-script">script</span> that invoked the method.</li>

<li>An icon chosen from the <span title="external resource
link">external resource links</span> of type <code
title="rel-icon">icon</code>, if any are available.</li>

</ul>

<p>If a new notification from one <span>browsing context</span> 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 <span>browsing context</span> or another <span
title="browsing context">browsing context</span> with the same
<span>origin</span>, 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.</p>

<div class=example>
<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
<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=#browsing-context>browsing
context</a> that is hidden, it should be shown for its complete
lifetime once the user brings that <a href=#browsing-context>browsing context</a>
to see it, so if a notification is spawned for a <span>browsing
context</span> that is hidden, it should be shown for its complete
lifetime once the user brings that <span>browsing context</span>
into view.</p>

<p>User agents should support multiple notifications at once.</p>

<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="#script's-browsing-context" title="script's browsing context">browsing context</a> of the
<a href=#concept-script title=concept-script>script</a> of the function given by
callback argument was present and is not null, then the <span
title="script's browsing context">browsing context</span> of the
<span title="concept-script">script</span> 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.</p>

-->


<h3 id=system-state-and-capabilities><span class=secno>5.6 </span>System state and capabilities</h3>

0 comments on commit 242b7dd

Please sign in to comment.
You can’t perform that action at this time.