win-notify

Simple notifications API for JavaScript Windows Store apps

Project maintained by tadeuszwojcik Hosted on GitHub Pages — Theme by mattgraham

win-notify

Simple notifications API for JavaScript Windows Store apps.

Compatible with Windows 8 and 8.1 APIs.

Why?

Short version: because native WinRT notifications API (Windows.UI.Notifications) isn't JavaScript friendly(to put it mildly - see example below).

Longer version: Everyone who builds Windows Store apps knows that live tiles and toasts notifications are great way to engage users. WinRT API provides way to utilize those features, unfortunately it requires messing with XML (yeah XML - see example below) and work with API which is more designed for C#/C++ devs. I was a bit frustrated by the current state of affairs, so written this lib. It's not too abstracted from native WinRT API, but provides much simpler way of working with notifications from Javascript (at least I hope so).

Installation

$ npm install win-notify

$ bower install win-notify

or simply copy file win-notify.js file to your project.

Examples

Tile notifications

tile notifications

Let's say we want to update tile with text and image when it's displayed on start screen as wide tile and text only when it's displayed as medium tile:

 

using win-notify:
winNotify.viaTileUpdate({
    tileWide310x150SmallImageAndText04: {
      image1: 'http://uifaces.com/faces/_twitter/cacestgang_73.jpg',
      text1: 'Hello',
      text2: 'World'
    },
    tileSquareText02: {
      text1: 'Hello',
      text2: 'World'
    }
  }
);
using native WinRT notifications API:
var Notifications = Windows.UI.Notifications;
var Imaging = Windows.Graphics.Imaging;

var tileXml = Notifications.TileUpdateManager.getTemplateContent(
  Notifications.TileTemplateType.tileWide310x150SmallImageAndText04);

var tileTextAttributes = tileXml.getElementsByTagName("text");
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello"));
tileTextAttributes[1].appendChild(tileXml.createTextNode("World"));

var tileImageAttributes = tileXml.getElementsByTagName("image");
tileImageAttributes[0].setAttribute("src", "http://uifaces.com/faces/_twitter/cacestgang_73.jpg");

var squareTileXml = Notifications.TileUpdateManager.getTemplateContent(
  Notifications.TileTemplateType.tileSquareText02);

var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello"));
squareTileTextAttributes[1].appendChild(squareTileXml.createTextNode("World"));

var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

var tileNotification = new Notifications.TileNotification(tileXml);

var tileUpdater = Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication();
tileUpdater.update(tileNotification);

Hope you see now which API is simpler and why it's worth using win-notify in your project. Check out API section to learn more about details.

Toast notifications

toast notifications

Let's say we want to show toast notification with text and image:

using win-notify:
winNotify.viaToast({
  toastImageAndText02: {
    text1: 'Hello',
    text2: 'World',
    image1: 'http://uifaces.com/faces/_twitter/cacestgang_73.jpg',
  }
});
using native WinRT notifications API:
var notifications = Windows.UI.Notifications;

var template = notifications.ToastTemplateType.toastImageAndText02;
var toastXml = notifications.ToastNotificationManager.getTemplateContent(template);

var toastTextElements = toastXml.getElementsByTagName("text");
toastTextElements[0].innerText = "Hello";
toastTextElements[1].innerText = "World";

var toastImageElements = toastXml.getElementsByTagName("image");
toastImageElements[0].setAttribute("src", "http://uifaces.com/faces/_twitter/cacestgang_73.jpg");

var toast = new notifications.ToastNotification(toastXml);
var toastNotifier = notifications.ToastNotificationManager.createToastNotifier();
toastNotifier.show(toast);

Again, win-notify is much simpler to use than native WinRT notifications API. Check out API section to learn more about details.

API Documentation on GitHub

Credits

Thanks Kraig Brockschmidt for images (hope he don't mind) and presentation Alive with Activity explaining notifications concepts in clear way and Microsoft for MSDN docs.

License

WTFPL