L'API de notification d'HTML 5

Ce tutoriel est la traduction la plus fidèle possible du tutoriel original de Paul Underwood, How To Use The HTML5 Notification API.

HTML 5 n'est pas nouveau, tout le monde en a au moins entendu parler ; mais il y a quelques fonctionnalités qui sont encore méconnues. La plupart des gens associe HTML 5 aux nouveaux tags header, footer, nav, article que vous pouvez utiliser dans vos pages mais peu connaissent les excellentes fonctionnalités disponibles pour les développeurs telles que l'API de géolocalisation ou encore la validation de formulaire.

Dans ce tutoriel nous allons nous intéresser à l'API de notification.

L'utilisation la plus connue de cette API est l'alerte de nouveaux e-mails sur Gmail. Si vous recevez un nouvel e-mail, une boite de dialogue s'ouvre en bas à droite de l'écran contenant le sujet et le contenu de l'e-mail. Nous allons voir comment créer nos propres messages d'alerte grâce à cette API.

Pour commencer il est important de parler des navigateurs qui supportent l'API. En effet l'API de notification est toujours en phase de tests et n'est donc pas encore considérée comme un standard. Ce qui signifie qu'elle n'est pas supportée par tous les navigateurs mais uniquement par les navigateurs webkits.

Elle a été introduite dans la version 19 de Chrome et la version 6 de Safari. On ne sait pas encore si les autres navigateurs supporteront l'API dans le futur mais il y a de grandes chances que ce soit le cas vu l'importance de cette API.

La meilleure façon de connaître la compatibilité d'un navigateur est d'utiliser caniuse.com :

API de notification

Il existe deux objets à utiliser avec l'API de notification. Le premier est l'objet notification.

interface Notification : EventTarget {
 // display methods
 void show();
 void cancel();
 // event handler attributes
 attribute Function ondisplay;
 attribute Function onerror;
 attribute Function onclose;
 attribute Function onclick;
}

C'est cette interface que vous allez utiliser pour les notifications, elle dispose de deux méthodes et quatre attributs.

IV-A. Méthodes▲

IV-B. Attributs▲

Le second objet de l'API est l'interface NotificationCenter qui est disponible dans la page web via l'interface de la fenêtre.

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;
...
}

L'objet NotificationCenter est utilisé pour créer des objets notification et vérifier que la page web a la permission d'afficher des notifications.

Il y a quatre méthodes à utiliser avec l'interface :

• la méthode createNotification : si la notification est autorisée à être affichée, cette méthode va créer un objet notification alimenté avec le contenu qui lui est fourni. Si la page web n'a pas la permission d'afficher des notifications, la méthode retournera une exception de sécurité ;
• la méthode createHTMLNotification : similaire à la méthode ci-dessus, cette méthode va créer une notification alimentée si la page a les permissions requises. Elle prend en paramètre une URL pour récupérer le code HTML qui doit être affiché ;
• la méthode checkPermission : retourne un entier correspondant à la permission de la notification sur la page web. PERMISSION_ALLOWED = 0, PERMISSION_NOT_ALLOWED = 1, PERMISSION_DENIED = 2 ;
• la méthode requestPermission : demande la permission à l'utilisateur d'afficher la boite de dialogue de notification.

Si vous voulez utiliser n'importe quelle fonction de l'API de notification, vous devez en premier lieu vérifier que votre navigateur la supporte. Pour ce faire, vous pouvez utiliser une simple condition if.

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

Pour afficher des notifications à un utilisateur vous devez avant tout obtenir la permission d'afficher des notifications. Pour ce faire, il vous suffit d'utiliser la méthode 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();
        }
}

Pour créer une notification qui contiendra du texte simple vous devez d'abord vérifier que vous en avez la permission. Si c'est le cas, vous pouvez créer une nouvelle notification en utilisant la méthode createNotification() et en lui passant en paramètre l'image, le titre et le contenu de la notification.

/**
* 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);
        }
}

Pour afficher une notification de type HTML nous devons opérer de la même manière que précédemment en vérifiant que nous avons la permission de créer la notification. Si tel est le cas, il suffit d'utiliser la méthode html_notification().

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

Nous avons vu dans ce tutoriel comment utiliser l'API de notification qui est disponible avec HTML 5. Vous pouvez vous amuser à créer vos propres boites de notification !

Vous pouvez consulter la démonstration pour avoir un aperçu du rendu dans un navigateur.

Je tiens à remercier Paul Underwood pour m'avoir autorisé à traduire son tutoriel.
Je remercie également f-leb pour sa relecture orthographique.