Jump Lists for your Site(Or Blogs) I

Windows 7 Taskbar Basics

The following graphic shows the taskbar elements in Windows 7.

Feature	Description
Taskbar button	When you click a Pinned Site button on the taskbar, the website launches in a new browser window that has been customized specifically for the site. The site icon is visible on the taskbar button.
Overlay icons	A 16x16 pixel notification icon that appears on top of the normal site icon. This notification indicates that something has changed in the website, such as new mail arriving, receiving a chat request, or being outbid in an auction. The notification is visible only when the site is running.
Jump List	The Jump List can contain static and dynamic tasks that act as shortcuts into the Pinned Site. A user can further customize their experience by pinning these items to the Jump List.
Jump List category	A Pinned Site can create and fill a single custom Jump List category by using script in the webpage. This list is dynamic.
Jump List tasks	In addition to the Jump List category, a Pinned Site can predefine a list of tasks in metadata. This list is static.
Thumbnail toolbar	A Pinned Site can create up to seven buttons that appear on the taskbar thumbnail window. These buttons can be visible or hidden, active or inactive, or toggle between different button states.

At the very least, Pinned Sites should define a list of tasks for the most frequently used features of the website. Beyond that, site developers can create a custom Jump List category for additional tasks and user-specific destinations. More advanced sites can provide icon overlays to notify you about the status of a website, such as the number of new messages in your Inbox. Finally, some sites might also benefit from remote controls on the thumbnail toolbar.

The Pinned Site API

You implement Pinned Site functionality by using the following two programming models:Static site properties. The first group defines properties that apply to anyone who uses the Pinned Site. This basic functionality is defined by meta elements.

- Application name
- Desktop tooltips
- Site start URL
- Window size
- Back and Forward button colors
- Static Jump List tasks

Customizing a website launched from a pinned site

You use meta elements to customize the way the pinned site renders after it is launched from a pinned site location, by using the following syntax:

<meta name="name" content="content"/>

The values for name and content are described in the following table:

Name	Content
application-name	The name of the shortcut. If missing, the document title is used instead.
msapplication-tooltip	Optional text that is displayed as a tooltip when the mouse pointer hovers over the pinned site shortcut icon in the Windows Start menu or desktop.
msapplication-starturl	The root URL of the application. If missing, the address of the current page is used instead. Only HTTP, HTTPS, or FTP protocols are allowed.
msapplication-navbutton-color	The color of the Back and Forward buttons in the pinned site browser window. Any named color, or hex color value as defined by Cascading Style Sheets (CSS), Level 3 (CSS3) is valid. For more information, see Color Table. If this meta element is absent, the color is based on the shortcut icon.
msapplication-window	The initial size of the pinned site browser window. Content sub-elements provide size as number N, separated by a semicolon. width=N (minimum 800) height=N (minimum 600) Note that user action overwrites this value. Windows preserves the user- generated window size when the user changes the size of the window and then closes the instance.

The following code example uses meta elements to customize the pinned site shortcut with a tooltip, start URL, initial window size, and navigation button color.




<meta name="application-name" content="Sample Site Mode Application"/>

<meta name="msapplication-tooltip" content="Start the page in Site Mode"/>

<meta name="msapplication-starturl" content="http://example.com/start.html"/>
<meta name="msapplication-window" content="width=800;height=600"/>


<meta name="msapplication-navbutton-color" content="red"/
>

You can also specify the favicon to use by following existing webpage syntax:




<LINK rel="shortcut icon" type=image/x-icon href="http://host/favicon.ico">
<LINK rel=icon type=image/ico href="./favicon.ico">

Windows attempts to retrieve a 32x32 version of the favicon from the specified file. If that size cannot be found, Windows frames the 16x16 version of the favicon inside a 32x32 document image. If no favicon is specified, Windows uses a framed version of the Internet Explorer icon. The favicon icon can also be overwritten by the user through the property settings dialog box.

Defining Jump List Tasks

Jump List tasks are application-specific actions that are tailored to a website. By using Jump List tasks, your website can surface the most frequently used commands to users. You should define the Jump List tasks based on both the website's features and the key actions a user is expected to undertake with them. The tasks provide a set of static URIs that users can access at any time, even if the browser instance is not running. Furthermore, these tasks provide a mechanism for your website to promote their most common destinations to users even when the user is not visiting your site. For instance, a web-based communication application could surface commands enabling users to quickly access their contacts, inbox, and profile information.

Figure 7: Jump List tasks associated with a communication site

