Quickstart: Using the NotificationsExtensions library in your code

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) directly. 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 both square and wide tile versions 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.
• The ability to create a basic Windows Store app with JavaScript using Windows Runtime APIs.
• 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 core tiles and badges sample for this procedure.

1. Download the App tiles and badges sample from the Windows Dev Center.
2. Unzip the App tiles and badges sample.zip file to a folder of your choosing.

2. Include the library in your project

1. Start Microsoft Visual Studio 2012 or Microsoft Visual Studio Express 2012 for Windows 8 and select File > Open > Project/Solution.
2. Go to the directory in which you unzipped the sample and double-click the sample's Visual Studio Solution (.sln) file.
3. Press F7 or use Build > Build Solution to build the sample.
4. Copy the built binary file NotificationsExtensions.winmd from the sample folder (under \NotificationsExtensions\bin\Relase\) to your own project directory. No specific location within your project is required, but we recommend putting it in the folder that contains your .appxmanifest file.
5. Open your project in Visual Studio 2012 or Visual Studio Express 2012 for Windows 8.
6. From the Project menu, select Add Reference.
7. Browse to the location of the NotificationsExtensions.winmd (NotificationsExtensions.dll for a web service) file, select that file, and press the Add button.

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). The only caveat is that you must add the WINRT_NOT_PRESENT compilation build symbol in the NotificationsExtensions project properties.

1. 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.
2. Select the NotificationsExtensions.csproj file to open the project in Visual Studio 2012 or Visual Studio Express 2012 for Windows 8.
3. From the Project menu, choose NotificationsExtensions Properties.
4. Select Build.

5. 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" as shown here:

   

6. Press F7 or use Build > Build Solution to build the project.
7. Copy the built binary file NotificationsExtensions.winmd from the sample 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.

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

var badgeContent = new NotificationsExtensions.BadgeContent.BadgeNumericNotificationContent(85);

var badgeNotification = badgeContent.createNotification();
Windows.UI.Notifications.BadgeUpdateManager.createBadgeUpdaterForApplication().update(badgeNotification);

This example shows the same procedure expressed as a direct manipulation of the XML DOM, not using NotificationsExtensions.

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

var badgeNotification = new Notifications.BadgeNotification(badgeXml);
Windows.UI.Notifications.BadgeUpdateManager.createBadgeUpdaterForApplication().update(badgeNotification);

This example uses NotificationsExtensions to supply text for use in a tile. The first step is the use of the 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 "createTileWideImageAndText01".

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

Once you've assigned strings to your text objects, you send the tile notification normally.

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

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 template. Like text, image elements are named for their function in the template, such as imageMain and imageSmallColumn2Row2.

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

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 wide and square versions of a tile notification and package them together. Note that when using NotificationsExtensions, order is important—you must first create the wide version and then add the square version to the wide.

var tileContent = NotificationsExtensions.TileContent.TileContentFactory.createTileWideText03();
tileContent.textHeadingWrap.text = "Hello World! My very own tile notification";

var squareTileContent = NotificationsExtensions.TileContent.TileContentFactory.createTileSquareText04();
squareTileContent.textBodyWrap.text = "Hello World! My very own tile notification";

tileContent.squareContent = squareTileContent;

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

This example uses NotificationsExtensions to supply text and image content for a toast. It also supplies audio and duration attributes for the toast.

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

toastContent.textHeading.text = "Heading text"; 
toastContent.textBodyWrap.text = "Body text that wraps over two lines";

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

toastContent.duration = toastContent.ToastDuration.long;

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

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.

Build date: 11/29/2012