Quickstart: Using the NotificationsExtensions library in your code (HTML)

Article
08/31/2015

Note Not using JavaScript? See Quickstart: Using the NotificationsExtensions library in your code (XAML).

The NotificationsExtensions object model library allows you to supply tile, badge, and toast notification XML template contents without using the XML Document Object Model (DOM). It gives you a simpler, clearer, and more direct method of supplying notification content. When you use this library in Microsoft Visual Studio, you gain these advantages:

IntelliSense which lists the available tags and attributes as object properties, rather than having to consult the schema documentation for elements and structure.
A factory function through which you can create skeleton notifications that you can then fill in with your content.
A simplified way to include multiple tile sizes in your notification payload (a best practice!).
A helpful way to find and fill in text and image attributes, which are named to give you more information as to their intended use, size, or position in the template.

Note The NotificationsExtensions library is released under an Microsoft Limited Public License (MS-LPL). You may reuse the library in your Windows Store app or web service and customize it if necessary for your app.

Prerequisites

A working knowledge of tile and notification terms and concepts. For more information, see Tiles, Badges, and Notifications.
The ability to create a basic Windows Store app with JavaScript using Windows Runtime APIs. For more information, see Create your first Windows Store app using JavaScript.
A basic knowledge of XML will give you a better idea of what the NotificationsExtensions library is creating for you.

Instructions

1. Get the NotificationsExtensions library

The NotificationsExtensions library is included in several downloadable tile, toast, and notifications samples and can be copied from them for your own use. We'll use the main tiles and badges sample in this procedure.

Note NotificationsExtensions is a C# library, but can be included in and used with JavaScript, C#, C++, and Microsoft Visual Basic projects.

Download the App tiles and badges sample from the Windows Dev Center.
Unzip the "App tiles and badges sample.zip" file to a folder of your choosing.
Go to the folder to which you unzipped the sample. Copy the NotificationsExtensions folder from the sample into your own project directory, as a sibling of your project's .sln file.

2. Include the library in your project

Launch Visual Studio and open your project.
In the Project Explorer, right-click the solution at the top of the tree.
Select Add then Existing Project.
Navigate to the NotificationsExtensions folder in your project and select the NotificationsExtensions.csproj file.
In each project within your solution, right-click References and select Add Reference.
In the Reference Manager, under Solution, select NotificationsExtensions and then click OK. At this point, NotificationsExtensions is ready to use.

Note If you don't want to include the full NotificationsExtensions project in your solution, you can build NotificationsExtensions as a stand-alone project and simply include the NotificationsExtensions.winmd as a reference in your project.

3. Include the library on your app server

You can also use NotificationsExtensions in your app server code if you are using ASP.NET to send push notifications to Windows Push Notification Services (WNS) or if you are implementing an ASP.NET service to handle requests for periodic tile or badge updates. The only caveat is that you must add the WINRT_NOT_PRESENT compilation build symbol in the NotificationsExtensions project properties.

Go to the directory in which you unzipped the sample. Open the sample folder and copy its NotificationsExtensions folder to a new location of your choosing.
Select the NotificationsExtensions.csproj file to open the project in Visual Studio.
From the Project menu, choose NotificationsExtensions Properties.
Change the Output type selection to "Class Library" to build a DLL file.
Also in the NotificationsExtensions properties, select the Build tab.
Under the General category, add "WINRT_NOT_PRESENT" in the Conditional compilation symbols box. If the box already contains other symbols, add a semi-colon as a separator before "WINRT_NOT_PRESENT".
Press F7 or use Build > Build Solution to build the project.
Copy the built NotificationsExtensions.dll file from your folder (under \NotificationsExtensions\bin\Debug\) to your app server code.

4. Use the library in your code

NotificationsExtensions can now be used as an object in your code. Its contains three members of note:

BadgeContent
TileContent
ToastContent

Each of those content types in turn contains members that represent the elements and attributes for each type.

The following example uses NotificationsExtensions to assign a value to a numeric badge, and then sends it to the tile.


var badgeContent = NotificationsExtensions.BadgeContent.BadgeNumericNotificationContent(85);
var badgeNotification = badgeContent.createNotification();

Windows.UI.Notifications.BadgeUpdateManager.createBadgeUpdaterForApplication().update(badgeNotification);

For comparison, the following example shows the same procedure without NotificationsExtensions, using direct manipulation of the XML DOM.


