Creating a Custom Jump List Category
In the Adding Tasks to a Jump List scenario, you learned how to create a static list of Tasks by using metadata. This scenario shows you how to create a custom Jump List category for your Pinned site.
- Methods Used in this Task
- msSiteModeCreateJumpList(bstrHeader)
- msSiteModeClearJumpList()
- Starting a custom Jump List category
- Clearing the custom Jump List category
- Related topics
Methods Used in this Task
The following methods are introduced in this topic:
msSiteModeCreateJumpList(bstrHeader)
The window.external.msSiteModeCreateJumpList method creates a Jump List category for the Pinned Site's taskbar button. Only one custom category can be created at a time.
msSiteModeClearJumpList()
The window.external.msSiteModeClearJumpList method removes the custom Jump List category and all items that have been associated with it; however, it does not remove items that have been pinned by the user.
Starting a custom Jump List category
When you enter a search term in the TweetFeed sample application, it adds the term to a custom category on the Jump List called "Searches" as shown in the following screen shot.
.png)
Before you can add items to a custom Jump List category, you must create one. Typically, this happens when the page loads for the first time.
window.onload = function()
{
try {
if (window.external.msIsSiteMode()) {
window.external.msSiteModeCreateJumpList("Searches");
// Add items here
}
}
catch (ex) {
// Fail silently.
}
}
This code initially checks that the site was launched from a Pinned site shortcut. (See Detecting a Pinned Site.) Then, it creates a custom Jump List category called "Searches" by calling msSiteModeCreateJumpList. Even though the category is now available, it will not show up on the Jump List menu until you add items to it. You learn to do this in the Adding items to a Jump List Dynamically task.
You do not need to check if the category already exists. If you use the same name each time you create the Jump List, it is not emptied when you create a new one. Most sites create the same custom category again and again. This is not problematic, but be aware that the list does not be clear if you use the same name each time. To ensure that your Jump List is cleared, see the Clearing the custom Jump List category section.
Clearing the custom Jump List category
Sometimes, it is better to start with an empty list. For example, you might want to re-create the custom Jump List category as part of the following tasks:
- Initializing the list with new items as the site loads.
- Changing from default to specific items when the user logs on.
- Allowing the user to select which tasks appear.
- Removing time-sensitive notifications or tasks that rely on application state, when a site is unloaded.
- Clearing the list at the request of the user.
The msSiteModeClearJumpList method deletes the custom Jump List category and all its items. This method does not remove tasks that were defined in the site's metadata, which cannot be removed by script.
Note Clearing a Jump List also deletes information about which items have been removed by the user, and prevents the onmssitemodejumplistitemremoved event from being raised when msSiteModeShowJumpList is called. For more information, see Adding Items to a Jump List Dynamically.
After removing the Jump List category, you must call msSiteModeCreateJumpList again before you add more items. The following script removes the Jump List category and recreates it.
window.onload = function()
{
try {
if (window.external.msIsSiteMode()) {
window.external.msSiteModeCreateJumpList("Searches");
// Add items here
}
}
catch (ex) {
// Fail silently.
}
}
Your site might not need clear the Jump List category. For example, the TweetFeed application could easily keep a long-running history of searches simply by not clearing the Jump List category when the site is launched. For privacy, however, the site should also provide a way to clear the list at the user's request.
Related topics
Tasks
Adding items to a Jump List Dynamically
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