Detecting a Pinned Site

You should prompt the user to pin a site only if site pinning features are detected. This task explains how to correctly detect the Pinned site API and whether a site has already been pinned.

• Methods Used in this Task
  • msIsSiteMode()
• Testing for Site Mode
• Simplifying script with a global variable
• Next Steps
• Related topics

Methods Used in this Task

The following method is introduced in this topic:

msIsSiteMode()

The window.external.msIsSiteMode method returns true if the window was launched as a Pinned site. Otherwise, it returns false.

Testing for Site Mode

When a site has been launched from a pinned shortcut, you can say it is running in site mode. In other words, the site is running in a site-specific browser window, as described in Introduction to Pinned Sites. As your application loads, you might perform additional actions if site mode has been enabled. For example, you might add dynamic tasks to the Jump List, or you might create a Thumbnail Toolbar to control audio or video playback on your site.

The msIsSiteMode method detects whether the current page is part of a Pinned site. If the method returns true, you continue with site initialization. If the method returns false, however, then you know that site mode is supported but not enabled. Finally, if the method throws an exception, you know that the browser version does not support site mode. You can implement this logic as follows:

try {
    if (window.external.msIsSiteMode()) {
        // Site mode is supported and active.
    }
    else {
        // Site mode is supported, but inactive.
    }
}
catch (ex) {
    // Site mode is not supported.
}

In the Prompting Users to Pin your Site task, you learn how to display a prompt only to users of Windows Internet Explorer 9. You should not display the prompt if the site was already been launched in site mode. The following code detects site mode and displays an on-screen prompt when appropriate.

window.onload = function()
{
    try {
        if (window.external.msIsSiteMode()) {
            // Continue initialization.
        }
        else {
            // Display prompt.
            document.getElementById('divPinSite').style.display = "block";
        }
    }
    catch (ex) {
        // Fail silently.
    }
}

The result is as follows:

• The prompt appears only in Internet Explorer 9. The prompt remains hidden otherwise.
• The prompt remains hidden in site mode. Using the msIsSiteMode method, the browser can detect whether the site was launched from a Pinned site shortcut.

Note  Before you call other Pinned site methods, first determine if site mode is enabled with the msIsSiteMode method.

Simplifying script with a global variable

Note  This optimization is entirely optional.

Although the code to detect site mode is only one line long, repeated calls to the msIsSiteMode method can impact the size and complexity of your script. Rather than checking for site mode each time you call a Pinned site API, you can save a global flag during initialization to use elsewhere. You can reduce the size of your code even further if you save a reference to window.external in the global variable, as shown in the following example:

var g_ext = null;        // Global variable.

window.onload = function()
{
    try {
        if (window.external.msIsSiteMode()) {
            g_ext = window.external;
            // Continue initialization.
        }
    }
    catch (ex) {
        // Fail silently.
    }
}

Then, later code need only verify the value of the global to detect a Pinned site, for example:

if (g_ext) {
    g_ext.msSiteModeAddJumpListItem("Task3", "task3.html", "img/icon.ico");
    g_ext.msSiteModeShowJumpList();
}

Next Steps

You have completed this scenario. To learn more about Pinned sites, choose one of the following:

• TweetFeed Sample: Search History—Create a custom Jump List category, and add items to it dynamically.
• TweetFeed Sample: Notifications—Use icon overlays to notify your users of a status change.
• Channel9 Podcast Player Sample: Remote Control—Implement a Thumbnail Toolbar to control audio playback.

Related topics

Tasks

Prompting Users to Pin your Site

Conceptual

Badge Notifications, directly on your Windows 8 Pinned Site

Fresh Tweets 2.0 - demo for Windows 8

High Quality Visuals for Pinned Sites in Windows 8

How to Create a Basic Pinned Site

Introduction to Pinned Sites

Pinned Sites in Windows 8

Windows User Experience Interaction Guidelines: Icons