All Jump List tasks are directly accessed by using a static URL path that is stored inside the .website file. Tasks are not expected to change frequently; however, they can be updated by modifying the meta elements on the webpage. Changes take effect the next time the user launches the pinned site, rather than when they are initially loaded by the browser.

You define Jump List tasks by using HTML meta tags. When accessing a pinned website, Windows caches and applies these tags during installation. URLs defined in tasks are not restricted to a domain. The following code example defines two Jump List tasks on a webpage: Task 1 and Task 2. When the user clicks Task 1, the pinned site window launches Page1.html. Similarly, when the user clicks Task 2, the pinned site window launches Page2.html on the microsoft.com domain.




<META name="msapplication-task" content="name=Task 1;action-uri=http://host/Page1.html;icon-uri=http://host/icon1.ico"/>

<META name="msapplication-task" content="name=Task 2;action-uri=http://microsoft.com/Page2.html;icon-uri=http://host/icon2.ico"/>

The pinned site window opens all tasks inside their own tab in the current pinned site window. If no browser instance exists, a new one is created. A website can define a maximum number of five tasks. Relative URLs on the action-uri field are resolved during install by using the URI of the page that contains the meta information.

Meta elements representing tasks can be updated by sites at any time. Changes to the Jump List tasks will be reflected the next time the site is launched.

Defining a Jump List Category and Adding Items to It

Jump 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 Access

Managing a custom category is divided into several stages:

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 callmsSiteModeCreateJumplist at least once before using any of the other methods in these steps.
```
window.external.msSiteModeCreateJumplist('List1');
```
Note 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.
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');


