C# and .NET Tips and Tricks

Tile Notifications in Windows 8 (Javascript)

This post will cover the main aspects of using Tile Notifications in a Metro-Style application. The only topic that will not be covered is “Push Notifications” since those deserve a post on their own and will follow in the near future.

So what are “Tile Notifications”? Well as you already know, each Metro-Style application has its own tile which appears in the start screen. This tile is either a “square” or a “wide” one as depicted in the following figure:

The user gets to choose from the “start menu” application bar which one of the two will be shown. You specify in your application that you support both by providing in the package.appxmanifest file (Application UI tab) a image for both the Logo and the Wide logo property:

It is important that you provide the wide version of the logo cause otherwise your application will not be able to appear as “wide” in the start menu and that option will not exist for the user in the application bar. Having done this, you may use the tile to make it “alive”, that is to provide some meaningful information (related to your app) to the user. The way this information will be delivered, defines the type of the notification:

Scheduled: Your application, when it is executed, schedules for some tile notification in the future. A possible scenario for this is when you have for example a calendar app, the user adds an appointment and defines that he would like to get notified. Then your app may schedule a notification to appear in the tile when the time comes.

Periodic: Your applications, at specific time intervals, asks from the operating system to make a request to a web service and display in the application’s tile the content it receives from the service. A possible scenario for this is when for example your app displays news of some kind and you want your tile to always present the latest news.

Push: Those are notifications that are initiated from a web service outside of your app which instructs the OS to change your tile with the content the service provides. As stated before this kind of notification and the way to create a web server capable of delivering such notification will be explained in a future post.

Apart from the type of notifications you may also define a notifications queue. That is you can define whether a newer notification will overwrite the current one displayed on the tile or the new notification will be inserted in a queue of the five most recent ones to be cycled on the tile. So let’s get started with the following code that schedules for a notification after 10 seconds:

   1: var notifications = Windows.UI.Notifications;

   2: var currentDate = new Date();

The following lines create the tile appearance for its “wide” version. The version is defined by the template (highlighted in yellow). The list of available templates may be found here. Basically the content provided for the tile is nothing more than a simple xml document with the information required for each tile type.

   1: var tileXMLWide = notifications.TileUpdateManager.getTemplateContent
                                               (notifications.TileTemplateType.tileWideText03); 

   2: var tileAttributesWide = tileXMLWide.getElementsByTagName("text"); 

   3: tileAttributesWide[0].appendChild(tileXMLWide.createTextNode("First Notification"));

The following lines create the tile appearance for its “square” version (of course we may only create one of the two but it is good practice if we support both versions to support both versions in the notifications also):

   1: var tileXMLSquare = notifications.TileUpdateManager.getTemplateContent
                                               (notifications.TileTemplateType.tileSquareText01); 

   2: var tileAttributesSquare = tileXMLSquare.getElementsByTagName("text"); 

   3: tileAttributesSquare[0].appendChild(tileXMLSquare.createTextNode("1st"));

Finally the two versions “square” and “wide” are packed in a single XML document:

   1: var node = tileXMLWide.importNode(tileXMLSquare.getElementsByTagName("binding")[0], true); 

   2: tileXMLWide.getElementsByTagName("visual").item(0).appendChild(node);

And the tile update is ready to be scheduled

   1: var futureTile = new notifications.ScheduledTileNotification(tileXMLWide, 
                                                       new Date(new Date().getTime() + 10 * 1000)); 

   2: futureTile.id = "Tile1"; 

   3: notifications.TileUpdateManager.createTileUpdaterForApplication().addToSchedule(futureTile);

If we want to add more scheduled notifications we just create them as above and add them to the Schedule with the previous (last) line. Now because we have not specified any "”queue” the next notification will overwrite the current. Therefore the tile’s id, tag does not play an role. If we don’t provide a new notification the current one will remain visible for ever unless we provide an expiration date for the notification. Adding the following line to the notification we have created before adding it to the schedule will make the notification disappear after 10secs from its appearance:

   1: futureTile.expirationTime = new Date(new Date().getTime() + 20 * 1000);

Now for periodic notifications we need to create a basic service (web service) that returns the XML required for updating the tile. The XML to generate is the same as before and taken from the possible templates here. Again we main combine the two tile versions square and wide to support both. An example of possible XML generated from the service is given in this link. So how can you create first of all such a service? One way to go is to use an ASP.NET MVC project. Go ahead and create one. Then erase the Content, Script etc folders. Create a class in the Models folder as follows:

   1: public class TileData

   2: {

   3:     public string Image1 { get; set; }

   4:     public string Image2 { get; set; }

   5:     public string Image3 { get; set; }

   6:     public string Image4 { get; set; }

   7:     public string Image5 { get; set; }

   8:  

   9:     public List<string> Text { get; set; }

  10: }

Then write the following code in the HomeController’s Index action (you basically need to populate with data the model you have created in the Models folder and pass it to the view). In the following example we just populate the model with random values:

   1: public ActionResult Index()

   2: {

   3:     TileData Model = new TileData();

   4:     // Popullate the model with your data here

   5:     return View(Model);

   6: }

Finally your view (for the index action) will be something like the following:

   1: @{

   2:     Layout = null;

   3:     Response.ContentType = "text/xml";

   4: }

   5: @model MetroStylePullNotificationDemo.Models.TileData 

   6: <tile>

   7:     <visual lang="en-US">

   8:         <binding template="TileSquarePeekImageAndText03">

   9:             <image id="1" src="@Model.Image1" />

  10:             @for (int i=0;i<Model.Text.Count;i++)

  11:             {

  12:                 @:<text id="@(i+1)">@Model.Text</text>

  13:             }

  14:         </binding>

  15:         <binding template="TileWideImageCollection">

  16:             <image id="1" src="@Model.Image1" />

  17:             <image id="2" src="@Model.Image2" />

  18:             <image id="3" src="@Model.Image3" />

  19:             <image id="4" src="@Model.Image4" />

  20:             <image id="5" src="@Model.Image5" />

  21:         </binding>

  22:     </visual>

  23: </tile>

You then deploy your service and you are “good to go” server-side. In your metro-style app it is very easy to tell the OS that you need it to query that service to update your tile with the following code:

   1: var recurrence = notifications.PeriodicUpdateRecurrence.halfHour; 

   2: var url = new Windows.Foundation.Uri("http://www.progware.org/windows8/tiles/"); 

   3: notifications.TileUpdateManager.createTileUpdaterForApplication().
                                      startPeriodicUpdate(url, recurrence);

Note that the period is an enumeration and can be of specific values only (30min, 1hour, 6hour, 12hour,24hour) and that is expected since the OS will handle the requests and your app lives in an ecosystem with hundreds of other apps that will compete for the same resources and bandwidth.

No matter the notification type (scheduled or periodic) you can activated the queue for holding the last ones and recycling them in a random order that favors the most recent ones. This is done with a single directive:

   1: notifications.TileUpdateManager.createTileUpdaterForApplication().enableNotificationQueue(true);

Having the queue means that your notification may live more than you want them to or you may need to update an already present notification in the queue. For this reason in this case it is important to tag your notifications by setting their tag property (for scheduled notifications). In periodic notifications this tag is inserted at the response header (see here– the Remarks section). Actually, in the header, we also store the notification’s expiration time.

So this was a brief overview on using tile notifications in metro-style apps with Javascript.We have seen scheduled and periodic notifications. I n the near future there will be a post for push notifications.