Webinos Logo

The Web Notifications API

Webinos API Specifications

28 Aug 2012

Authors


Abstract

The webinos Web Notifications specification provides an API to display notifications to alert users outside the context of a web page.

Table of Contents

  1. Introduction
  2. Interfaces and Dictionaries
    1. Webinos
    2. NotificationManager
    3. Notification
    4. NotificationOptions
  3. Enums
    1. NotificationDirection
  4. Features
  5. Full WebIDL

Summary of Methods

Interface Method
Webinos
NotificationManager
Notification close ()

Introduction

The webinos Web Notifications specification is based on the W3C Web Notifications specification. It does not specify exactly how a user agent should display these notifications; the best presentation depends on the device where the user agent is run. When this specification refers to displaying notifications on the "desktop", it generally refers to some static display area outside the scope of the application, but may take several forms, including:

- A corner of the user's display.
- An area within the chrome of the user agent.
- The "home" screen of a mobile device.

This specification does not define exactly how the user agent should display the notification, and the API is designed to be flexible with respect to presentation options. This specification is designed to be compatible with existing notification platforms as much as possible, but also to be platform-independent. Since the common platforms do not provide the same functionality, this spec will indicate what events are guaranteed and which are not. In particular, notifications as specified here only can contain text and icon content. In the future, notifications generated from web content may wish to contain web content themselves, but that is outside the scope of this document.

In contrast to the original W3C version of this API, the event model for notifications is reliable and not best-effort; the Notification object offers a click event and applications may enhance their functionality by listening for that event.

Interfaces and Dictionaries

Interface Webinos (partial interface)

The Notification interface describes the part of the Web Notification API accessible through the webinos object.

WebIDL
        partial interface Webinos {

            readonly attribute NotificationManager notification;
        };

Attributes

readonly NotificationManager notification

webinos.notification object.

This attribute is readonly.

Interface NotificationManager

The NotificationManager interface which is accessible by using the webinos service discovery API.

WebIDL
        [NoInterfaceObject] 
        interface NotificationManager {

            attribute Notification notification;
        };

Attributes

Notification notification

The object through which a new notification can be created. No exceptions.

Interface Notification

The Notification interface for showing notifications when created.

WebIDL
        [Constructor(DOMString title, optional NotificationOptions options)]

        interface Notification : EventTarget {
  

           attribute Function? onclick;

           attribute Function? onshow;

           attribute Function? onerror;

           attribute Function? onclose;


                        close();
        };

Constructors

Notification(DOMString title, optional NotificationOptions options);
Parameters
  • title
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description:
  • options
WebIDL
Constructor(DOMString title, optional NotificationOptions options)

Attributes

Function? onclick

Callback called when the shown notification was clicked.

Function? onshow

Callback called when the notification is shown.

Function? onerror

Callback called when the could not be shown.

Function? onclose

Callback called when the notification was closed.

Methods

Close the notification.

Signature
close ();

Dictionary NotificationOptions

The NotificationOptions that defining the content of the notification.

WebIDL
        dictionary NotificationOptions {

           NotificationDirection titleDir;

           DOMString body;

           NotificationDirection bodyDir;

           DOMString tag;

           DOMString iconUrl;
        };

Dictionary Members

NotificationDirection titleDir

The title direction of this notification.

Can be null.

DOMString body

The body content of this notification.

Can be null.

NotificationDirection bodyDir

The body direction of this notification.

Can be null.

DOMString tag

The tag of this notification.

Notifications which represent the same conceptual event can be tagged in the same way, and when both are shown, the user will only receive one notification. Can be null.

DOMString iconUrl

The URI that represents an icon to be shown by the notification.

Can be null.

Enums

NotificationDirection

The NotificationDirection that defines possible directions of displaying notifications.

WebIDL
        enum NotificationDirection {
           "auto",
           "ltr",
           "rtl"
        };

Values

auto
ltr
rtl

Features

This is the list of URIs used to declare this API's features, for use in the widget config.xml and as identifier for service type in service discovery functionality. For each URI, the list of functions covered is provided.

http://webinos.org/api/notifications

Accessing the notification API

Full WebIDL

WebIDL
        partial interface Webinos {

            readonly attribute NotificationManager notification;
        };
 
  

        [NoInterfaceObject] 
        interface NotificationManager {

            attribute Notification notification;
        };
 


        [Constructor(DOMString title, optional NotificationOptions options)]

        interface Notification : EventTarget {
  

           attribute Function? onclick;

           attribute Function? onshow;

           attribute Function? onerror;

           attribute Function? onclose;


                        close();
        };


        dictionary NotificationOptions {

           NotificationDirection titleDir;

           DOMString body;

           NotificationDirection bodyDir;

           DOMString tag;

           DOMString iconUrl;
        };


        enum NotificationDirection {
           "auto",
           "ltr",
           "rtl"
        };