win-notify
v0.1.1
Published
Simple notifications API for JavaScript Windows Store apps
Downloads
12
Readme
#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
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 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
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
Tile updates
winNotify.viaTileUpdate(templatesDefinitions, [optional] options)
Updates live tile with new content defined in templates definitions.
templatesDefinitions
It's an object which contains template definition objects and has following structure:
{
'templateDefinition': {
... template paremeters
},
'TemplateDefinition' : {
... template parameters
}
}
Every single templateDefinition
object needs to named after template name from tile templates catalog
(for example tileSquare150x150Text04
).
Both camelCase and PascalCase naming conventions are supported (both tileSquare150x150Text04
and TileSquare150x150Text04
will work).
If you want to send update only for one tile type, specify only one template definition,
if you want to handle more tile types(medium, wide, large etc) specify template definition
for each of them (it's best practise to send updates to all handled by app tile types, so if your app
supports wide and medium tiles send update for both).
When you know which template definition from catalog you want to use, templateDefinition
object needs to contain properties which are template's parameters and those can be of text
or image
type.
image
- can be simplestring
orobject
withsrc
,alt
andaddImageQuery
properties - see MSDN for more detailstext
- can be simplestring
orobject
withlang
andtext
properties - see MSDN for more details
Let's say we want to use template TileSquare150x150PeekImageAndText02
:
It has following xml definition:
<tile>
<visual version="2">
<binding template="TileSquare150x150PeekImageAndText02" fallback="TileSquarePeekImageAndText02">
<image id="1" src="image1" alt="alt text"/>
<text id="1">Text Field 1 (larger text)</text>
<text id="2">Text Field 2</text>
</binding>
</visual>
</tile>
Templatedefinition
object for such template looks like:
tileSquare150x150PeekImageAndText02: {
image1: {
src:'image1',
alt:'alt text'
},
text1: 'Text Field 1 (larger text)',
text2: 'Text Field 2'
}
Notice that image
and text
properites have proper suffixes which match id
of element in template xml
(text1
for text with id=1 etc).
options
It's an object with following properties (all optional):
addImageQuery
, baseUri
, branding
, contentId
, lang
, version
Read more about each of them on MSDN.
Additionalally options object can contain following properties:
tag
- gets or sets astring
that Windows can use to prevent duplicate notification content from appearing in the queue.expirationTime
- gets or sets the time (DateTime
) that Windows will remove the notification from the tile.tileId
- if not specified tile update will update application tile, if specified it will update secondary tile if secondary tile withtileId
existsdeliveryTime
- gets the time (DateTime) at which the tile is scheduled to be updated (applies only to scheduled tile updates).id
- gets or sets the unique ID that is used to identify the scheduled tile in the schedule (applies only to scheduled tile updates).debug
- if set to true willconsole.log
xml output for debugging purposes
winNotify.viaScheduledTileUpdate(templatesDefinitions, [optional] options)
Schedules update to live tile with new content defined in templates definition.
Both TemplatesDefinitions
and options
objects are the same as for winNotify.viaTileUpdate
method.
winNotify.clearTile([optional] options)
Removes all updates and causes the tile to display its default content as declared in the app's manifest.
Optional options object can contain tileId
property which allows to clear content of secondary tile.
Toasts notifications
winNotify.viaToast(templatesDefinitions, [optional] options)
Raises a toast notification.
Templatesdefinitions
object has the same structure as one from winNotify.viaTileUpdate
method.
Only template names are changes, and need to match ones
from [toasts template catalog] (http://msdn.microsoft.com/en-us/library/windows/apps/hh761494.aspx).
Let's say we want to use template ToastImageAndText04
:
It has following xml definition:
<toast>
<visual>
<binding template="ToastImageAndText04">
<image id="1" src="image1" alt="image1"/>
<text id="1">headlineText</text>
<text id="2">bodyText1</text>
<text id="3">bodyText2</text>
</binding>
</visual>
</toast>
Templatedefinition
object for such template looks like:
toastImageAndText04: {
image1: {
src:'image1',
alt:'alt text'
},
text1: 'headlineText',
text2: 'bodyText1',
text3: 'bodyText2'
}
options
Options from winNotify.viaTileUpdate
apply here as well, additionally you can specify following properties:
onactivated
,ondismissed
,onfailed
(MSDN reference)launch
,duration
(MSDN reference)loop
,silent
src
(MSDN reference)
winNotify.viaScheduledToast(templatesDefinitions, [optional] options)
Schedule toast notification that will display at the scheduled time.
Both TemplatesDefinitions
and options
objects are the same as for winNotify.viaToast
method.
Badge updates
winNotify.viaBadgeUpdate(value, [optional] options)
Updates a badge overlay tile.
Value
is a string and defines badge value (MSDN referene).
Options
object can contain tileId
property, so badge update will update badge of secondary tile, not main app tile.
winNotify.clearBadge([optional] options)
Removes the badge from the tile.
Optional options object can contain tileId
property which allows to remove badge of secondary tile.
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.