IE Pinned Sites Part 5: How to implement dynamic Jump List Categories

Article
04/27/2011

Remember how in an earlier post, I mentioned that there were two parts to the msSiteMode API to integrate pinned sites with the Windows 7 taskbar: some things were implemented in HTML and would apply to anyone visiting the website, and some things were implemented in JavaScript and were dynamic or specific to an individual user visiting the website.

Well, we’ve covered basic site properties and Jump List tasks which were both implemented in HTML and applied to everyone, and now we’re transitioning to the information that is dynamic in nature or specific to an individual user, which includes:

Jump List Categories
Overlay Icons
Thumbnail Toolbar Buttons
Flashing Taskbar Button

In today’s post, we’ll tackle Jump List Categories. Jump List categories are similar to Jump List tasks, except with categories, you can define your own heading (or category) for the items in the Jump List. They can be used to surface information specific to a user, notifications, or the user’s history. For example, on an eCommerce site, as the user clicks around looking at various products which they are considering purchasing, the site could build up a “Recently Viewed” category in the Jump List and include perhaps the last 5 items viewed on the site.

Let’s look at a real-world example of a popular site using Jump List categories. One such site is Amazon. If you pin the Amazon website and right-click on the Taskbar icon, you will see a Jump List like this:

Now, you will notice that the Amazon pinned site Jump List not only has common tasks (like “Check Order Status” and “Manage Your Account”) in the Tasks list, but it also has a custom Jump List category called “Amazon Favorites”. This category contains some favorite destinations on the Amazon website, such as “Gold Box Deals” and “Amazon Wish List”.

Now, let’s look at how to code a Jump List category. First, we need to create a new Jump List category. To do that, use the msSiteModeCreateJumpList method in JavaScript. It takes a single parameter, which is the name of the Jump List category that will be displayed to the user.

 window.external.msSiteModeCreateJumplist('Resources');

Next, we need to create items in this Jump List category. This is done by the msSiteModeAddJumpListItem method. This method has 3 required parameters, which are the same trifecta as when we were putting items in our Jump List tasks:

name – This is the name of the Jump List item which is displayed to the user in the Jump List.
action-uri – This URI is the destination that the user will be taken to when the Jump List item is clicked.
icon-uri – This URI is a pointer to an icon (*.ico file) that will be displayed to the left of the item name in the Jump List.

You will probably want to add multiple items to your Jump List category, but I’m just showing one for now:

 window.external.msSiteModeAddJumpListItem('Twitter', 
    'https://www.twitter.com/windevbootcamp', 
    'https://a3.twimg.com/a/1294164987/images/iefavicon.ico');

Next, we have to call msSiteModeShowJumpList to display the Jump List with our new items.

 window.external.msSiteModeShowJumplist();

Finally, if you ever want to remove your custom Jump List, you can do this by calling the msSiteModeClearJumpList method.

 window.external.msSiteModeClearJumplist();

Putting it all together, our JavaScript might look like this:

 // Jump list categories
if (window.external.msIsSiteMode()) {
    window.external.msSiteModeCreateJumplist('Resources');
    window.external.msSiteModeAddJumpListItem('Jennifer Blog', 'https://blogs.msdn.com/jennifer', 'https://windowsdevbootcamp.com/favicon.ico');
    window.external.msSiteModeAddJumpListItem('Twitter', 'https://www.twitter.com/windevbootcamp', 'https://a3.twimg.com/a/1294164987/images/iefavicon.ico');
    window.external.msSiteModeAddJumpListItem('Silverlight 4', 'https://bit.ly/dvR7Hb', 'https://windowsdevbootcamp.com/favicon.ico');
    window.external.msSiteModeAddJumpListItem('Internet Explorer 9', 'https://bit.ly/b9HBZu', 'https://windowsdevbootcamp.com/favicon.ico');
    window.external.msSiteModeAddJumpListItem('Windows 7 Training Kit for Developers', 'https://bit.ly/cXaJ1u', 'https://windowsdevbootcamp.com/favicon.ico');
    window.external.msSiteModeAddJumpListItem('Windows API Code Pack', 'https://bit.ly/bGKULt', 'https://windowsdevbootcamp.com/favicon.ico');
    window.external.msSiteModeShowJumplist();
    //window.external.msSiteModeClearJumplist();
}

