Metro doesn't allow you very many ways to interact with the user when your app wants to, so you need to master the few at your disposal - toast popups in particular. Fortunately they aren't difficult and follow the same pattern as the other notifications - badges, and tiles.

This article is Chapter 7 of  Creating JavaScript/HTML5 Metro Applications and follows on from these previous ones: 

• Chapter 1 Getting Started With Metro JavaScript
• Chapter 2 WinControls
• Chapter 3 The App Bar
• Chapter 4 Templates & Data Binding
• Chapter 5 Working with Tiles - Badges
• Chapter 6 Working with Tiles - Notifications
• Chapter 7 Toast Notification
• Chapter 8 Custom Controls
• Chapter 9 Promises
• Chapter 10 Web Workers & Promises
• Chapter 11 Data Binding
• Chapter 12 Life Cycle

Toast Notification

A toast popup, or just toast, is a small window that appears in the upper right (or left for a right-to-left language) of the screen. Unlike badges and tile notifications, a toast can appear on the Start screen, the desktop or another app. 

A toast might look a bit like a dialog box but, while you can include text, images and even a sound, you cannot add buttons or other methods of interacting with the user. A toast is intended to let the user know that something important has happened and acts as an invitation to return to your app. The user can dismiss the toast, ignore it or tap on it to activate it. Activating it causes an event which your app can subscribe to.

To make all of this work and to keep things under control your app has to state that it is going to use toasts and the user can decide to allow or deny your app the right to do so. Apart from this change, the basic pattern of using a toast follows the other notifications:

1. select an XML template
2. use the XML to generate an xmlDocument object
3. customise the xmlDocument object
4. use the xmlDocument object to create a ToastNotification object
5. create a ToastNotififier object and use its show method to display the ToastNotification object

This all sounds easy. So let's try it out with the simplest possible toast.

Note that there is an optional JavaScript object wrapping of most of the notification XML which makes things slightly easier to use. It isn't clear at the moment if this is going to be the standard way to work with notifications so this chapter describes the more fundamental direct XML approach.

A Toast

Start a new blank JavaScript project and open the package.appmanifest file. You can edit the XML in the manifest directly but it is much easier to use the designer to do the job. Simply scroll down on the Application UI page and select Yes for Toast Capable:

If you don't set your application to be Toast Capable then your code will compile perfectly and your app will run but the user will not see any toasts - they are just ignored at runtime.

Following the standard steps we first select a template:

var Notifications = Windows.UI.Notifications;
var template = Notifications.
       ToastTemplateType.toastImageAndText01;

The first line just defines a reference so we don't have to keep repeating the full name. The ToastTemplateType is just and ennumeration that indexes the template collection. toastImageAndText01 is template 0 and so you could use

var template = 0;

but don't as the allocations might change.

Next we can use the template number to retrieve an xmlDocument object based on the XML defining the template:

var toastXml = Notifications.
           ToastNotificationManager.
               getTemplateContent(template);

This can also be written:

var toastXml = Notifications.
           ToastNotificationManager.
                      getTemplateContent(0);

Next we create the ToastNotification based on the xmlDocument object:

var toast = new Notifications.
                 ToastNotification(toastXml);

The notification object can be stored for later use or recreated as and when it is needed.

The final step is to create a toastNotifier object. This can be used to send and manage toasts by sending a ToastNotification object to the toast manager:

var toastNotifier =Notifications.
          ToastNotificationManager.
                       createToastNotifier();

To send the toast you simple use the show method:

toastNotifier.show(toast);

If you put all this together and run the program you will discover that soon after your app appears the toast pops up in the corner of the screen. You will hear a default alert noise and your apps icon graphic is used in the corner of the toast. Default values for the text and image are null.

You can dismiss the toast or just ignore it when it will just fade away. You can control how long the toast will stay on the screen. If the user taps or clicks in the toast then it triggers an event that you can choose to handle. There is a corresponding dismiss event that you can use to take action if the user doesn't want to respond to the toast.

Let's find out how to customize the toast.