Customizing the Toast

Customizing a toast follows the same lines as customizing a badge or a tile template. You simply have to use the methods provided by the xmlDocument object to customize the XML To do this correctly you need to know the structure of the template. You can find this is in the documenation and the template we have been using is defined as:

<toast>
 <visual>
  <binding template="ToastImageAndText01">
   <image id="1" src="/image1" alt="image1"/>
   <text id="1">bodyText</text>
  </binding>
 </visual>
</toast>

We need to set an image src for the image tag and some text for the text tag. All of the discussions on how best to do this for the badge and tile template carry over here and if you want to know about them in detail read the ealier chapters.

To set a simple text message and an image stored on the web you would use something like:

var text1Node = toastXml.
              getElementsByTagName("text")[0];
text1Node.innerText = "The toast is ready";    var ImageNode = toastXml.
             getElementsByTagName("image")[0];
ImageNode.attributes.
     getNamedItem("src").nodeValue = 
                 "http://awebsite.com/IP.jpg";

You can specify text in a resource file and the images can be local to the project or stored in a resource file.

If you run the program with the customized XML template you will see a toast with text and image:

You can also set the toast tag's duration attribute to determine how long the toast will display - "long" or "short". For example to set a long display time:

toastXml.getElementsByTagName("toast")[0].
             setAttribute("duration", "long");

A long duration toast stays on the screen for 25s compared to a short duration which stays for 7 seconds.

You can use the toastNotifier's Setting property to determine if the app is allowed to send toasts at the moment.

Using XML

An alternative to customizing the xmlDocument object after it has been constructed is to customize XML as text and use this to generate an xmlDocument object. This works in exactly the same way as for the badge and live tile examples. For example to create the same toast as above you would use:

var toastXml = new Windows.
      Data.Xml.Dom.XmlDocument();
toastXml.loadXml('
 <toast>
  <visual>
   <binding template="ToastImageAndText01">
    <image id="1" src="http:website/IP.jpg"
      alt="image1"/>
    <text id="1">The toast is ready</text>
   </binding></visual></toast>');
var toast = new Notifications.
                  ToastNotification(toastXml);
var toastNotifier =Notifications.
 ToastNotificationManager.
                        createToastNotifier();
toastNotifier.show(toast);

Note: the XML string is formatted in the listing to make it easier to read. In the program it would be entered without returns or formatting.

This produces the same toast without the need to use a template or work with the xmlDocument object.

You can, of course include any customization you want within the XML - an audio tag, other attributes etc. - but you cannot invent a completely new XML template.

Toast Audio

One of the main differences between other notifications and  toast is that you can specify a sound for the event. You can't specify any sound just select from the supplied set:

• ms-winsoundevent:Notification.Default
• ms-winsoundevent:Notification.IM
• ms-winsoundevent:Notification.Mail
• ms-winsoundevent:Notification.Reminder
• ms-winsoundevent:Notification.SMS
• ms-winsoundevent:Notification.Looping.Alarm
• ms-winsoundevent:Notification.Looping.Alarm2
• ms-winsoundevent:Notification.Looping.Call
• ms-winsoundevent:Notification.Looping.Call2

There are also some additional attributes that you can set to determine how the sound is treated:

loop -  true if the sound is to repeat while the toast is displayes

silence - true if sound is muted.

The only complication is that that the audio tag doesn't exist in the template so you have to create it, add a src attribute and then add it to the toast template.

For example, first we create the audio node:

var toastAudioElement = toastXml.
                       createElement("audio");

Next we customize the src element:

toastAudioElement.setAttribute("src",
       "ms-winsoundevent:Notification.Alarm");

Finally we add the audio element to the toast:

toastXml.getElementsByTagName("toast"[0].
               appendChild(toastAudioElement);

Now if you run the program you will hear an alarm tone in place of the default.

You can customize the other attributes in exactly the same way.

You can also simply write the XML complete with the audio tag and use it to create an xmlDocument object in the usual way.