var notifications = Windows.UI.Notifications;                        
var badgeXml = notifications.BadgeUpdateManager.getTemplateContent(notifications.BadgeTemplateType.badgeNumber);
var badgeAttributes = badgeXml.getElementsByTagName("badge");
badgeAttributes[0].setAttribute("value", "85");
var badgeNotification = new notifications.BadgeNotification(badgeXml);

BadgeUpdateManager.createBadgeUpdaterForApplication().update(badgeNotification);

The next example uses NotificationsExtensions to supply text in a tile notification. The first step uses the NotificationsExtensions TileContentFactory function to create an object based on a specific template. There is a separate create function for each template; simply attach the word "create" to the template name, such as "createTileWide310x150ImageAndText01".

The template-based object then provides IntelliSense to show the elements available in that template, as properties named according to their function, such as textHeading, textBodyWrap, textBody1, or textColumn1Row4. This tells you precisely which element you are assigning.

Once you've assigned values to the properties, you send the tile notification normally.


var tileContent = NotificationsExtensions.TileContent.TileContentFactory.createTileSquare150x150Text01();

tileContent.textHeading.text = "Hello!";
tileContent.textBody1.text = "One";
tileContent.textBody2.text = "Two";
tileContent.textBody3.text = "Three";

var tileNotification = tileContent.createNotification();

Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

This example uses NotificationsExtentions to assign text and an image to a notification. Like text, image elements are shown as properties named for their function in the template, such as imageMain and imageSmallColumn2Row2.


var tileContent = NotificationsExtensions.TileContent.TileContentFactory.createTileWide310x150ImageAndText01();

tileContent.textCaptionWrap.text = "This tile notification uses ms-appx images";

tileContent.image.src = "ms-appx:///images/redWide.png";
tileContent.image.alt = "A red rectangle";

This example uses NotificationsExtensions to define a full tile notification. This illustrates one peculiarity of this library—the order in which you add template sizes to the payload matters.

A small template (square71x71—Windows Phone 8.1 only) can only be added to a medium template.
A medium template (square150x150) can only be added to a wide template.
A wide template can only be added to a large (square310x310—Windows only) template.

If you try to do it in a different order, you'll find that the necessary properties are not available.


var tileLargeContent = NotificationsExtensions.TileContent.TileContentFactory.createTileSquare310x310Text09();
tileLargeContent.textHeadingWrap.text = "Lorem ipsum dolor sit amet, consectetur";
tileLargeContent.textHeading1.text = "Lorem ipsumo";
tileLargeContent.textHeading2.text = "Lorem ipsumo";
tileLargeContent.textBody1.text = "VivAmus tincidunt convallis urn";
tileLargeContent.textBody2.text = "VivAmus tincidunt convallis urn";

var tileWideContent = NotificationsExtensions.TileContent.TileContentFactory.createTileWide310x150Text04();
tileWideContent.textBodyWrap.text = "Lorem ipsum dolor sit amet, consectetur";

var tileMediumContent = NotificationsExtensions.TileContent.TileContentFactory.createTileSquare150x150Block();
tileMediumContent.textBlock.text = "24";
tileMediumContent.textSubBlock.text = "Aliquam";
        
tileWideContent.square150x150Content = tileMediumContent;
tileLargeContent.wide310x150Content = tileWideContent;

var tileNotification = tileLargeContent.createNotification();

Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

This example uses NotificationsExtensions to supply content for a toast notification, including text, image, audio, duration, and launch parameters.


var toastContent = NotificationsExtensions.ToastContent.ToastContentFactory.createToastImageAndText01();

toastContent.textBodyWrap.text = "Lorem ipsum dolor sit amet";

toastContent.image.src = "ms-appx:///images/redWide.png";
toastContent.image.alt = "A red rectangle";

toastContent.audio.content = NotificationsExtensions.ToastContent.ToastAudioContent.loopingAlarm;
toastContent.audio.loop = true;

toastContent.duration = NotificationsExtensions.ToastContent.ToastDuration.long;

toastContent.launch = '{"type":"toast","param1":"12345","param2":"67890"}';

var toast = toastContent.createNotification();
Windows.UI.Notifications.ToastNotificationManager.createToastNotifier().show(toast);

Summary

This topic has shown you how to use NotificationsExtensions to simplify the creation of badge, tile, and toast notifications. This is a more straightforward way to populate a template than dealing directly with the XML DOM.

Share via