The first if statement checks to see if the current page was launched as a pinned site using the msIsSiteMode method. (If the page is just running within the browser and isn’t pinned, none of this functionality will be exposed anyway.) In a future blog post, I’ll also detail some patterns for making your code run well in all browsers.

In the code, I create a Jump List category called “Resources”. Then I add 6 Jump List items under that category. Finally, I show the Jump List. (In my scenario, I don’t ever need to clear the Jump List.)

This code is used for the Windows Development Boot Camp site, to give a number of resources that are useful for that training. If you pin that site, you will see a Jump List like the one below. Note that the ordering is interesting. In the code above, the first item that I added to the Jump List was my blog, and that item becomes the bottom item on the Jump List when it is displayed. So when new Jump List items are added, they are added to the top of the list and previous entries are pushed down the list.

Now, although I was using dynamic Jump List categories, my “Resources” scenario above wasn’t really that dynamic. I’m essentially adding more static resources to the pinned site in a dynamic way. So, let me give you a quick example of something that is truly dynamic. Let’s keep track of which pages on the Windows Development Boot Camp site that the user has visited in a dynamic Jump List (the “Recently Viewed” scenario that I mentioned above, although it makes less sense here since this isn’t an eCommerce site).

I will need some JavaScript like this:

 <script type="text/javascript">
    // Jump list categories - more dynamic example
    function AddToJumpList() {
        if (window.external.msIsSiteMode()) {
            window.external.msSiteModeCreateJumplist('History');
            var itemURL = "https://" + window.location.host + window.location.pathname;
            var title = window.location.pathname.replace('/','');
            window.external.msSiteModeAddJumpListItem(title, itemURL, 
                "https://windowsdevbootcamp.com/favicon.ico");
            window.external.msSiteModeShowJumplist();
        }
    } 
</script>

I’ll also need to modify my menu items along the top to call this function when they are clicked (so that the page that we’re leaving can be added to the history):

 <div id="menu">
    <ul>
        <li><a href="Default.aspx" onclick="AddToJumpList();">Home</a></li>
        <li><a href="Location.aspx" onclick="AddToJumpList();">Locations</a></li>
        <li><a href="WhatToBring.aspx" onclick="AddToJumpList();">What to Bring</a></li>
        <li><a href="Agenda.aspx" onclick="AddToJumpList();">Agenda</a></li>
        <li><a href="Resources.aspx" onclick="AddToJumpList();">Resources</a></li>
        <li><a href="Trainers.aspx" onclick="AddToJumpList();">Trainers</a></li>
    </ul>
</div>

Now, as I click from one page to another, the recently viewed pages are added to a custom Jump List category called “History”. If I click on one of these items, it will take me back to the corresponding page in the website.

One final and very important gotcha about Jump List Categories: you can only have one custom category in your Jump List (in addition to the Tasks). If you call msSiteModeCreateJumpList with a different category name, it will replace your current Jump List category. You are also allowed a maximum of 20 items in your custom Jump List. Now, that is somewhat misleading, because the Windows 7 operating system has a default value of displaying 10 items maximum. So, for your users to see all 20 items, they would have to:

Right-click on the Taskbar and select “Properties”.
Click the “Start Menu” tab.
Click the “Customize…” button.
At the bottom, find the field for “Number of recent items to display in Jump Lists” and change the value from 10 to 20.

Therefore, it’s my personal opinion that although you can have 20 items max in a custom Jump List category, you should just consider 10 to be your maximum since most of your users are not going to change the default settings in Windows.

In tomorrow’s blog post, we’ll investigate overlay icons in pinned sites.

Other Blog Posts in this Series

IE Pinned Sites Part 1: What Are Pinned Sites?

IE Pinned Sites Part 2: Why Implement Pinned Sites?

IE Pinned Sites Part 3: How to implement basic site properties

IE Pinned Sites Part 4: How to implement Jump List Tasks

IE Pinned Sites Part 5: How to implement dynamic Jump List Categories

IE Pinned Sites Part 6: How to implement Overlay Icons

IE Pinned Sites Part 7: How to implement Thumbnail Toolbar Buttons

IE Pinned Sites Part 8: How to implement a Flashing Taskbar Button

IE Pinned Sites Part 9: Patterns to make your pinned site code play nice in all browsers

IE Pinned Sites Part 10: Pinned Site Resources

IE Pinned Sites Part 5: How to implement dynamic Jump List Categories

Additional resources