How To Use The HTML5 Notification API

HTML5 isn't something new, everyone has heard about it but there are some features with HTML5 that people don't know about. Most people think that all HTML5 is are new semantic tags like header, footer, nav, article, section which you can use on the document but many people don't know some of the awesome new features which are now available to developers, things like:

• HTML5 Details Tag
• HTML5 Form features

In this article we are going to look at a new feature in HTML5 called the notification API. The most popular use of this feature would be Gmail alerting you of new email, if you have a Gmail tab currently open. You will get an alert box pop up at the bottom right of the screen with the title and message inside. We are going to look at how you can use this API to create your own notification messages.

#Browser Support

A good place to start is to mention the browser support, the notification API is still in draft stage and therefore it is not a current web standard. This means that it is not supported over all browsers, in fact this is only supported on webkit browsers. It was first introduced into webkit from version 19 of Chrome and version 6 of safari. It is not yet known if the other browsers will be supporting this in the future but I think they should as I can see it being a very important feature for web apps. The best place to see what browsers support this feature is to use the website caniuse.com. Notification API

#Notification API

There are two objects to use in the Notication API the first is the notification object.

interface Notification : EventTarget {
 // display methods
 void show();
 void cancel();

 // event handler attributes
 attribute Function ondisplay;
 attribute Function onerror;
 attribute Function onclose;
 attribute Function onclick;
}

This is the interface you will use for the notifications, it has 2 methods and 4 attributes attached to it.

#Notification Methods

The notification methods are used to display or hide the notification box. - Show - This method will display a notification

• Cancel - This will remove the notification, if the notification is currently displayed this will hide it. If the notification is not displayed then this will stop it from being displayed.

#Notification Attributes

The notification attributes are used as event listeners on the different events on the notification. - ondisplay - A function to run when the notification box is displayed.

• onerror - A function to run when there is an error with the notification box.
• onclose - A function to run when the notification box is closed.
• onclick - A function to run when there is a click on the notification box.

The second object needed for notifications is the NotificationCenter interface which is available to the webpage via the window interface.

interface NotificationCenter {
 // Notification factory methods.
 Notification createNotification(in DOMString iconUrl, in DOMString title, in DOMString body) throws(Exception);
 optional Notification createHTMLNotification(in DOMString url) throws(Exception);

 // Permission values
 const unsigned int PERMISSION_ALLOWED = 0;
 const unsigned int PERMISSION_NOT_ALLOWED = 1;
 const unsigned int PERMISSION_DENIED = 2;

 // Permission methods
 int checkPermission();
 void requestPermission(in Function callback);
}

interface Window {
...
 attribute NotificationCenter webkitNotifications;
...
}

The notification center is used to create notification objects and check that the webpage has permission to display the notification objects. There are 4 methods that will need to use on the notification center: - createNotification - If the notification has permission to be displayed then this method will create a notification object populated with the content supplied to it. If the web page does not have permission to display the notification then this will throw a security exception.

• createHTMLNotification - This is similar to the createNotification method it will return a populated notification if the webpage has permission to display the notification. This method uses a parameter of a URL to get the HTML to be displayed.
• checkPermission - This will return an integer of the permission the notification has on this webpage. * PERMISSION_ALLOWED* = 0, PERMISSION_NOT_ALLOWED = 1, or PERMISSION_DENIED = 2
• requestPermission - This will ask for permission from the user to display the notification box.

#Does The Browser Support Notifications

If you are going to do anything with the notification API you first need to check if the browser supports it to do this you can use a simple if statement on webkitNotification.

/**
 * Check if the browser supports notifications
 * 
 * @return true if browser does support notifications
 */
 function browser_support_notification()
 {
        return window.webkitNotifications;
 }

#Get Permissions To Display Alert

To display notifications to the user you must first get permission to display any notifications. To get permission to display all you have to do is use the method requestPermission().

/**
* Request notification permissions
*/
function request_permission()
{
	// 0 means we have permission to display notifications
	if (window.webkitNotifications.checkPermission() == 0) {
	    window.webkitNotifications.createNotification();
        } else {
	    window.webkitNotifications.requestPermission();
	}
}

#Display Plain Text Notification Box

To create a plain text notification box you first need to check if you have permission to display the notification box. If you do then we can create a new notification using the method createNotification() passing in the parameters for the image, title and description.

/**
* Create a plain text notification box
*/
function plain_text_notification(image, title, content)
{
    	if (window.webkitNotifications.checkPermission() == 0) {
    		return window.webkitNotifications.createNotification(image, title, content);
    	}
}

#Display HTML Notification Box

To display HTML in a notification box we need to do the same thing as the plain text notification box by checking if we have permission to display the notification box. If we do then we can create the a notification box passing in the HTML URL to display.

/**
 * Create a notification box with html inside
 */
 function html_notification(url)
 {
    	if (window.webkitNotifications.checkPermission() == 0) {
    		return window.webkitNotifications.createHTMLNotification(url);
    	}
 }

#Demo

On the demo page you will see this notification alert box in action, both the plain text and html demo.