Adding items to a Jump List dynamically

Article
03/03/2016

In the Creating a Custom Jump List Category task, you learned how to create and show a custom Jump List category. In this task, you add items to the Jump List dynamically.

Note The custom Jump List category is primarily designed for tasks that change over time. Predefined tasks that do not change frequently can be created when the Pinned site shortcut is installed. For more information, see Adding Tasks to a Jump List.

Methods Used in this Task
- msSiteModeAddJumpListItem(bstrName, bstrActionUri, bstrIconUri [, bstrWindowType])
- msSiteModeShowJumpList()
Adding items to a Jump List
Updating Jump List items on demand
Clearing the Jump List, revisited
Putting It All Together
Next Steps
More Examples
- Amazon.com
- HuffingtonPost.com
Related topics

Methods Used in this Task

The following methods are introduced in this topic:

msSiteModeAddJumpListItem(bstrName, bstrActionUri, bstrIconUri [, bstrWindowType])

The window.external.msSiteModeAddJumpListItem method dynamically adds items to the custom Jump List category.

msSiteModeShowJumpList()

The window.external.msSiteModeShowJumpList method refreshes the visible items in the custom Jump List.

Adding items to a Jump List

For a developer, creating custom Jump List categories can provide quick access to commonly used destinations on your sites. By using these custom categories, a user can easily return to previously viewed pages (history), access user-specific information (such as radio stations), or keep track of site interactions (for example, a shopping list). When a user selects a custom item from the Jump List, the Pinned site window navigates directly to that item. By default, custom items open in a new tab; however, you can use the bstrWindowType parameter to open the link in the current tab by specifying self, or in a new Pinned site window by specifying window.

Before you can add Jump List items, you must create a custom Jump List category. For more information, see Creating a Custom Jump List Category. After you have created the category list, you add items to it by calling the msSiteModeAddJumpListItem method. Items are added at the top of the list, in the reverse order from how they appear in script.

The next example saves two tasks in a custom "My Site" category list immediately after the page is loaded, in response to the onload event. Notice how Task2 is defined before Task1 so that they appear in the correct order on the Jump List.

var g_ext = null;
window.onload = function()
{
    try {
        if (window.external.msIsSiteMode()) {
            g_ext = window.external;
            g_ext.msSiteModeCreateJumpList("My Site");
            g_ext.msSiteModeAddJumpListItem(
                "Task2", "/users/44324847/task2", "img/icon.ico");
            g_ext.msSiteModeAddJumpListItem(
                "Task1", "/users/44324847/task1", "img/icon.ico");
        }
    }
    catch (ex) {
        // Fail silently.
    }
}

Items on a Jump List remain visible even after you close a Pinned site. Just like site Tasks that you define with metadata, dynamic items can also act as shortcuts into your website. However, if the dynamic items depend on application state, they will not be valid after the site is closed. Links in a Jump List should contain enough information to navigate without application state, if necessary.

Note A custom Jump List category should provide a dynamic set of destinations that are specific to the current user, but independent of the application state or current webpage. Make sure items in your Jump List fit the intention of your website, address customer needs, and include enough detail to be helpful.

Although a custom Jump List category can contain up to 20 items, only the last 10 items in the list are visible by default. The taskbar ultimately controls the number of Jump List items you are able to see.

To change the default settings of the taskbar

Right-click the Start menu and click Properties.
On the Start Menu tab, click the Customize button to open the Customize Start Menu dialog box.
Change the Number of recent items to display in Jump Lists option to a number that fits your needs.
Click OK to close the dialog box.

Updating Jump List items on demand

In the previous section, you updated a custom Jump List category during the onload event. The Pinned site API is designed to accept changes to the Jump List at this point; however, subsequent changes to the Jump List do not appear automatically. For example, if you add items to the Jump List after the page has loaded due to user activity or site configuration, you must call the msSiteModeShowJumpList method to write those changes to the Jump List.

The following script runs in response to a button click. The code has been simplified by using the global variable set in the code example from the preceding section.

function buttonClick()
{
    if (g_ext) {
        // Optionally, remove and re-create category.
        g_ext.msSiteModeClearJumpList();
        g_ext.msSiteModeCreateJumpList("My Site");

        // Add items to the Jump List here.
        g_ext.msSiteModeAddJumpListItem(
            "Task4", "/users/44324847/task4", "img/icon.ico");
        g_ext.msSiteModeAddJumpListItem(
            "Task3", "/users/44324847/task3", "img/icon.ico");

        // Show updates to the Jump List.
        g_ext.msSiteModeShowJumplist();
    }
}

Clearing the Jump List, revisited

If any item being added by script matches the name and URL of an item that has been removed by the user, that item is not added to the list. However, clearing the list also clears any information about which items have been removed by the user, and allows the site to re-create items that have been removed.

Note In addition to updating the Jump List, the msSiteModeShowJumpList method raises the the onmssitemodejumplistitemremoved event once for each item that has been removed by the user since the last time the msSiteModeShowJumpList method was called. This event is not raised if you call msSiteModeClearJumpList.

Clearing the list is optional, and should be avoided if you want to honor your users' choices.

Putting It All Together

The TweetFeed sample application creates a custom Jump List category to contain previous search results. When the user clicks the links, the site issues the search again. To do this, the links must contain enough information to repeat the search, even if the site is not running. The following example code shows how to do this.

tweetQuery = document.getElementById("txtSearch").value;
if (tweetQuery.length > maxTweetSize) {
    tweetQuery = tweetQuery.substr(0, maxTweetSize);
}

try {
    if (window.external.msIsSiteMode()) {
        var itemURL = "http://" + window.location.host 
                       + window.location.pathname 
                       + "?tweet=" + escape(tweetQuery);
        window.external.msSiteModeAddJumpListItem(
                       tweetQuery, itemURL, 
                       "http://twitter.com/favicon.ico");
        window.external.msSiteModeShowJumplist();
    }
}
catch (e) {
    // Fail silently.
}

The code example performs the following steps.

First, it reads the query from a form field.
Next, it constructs a URL that can be used to repeat the search query.
Finally, the URL is added to the Jump List by calling the msSiteModeAddJumpListItem method, and update the list by calling the msSiteModeShowJumpList method.

Next Steps

You have completed this scenario. To learn how the TweetFeed sample application uses icon overlays to visually represent site activity on the taskbar button, continue with the TweetFeed Sample: Notifications scenario.

More Examples

This section shows how some popular websites in the United States that have used a custom Jump List category to enhance their user experience in Windows Internet Explorer 9.

Amazon.com

Amazon.com does a good job of separating tasks (verbs) from destinations (nouns). Because the custom Jump List category is created while the page is loading, the msSiteModeShowJumpList method is not required. Notice how items are added in the reverse order of how they appear in the Jump List.

<script type='text/javascript'>
try {
window.external.msSiteModeCreateJumplist('Amazon Favorites');
window.external.msSiteModeAddJumpListItem 
    ('Amazon Wish List' , 
     'http://www.amazon.com/wishlist?tag=amzn-ie9-jl-wl-20',
     'http://www.amazon.com/favicon.ico');
window.external.msSiteModeAddJumpListItem 
    ('Amazon Prime' ,
     'http://www.amazon.com/gp/prime?tag=amzn-ie9-jl-prm-20',
     'http://www.amazon.com/favicon.ico');
// ...

} catch (ex) {
}
</script>