From 13a81a327c0876a025f3709d044a2011464bcc1c Mon Sep 17 00:00:00 2001 From: Peter Beverloo Date: Fri, 5 Aug 2016 16:28:56 +0100 Subject: [PATCH] Encourage user agents to only expose supported properties Fixes #81. --- notifications.bs | 8 + notifications.html | 503 +++++++++++++++++++-------------------------- 2 files changed, 218 insertions(+), 293 deletions(-) diff --git a/notifications.bs b/notifications.bs index 1ae59fa..d286733 100644 --- a/notifications.bs +++ b/notifications.bs @@ -291,6 +291,14 @@ removed from the list of notifications.

User agents should display persistent notifications in a platform's "notification center" (if available). +

User agents should only expose properties on the {{Notification}} object when +the associated feature impacts the user agent's presentation or behavior of +notifications, for instance when the feature is +supported by the platform's "notification center" or alternative presentation. + +

Only exposing the supported properties enables authors to employ +feature detection to decide on alternative ways of delivering content when a +particular feature cannot be supported.

Permission model

diff --git a/notifications.html b/notifications.html index bbe2b4a..1ad79fb 100644 --- a/notifications.html +++ b/notifications.html @@ -8,159 +8,70 @@ - - - - +

Notifications API

-

Living Standard — Last Updated

+

Living Standard — Last Updated

@@ -386,6 +297,12 @@

<

A persistent notification could have the close() method invoked of one of its Notification objects.

User agents should display persistent notifications in a platform’s "notification center" (if available).

+

User agents should only expose properties on the Notification object when +the associated feature impacts the user agent’s presentation or behavior of notifications, for instance when the feature is +supported by the platform’s "notification center" (or alternative presentation).

+

Only exposing the supported properties enables authors to employ +feature detection to decide on alternative ways of delivering content when a +particular feature cannot be supported.

2.2. Permission model

Notifications can only be displayed if the user (or user agent on behalf of the user) has granted permission. @@ -584,76 +501,76 @@

Perform vibration using notification’s vibration pattern, if any.

3. API

