Defining a Jump List Category and Adding Items to ItJump List categories are a great mechanism for your websites to surface dynamic information to end-users. Items can be added to the custom category from any webpage on the same domain. Jump List items within a custom category are visually separated from Jump List tasks and can be individually persisted or deleted by users. When a user clicks a Jump List item from a pinned site, the pinned site window displays that item in a separate tab on the same browser instance as the pinned site. Jump List items in a category list are not the way to send commands back to your application and avoid navigation, however. They are destinations intended to navigate a user to a URI.
Use Jump List categories to give users access to contextual information in the form of destinations or actions. Destinations can be used to access files, documents, or URLs. The items in the categories represent URLs with user-specific context. These might include a profile page on a social networking site or a radio station on a music streaming site. Users access the resources directly by clicking on the item links. Actions can include visiting sites, viewing history, and more. Your website can also use a custom category to notify users of interactions or alerts that are happening on the backend—new received email, friend online, upcoming appointment. Another advantage of custom categories is that they are persisted in the Jump List after the browser instance is closed. This provides users with a contextual mechanism for accessing site information when the browser is not running.
The following screen shot shows how Microsoft Office Outlook Web Access uses a custom category,
Notifications, to display an upcoming appointment,
scrum. When the user clicks
scrum, IE opens a new tab on the same browser instance as the pinned site and displays the appointment information.
Figure 8: A custom notification in Outlook Web AccessManaging a custom category is divided into several stages:
1.
Create the Category — First, call the
msSiteModeCreateJumplist method to create a custom category with a label. The following code example creates a custom category named List1. You must call
msSiteModeCreateJumplist at least once before using any of the other methods in these steps.
window.external.msSiteModeCreateJumplist('List1') ;
Note: [/i]that the category label is not visible until the category is populated with at least one item. Creating a second category replaces an existing one[/i].
2.
Create Items — Add items to the in-memory list (note that the items are not yet displayed). The following code example uses the
msSiteModeAddJumpListItem method to create three list items:
Item 1,
Item 2, and
Item 3. The first parameter specifies the item name. The second parameter specifies the URL to use when the item is selected. The third parameter specifies the icon that to use when displaying the item on the list.
window.external.msSiteModeAddJumpListItem('Item 1', 'http://host/Item1.html ', 'http://host/images/item1.ico') ;
window.external.msSiteModeAddJumpListItem('Item 2 ', 'http://host/Item2.html ', '
http://host/images/item2.ico')[/i] ;
window.external.msSiteModeAddJumpListItem('Item 3 ', 'Item3.html', 'images/item3.ico') ;
3.
Display the List — Display the in-memory list for the Jump List. After you call the
msSiteModeAddJumpListItem method, Windows immediately updates the in-memory list in the Jump List.
window.external.msSiteModeShowJumplist() ;
4.
Clear the List — Clear the items on the custom list. When you call the
msSiteModeClearJumplist method, Windows immediately removes the items from the Jump List.
window.external.msSiteModeClearJumplist() ;
The pinned site APIs display a maximum of 20 items at any one time in a custom category. If you add more than twenty items to a category, the previously added items are deleted. The pinned site APIs will not duplicate an existing entry; however, the duplicate entry will be moved to the top of the list. In some cases, the system may reduce the maximum number of items displayed. This is based on various factors such as user choice, display resolution, and font size. If there isn't space enough for all items in all categories, the items are truncated from the bottom up.
Websites are responsible for maintaining the state of the category and for adding and removing items to and from the category. In addition, your website can register for an event that is triggered when a user removes an item from a custom category by using one of the following event listeners:
document.addEventListener( ' mssitemodejumplistitemremoved ', removed, false) ;
document.attachEvent( ' onmssitemodejumplistitemremoved', removed)[/i] ;
The listener generates a callback to a delegate with a URL parameter:
function removed(url) { … }When a user removes an item from the Jump List, Windows cannot capture or pass back a shell event to the site. Thus, the event is artificially generated by the IE instance running the pinned site after the user adds a Jump List item and the website calls the
msSiteModeShowJumplist method. However, the event is generated only if there are items that were deleted by the user prior to the site inserting them back. This creates a mismatch between the in-memory representation of the Jump List and the actual set of items in the Jump List. The pinned site APIs synchronize the in-memory Jump List representation and the actual Jump List items after the event is triggered.
Any page on the same domain can modify information on the Jump List category by using the JavaScript APIs.
source:msdn.microsoft.com