window.external.msSiteModeAddJumpListItem('Item 3', 'Item3.html', 'images/item3.ico')
;
```
Display the List — Display the in-memory list for the Jump List. After you call the msSiteModeShowJumplist method, Windows immediately updates the in-memory list in the Jump List.
```
window.external.msSiteModeShowJumplist();
```
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);

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.

Displaying Overlay Icons

Windows applications can communicate notifications and status to users by displaying an overlay icon on top of the application’s taskbar button. The msSiteModeSetIconOverlay method adds an icon overlay to the pinned site’s taskbar button. Overlay icons help draw attention to a website when the view to the pinned site’s window is blocked, as when the browser window is minimized or blocked by another window. Use overlay icons to supply important, long-standing status or notifications such as network status, online status, or new mail. Remember that presenting users with constantly changing overlays or animations creates a negative user experience.

Windows displays overlay icons in the lower-right corner of the taskbar button; however, the taskbar must be in the default large icon mode to display overlay icons. Overlay icons are not visible when the website is not running or when the website is not running as a pinned site. Overlay icons can be displayed from any webpage in the same domain. In addition, a website can apply multiple overlay icons without having to clear them first. However, when an overlay icon is cleared, Windows removes the icons starting from the most recently added. This implies that the clearing order is such that the last icon displayed is the first one removed.

The following screen shot shows how Outlook Web Access uses the overlay icon of a bell to notify the user that it is time for an appointment.

Figure 9: An overlay icon in Outlook Web Access

The following code example uses the msSiteModeSetIconOverlay method to add an overlay icon, overlay1.ico, on the taskbar button and provide a tooltip with the string “Overlay 1”.




window.external.msSiteModeSetIconOverlay('http://host/images/overlay1.ico', 'Overlay 1');

Remove the overlay icon by calling the msSiteModeClearIconOverlay method.

window.external.msSiteModeClearIconOverlay();

Displaying Thumbnail Toolbar Buttons on the Thumbnail Preview

For native Windows applications, users interact with thumbnail toolbar buttons in the taskbar without having to restore or activate the site's window. A pinned site can make use of the same functionality for individual webpages. Each button represents a command that can be executed in the webpage, so users can interact with the webpage while in a minimized state or without activating it. The following screen shot shows how a webpage with multiple video clips uses thumbnail toolbar buttons to control the play, pause, and selection of videos without causing the user to access the page directly.

Figure 10: Thumbnail toolbar buttons to control video

You can display a maximum of seven buttons in a thumbnail toolbar. Because there is a limited amount of space in which to display thumbnails, as well as a constantly changing number of thumbnails to display, applications are not guaranteed a specific toolbar size. If display space is low, buttons in the toolbar are truncated from right to left as needed. Therefore, an application should prioritize the commands associated with its buttons to ensure that those of highest priority are to the left and are therefore least likely to be truncated.

When a user clicks a thumbnail toolbar button, an event with a specific ID is returned to the webpage for processing. These events are scoped to the domain that created the events. Buttons can be created, displayed, hidden, enabled, or disabled, or their image can be replaced.

Thumbnail toolbar buttons are defined in memory before they are displayed. The following code example uses the msSiteModeAddThumbBarButton method to create three thumbnail toolbar buttons, passing in the URL of an icon resource file in the first parameter and the (optional) tooltip in the second parameter. The method returns an ID that is used by the system when a thumbnail toolbar button click event is generated.


btn1 = window.external.msSiteModeAddThumbBarButton( 'http://host/images/button1.ico', 'button 1');
btn2 = window.external.msSiteModeAddThumbBarButton( 'http://host/images/button2.ico', 'button 2');


btn1 = window.external.msSiteModeAddThumbBarButton( 'http://host/images/button3.ico', 'button 3')
;

You capture events generated when the user clicks a thumbnail toolbar button by subscribing to the msthumbnailclick event with an event handler. The following code example registers an event handler, handler1, to process all events generated by the thumbnail toolbar buttons.


document.addEventListener('msthumbnailclick', handler1, false);
…
function handler1 (btn) {

t:thumbnail btn id" + btn.buttonID);
}
alert ("addeventli

s

After being defined, you can instantiate a button only once, by using the msSiteModeShowThumbBar method.

window.external.msSiteModeShowThumbBar();

Use the msSiteModeUpdateThumbBarButton method to set the state and visibility of a button after the button has been instantiated. The following code example makes button1 disabled and visible, button2 enabled and visible, and button3 enabled but not visible.


window.external.msSiteModeUpdateThumbBarButton(btn1, false, true);
window.external.msSiteModeUpdateThumbBarButton(btn2, true, true);


window.external.msSiteModeUpdateThumbBarButton(btn3, true, false)
;

Changes to the button state take place immediately; however, changes to the button visibility take place only after the thumbnail preview window is refreshed.

You can define and implement alternate styles to dynamically replace button information already displayed in the thumbnail toolbar. First, define a new style. Use the msSiteModeAddButtonStyle method to define an alternate icon image and tooltip for the specified button. Each style contains a replacement image and a new tooltip value. The following code example defines style1 for btn1 using a new image and tooltip.

style1 = window.external.msSiteModeAddButtonStyle(btn1, 'http://host/images/style1.ico', 'style1');

Then, apply defined styles to the already displayed buttons by using the msSiteModeAddButtonStyle method. The following code example applies the previously defined style1 to btn1.

window.external.msSiteModeShowButtonStyle(btn1, style1);

Your site should hide thumbnail toolbar buttons when a user exits the website’s domain or navigates away to other pages. Similarly, sites should re-instantiate these buttons and make them visible when a user returns to the page.

When re-instantiating these buttons a site should not call the msSiteModeShowThumbBar method on the same instance as an exception will be triggered. At a minimum the method should be called with a try/catch block around it to ensure the buttons continue to work once they are reinitialized and made visible again. To support this scenario, you can call the msSiteModeAddThumbBarButton method multiple times to reinitialize your variable with the necessary ids that will be used inside the event handler to deal with the event. Therefore, the msSiteModeAddThumbBarButton method is guaranteed to return the same button id every time. This allows you to reuse your event handling logic independent of any navigation outside of the page.

Causing the Taskbar Button to Flash, Indicating That User Interaction Is Required

At times, you will want to notify users that your site requires interaction to advance or complete a task. Use the msSiteModeActivate method to start the flashing of the pinned site icon on the taskbar. For example, use this interaction when a user needs to enter their credentials, when a download is completed, or when another user is trying to communicate with a user.

To activate the state, call the msSiteModeActivate method.

window.external.msSiteModeActivate();

The icon flashes a maximum 20 times before the taskbar button stays permanently lit. After the user interacts with the site, Windows resets the taskbar button to the non-flashing state.

Icon Resolutions

Pinned sites use icons in several places: Jump List destinations, the taskbar button, thumbnail preview buttons, and overlay icons. Icon files should contain the following size representations:

Recommended: 16x16, 32x32, 48x48
Optimal: 16x16, 24x24, 32x32, 64x64

In a standard configuration, the taskbar icon will be 32x32, the Jump List destination icon will be 16x16, the thumbnail preview buttons will be 16x16, and the overlay icons will be 16x16. The image on the top left hand corner of the pinned site browser window holds a 24x24 version of the specified favicon. Using different .ico files, from the site favicon, to represent actions or destinations on the Jump List items and tasks will make it easier for your users to quickly identify the tasks they want to execute.

Coutersy Microsoft Corporation

SG OwnBlog

Search This Blog