-
[Constructor(DOMString title, optional NotificationOptions options),
- Exposed=(Window,Worker)]
-interface Notification : EventTarget {
-  static readonly attribute NotificationPermission permission;
-  [Exposed=Window] static Promise<NotificationPermission> requestPermission(optional NotificationPermissionCallback deprecatedCallback);
+
[Constructor(DOMString title, optional NotificationOptions options),
+ Exposed=(Window,Worker)]
+interface Notification : EventTarget {
+  static readonly attribute NotificationPermission permission;
+  [Exposed=Window] static Promise<NotificationPermission> requestPermission(optional NotificationPermissionCallback deprecatedCallback);
 
-  static readonly attribute unsigned long maxActions;
+  static readonly attribute unsigned long maxActions;
 
-  attribute EventHandler onclick;
-  attribute EventHandler onerror;
+  attribute EventHandler onclick;
+  attribute EventHandler onerror;
 
-  readonly attribute DOMString title;
-  readonly attribute NotificationDirection dir;
-  readonly attribute DOMString lang;
-  readonly attribute DOMString body;
-  readonly attribute DOMString tag;
-  readonly attribute USVString icon;
-  readonly attribute USVString badge;
-  readonly attribute USVString sound;
-  [SameObject] readonly attribute FrozenArray<unsigned long> vibrate;
-  readonly attribute DOMTimeStamp timestamp;
-  readonly attribute boolean renotify;
-  readonly attribute boolean silent;
-  readonly attribute boolean noscreen;
-  readonly attribute boolean requireInteraction;
-  readonly attribute boolean sticky;
-  [SameObject] readonly attribute any data;
-  [SameObject] readonly attribute FrozenArray<NotificationAction> actions;
+  readonly attribute DOMString title;
+  readonly attribute NotificationDirection dir;
+  readonly attribute DOMString lang;
+  readonly attribute DOMString body;
+  readonly attribute DOMString tag;
+  readonly attribute USVString icon;
+  readonly attribute USVString badge;
+  readonly attribute USVString sound;
+  [SameObject] readonly attribute FrozenArray<unsigned long> vibrate;
+  readonly attribute DOMTimeStamp timestamp;
+  readonly attribute boolean renotify;
+  readonly attribute boolean silent;
+  readonly attribute boolean noscreen;
+  readonly attribute boolean requireInteraction;
+  readonly attribute boolean sticky;
+  [SameObject] readonly attribute any data;
+  [SameObject] readonly attribute FrozenArray<NotificationAction> actions;
 
-  void close();
+  void close();
 };
 
-dictionary NotificationOptions {
-  NotificationDirection dir = "auto";
-  DOMString lang = "";
-  DOMString body = "";
-  DOMString tag = "";
-  USVString icon;
-  USVString badge;
-  USVString sound;
-  VibratePattern vibrate;
-  DOMTimeStamp timestamp;
-  boolean renotify = false;
-  boolean silent = false;
-  boolean noscreen = false;
-  boolean requireInteraction = false;
-  boolean sticky = false;
-  any data = null;
-  sequence<NotificationAction> actions = [];
+dictionary NotificationOptions {
+  NotificationDirection dir = "auto";
+  DOMString lang = "";
+  DOMString body = "";
+  DOMString tag = "";
+  USVString icon;
+  USVString badge;
+  USVString sound;
+  VibratePattern vibrate;
+  DOMTimeStamp timestamp;
+  boolean renotify = false;
+  boolean silent = false;
+  boolean noscreen = false;
+  boolean requireInteraction = false;
+  boolean sticky = false;
+  any data = null;
+  sequence<NotificationAction> actions = [];
 };
 
-enum NotificationPermission {
-  "default",
-  "denied",
-  "granted"
+enum NotificationPermission {
+  "default",
+  "denied",
+  "granted"
 };
 
-enum NotificationDirection {
-  "auto",
-  "ltr",
-  "rtl"
+enum NotificationDirection {
+  "auto",
+  "ltr",
+  "rtl"
 };
 
-dictionary NotificationAction {
-  required DOMString action;
-  required DOMString title;
-  USVString icon;
+dictionary NotificationAction {
+  required DOMString action;
+  required DOMString title;
+  USVString icon;
 };
 
-callback NotificationPermissionCallback = void (NotificationPermission permission);
+callback NotificationPermissionCallback = void (NotificationPermission permission);
 

    
A non-persistent notification is represented by one Notification object and can be created through Notification's constructor. 

    
A persistent notification is represented by zero or more Notification objects and can be created through the showNotification() method. 

@@ -858,30 +775,30 @@ 
close() method. 

    
4. Service worker API

-
dictionary GetNotificationOptions {
-  DOMString tag = "";
+
dictionary GetNotificationOptions {
+  DOMString tag = "";
 };
 
-partial interface ServiceWorkerRegistration {
-  Promise<void> showNotification(DOMString title, optional NotificationOptions options);
-  Promise<sequence<Notification>> getNotifications(optional GetNotificationOptions filter);
+partial interface ServiceWorkerRegistration {
+  Promise<void> showNotification(DOMString title, optional NotificationOptions options);
+  Promise<sequence<Notification>> getNotifications(optional GetNotificationOptions filter);
 };
 
-[Constructor(DOMString type, NotificationEventInit eventInitDict),
- Exposed=ServiceWorker]
-interface NotificationEvent : ExtendableEvent {
-  readonly attribute Notification notification;
-  readonly attribute DOMString action;
+[Constructor(DOMString type, NotificationEventInit eventInitDict),
+ Exposed=ServiceWorker]
+interface NotificationEvent : ExtendableEvent {
+  readonly attribute Notification notification;
+  readonly attribute DOMString action;
 };
 
-dictionary NotificationEventInit : ExtendableEventInit {
-  required Notification notification;
-  DOMString action = "";
+dictionary NotificationEventInit : ExtendableEventInit {
+  required Notification notification;
+  DOMString action = "";
 };
 
-partial interface ServiceWorkerGlobalScope {
-  attribute EventHandler onnotificationclick;
-  attribute EventHandler onnotificationclose;
+partial interface ServiceWorkerGlobalScope {
+  attribute EventHandler onnotificationclick;
+  attribute EventHandler onnotificationclose;
 };
 

    
The showNotification(title, options) method, when invoked, must run these steps: 

@@ -1221,108 +1138,108 @@ 
N
    
[RFC2119]
    
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
    
[URL]
-   
Anne van Kesteren; Sam Ruby. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
+   
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
    
[VIBRATION]
    
Anssi Kostiainen. Vibration API. 10 February 2015. REC. URL: https://w3c.github.io/vibration/
    
[WEBIDL]
    
Cameron McCormack; Jonas Sicking. Web IDL. URL: https://heycam.github.io/webidl/

IDL Index

-
[Constructor(DOMString title, optional NotificationOptions options),
- Exposed=(Window,Worker)]
-interface Notification : EventTarget {
-  static readonly attribute NotificationPermission permission;
-  [Exposed=Window] static Promise<NotificationPermission> requestPermission(optional NotificationPermissionCallback deprecatedCallback);
+
[Constructor(DOMString title, optional NotificationOptions options),
+ Exposed=(Window,Worker)]
+interface Notification : EventTarget {
+  static readonly attribute NotificationPermission permission;
+  [Exposed=Window] static Promise<NotificationPermission> requestPermission(optional NotificationPermissionCallback deprecatedCallback);
 
-  static readonly attribute unsigned long maxActions;
+  static readonly attribute unsigned long maxActions;
 
-  attribute EventHandler onclick;
-  attribute EventHandler onerror;
+  attribute EventHandler onclick;
+  attribute EventHandler onerror;
 
-  readonly attribute DOMString title;
-  readonly attribute NotificationDirection dir;
-  readonly attribute DOMString lang;
-  readonly attribute DOMString body;
-  readonly attribute DOMString tag;
-  readonly attribute USVString icon;
-  readonly attribute USVString badge;
-  readonly attribute USVString sound;
-  [SameObject] readonly attribute FrozenArray<unsigned long> vibrate;
-  readonly attribute DOMTimeStamp timestamp;
-  readonly attribute boolean renotify;
-  readonly attribute boolean silent;
-  readonly attribute boolean noscreen;
-  readonly attribute boolean requireInteraction;
-  readonly attribute boolean sticky;
-  [SameObject] readonly attribute any data;
-  [SameObject] readonly attribute FrozenArray<NotificationAction> actions;
+  readonly attribute DOMString title;
+  readonly attribute NotificationDirection dir;
+  readonly attribute DOMString lang;
+  readonly attribute DOMString body;
+  readonly attribute DOMString tag;
+  readonly attribute USVString icon;
+  readonly attribute USVString badge;
+  readonly attribute USVString sound;
+  [SameObject] readonly attribute FrozenArray<unsigned long> vibrate;
+  readonly attribute DOMTimeStamp timestamp;
+  readonly attribute boolean renotify;
+  readonly attribute boolean silent;
+  readonly attribute boolean noscreen;
+  readonly attribute boolean requireInteraction;
+  readonly attribute boolean sticky;
+  [SameObject] readonly attribute any data;
+  [SameObject] readonly attribute FrozenArray<NotificationAction> actions;
 
-  void close();
+  void close();
 };
 
-dictionary NotificationOptions {
-  NotificationDirection dir = "auto";
-  DOMString lang = "";
-  DOMString body = "";
-  DOMString tag = "";
-  USVString icon;
-  USVString badge;
-  USVString sound;
-  VibratePattern vibrate;
-  DOMTimeStamp timestamp;
-  boolean renotify = false;
-  boolean silent = false;
-  boolean noscreen = false;
-  boolean requireInteraction = false;
-  boolean sticky = false;
-  any data = null;
-  sequence<NotificationAction> actions = [];
+dictionary NotificationOptions {
+  NotificationDirection dir = "auto";
+  DOMString lang = "";
+  DOMString body = "";
+  DOMString tag = "";
+  USVString icon;
+  USVString badge;
+  USVString sound;
+  VibratePattern vibrate;
+  DOMTimeStamp timestamp;
+  boolean renotify = false;
+  boolean silent = false;
+  boolean noscreen = false;
+  boolean requireInteraction = false;
+  boolean sticky = false;
+  any data = null;
+  sequence<NotificationAction> actions = [];
 };
 
-enum NotificationPermission {
-  "default",
-  "denied",
-  "granted"
+enum NotificationPermission {
+  "default",
+  "denied",
+  "granted"
 };
 
-enum NotificationDirection {
-  "auto",
-  "ltr",
-  "rtl"
+enum NotificationDirection {
+  "auto",
+  "ltr",
+  "rtl"
 };
 
-dictionary NotificationAction {
-  required DOMString action;
-  required DOMString title;
-  USVString icon;
+dictionary NotificationAction {
+  required DOMString action;
+  required DOMString title;
+  USVString icon;
 };
 
-callback NotificationPermissionCallback = void (NotificationPermission permission);
+callback NotificationPermissionCallback = void (NotificationPermission permission);
 
-dictionary GetNotificationOptions {
-  DOMString tag = "";
+dictionary GetNotificationOptions {
+  DOMString tag = "";
 };
 
-partial interface ServiceWorkerRegistration {
-  Promise<void> showNotification(DOMString title, optional NotificationOptions options);
-  Promise<sequence<Notification>> getNotifications(optional GetNotificationOptions filter);
+partial interface ServiceWorkerRegistration {
+  Promise<void> showNotification(DOMString title, optional NotificationOptions options);
+  Promise<sequence<Notification>> getNotifications(optional GetNotificationOptions filter);
 };
 
-[Constructor(DOMString type, NotificationEventInit eventInitDict),
- Exposed=ServiceWorker]
-interface NotificationEvent : ExtendableEvent {
-  readonly attribute Notification notification;
-  readonly attribute DOMString action;
+[Constructor(DOMString type, NotificationEventInit eventInitDict),
+ Exposed=ServiceWorker]
+interface NotificationEvent : ExtendableEvent {
+  readonly attribute Notification notification;
+  readonly attribute DOMString action;
 };
 
-dictionary NotificationEventInit : ExtendableEventInit {
-  required Notification notification;
-  DOMString action = "";
+dictionary NotificationEventInit : ExtendableEventInit {
+  required Notification notification;
+  DOMString action = "";
 };
 
-partial interface ServiceWorkerGlobalScope {
-  attribute EventHandler onnotificationclick;
-  attribute EventHandler onnotificationclose;
+partial interface ServiceWorkerGlobalScope {
+  attribute EventHandler onnotificationclick;
+  attribute EventHandler onnotificationclose;
 };
 
 

\ No newline at end of file