Export (0) Print
Expand All
92 out of 114 rated this helpful - Rate this topic

Pinned Sites: Windows 7 Desktop Integration with Internet Explorer 9

Israel Hilerio, Ph.D.
Program Manager, Internet Explorer

September 15, 2010

This documentation was published for Internet Explorer 9 Beta. For the most current information, see the following:

Introduction

Windows Internet Explorer 9 introduces pinned sites, a feature with which you can integrate your websites with the Windows 7 desktop. With pinned sites enabled for a website, users can pin that site to the Windows 7 taskbar or add the site to the desktop or Start menu. Pinned sites enable easy access to favorite websites and add shortcut functionality similar to that found in Microsoft Windows applications. In addition, pinned sites require little development cost and offer robust features. Some meta elements and JavaScript is all that you need to gain functionality; you need not modify any existing content or attributes for a current website.

The following screen shot showcases the functionality available through pinned sites.

screen shot of features in pinned sites Figure 1: Features in the Windows 7 taskbar that a pinned site can use

Windows generates a shortcut file with the .website extension for each pinned site, whether the site is pinned on the taskbar, added to the desktop, or Start menu. Windows associate the site’s URL as the start URL for a specific .website file and creates a unique AppID based on that URL. The AppID is shared by any window or tab created from this Windows Internet Explorer instance and enables users to treat all of their tabs and windows that are instantiated from the same site as one group.

When a user launches your website from a pinned site, the website renders with a custom-branded look using your site’s favicon, navigation button colors, and other information you provide. The pinned site window automatically starts an isolated instance of Internet Explorer that runs in a special mode (note that Browser Helper Objects and other toolbars are not enabled in this Internet Explorer mode). If an instance of Internet Explorer that is used for general web browsing crashes, this self-contained instance used for the pinned site is not affected and continues to operate normally.

The pinned site APIs and the HTML meta tags described in this article provide capabilities for websites to tightly interact with the user through desktop concepts familiar to customers who use native Windows applications. The following sections describes the common enhancements these APIS offer through a pinned site:

Pinning a Site to the Taskbar

There is no programmatic way to pin a site to the taskbar. All pinning actions require user intervention. Users must complete one of the following actions to pin a site to the taskbar:

  • Tear off a tab, and drag it to the taskbar.
  • Drag the favicon from the address bar in Internet Explorer to the taskbar.

The following screen shot shows how a user might tear off a tab to pin the CNN website to the taskbar.

A user clicks and tears the tab to isolate it from any other tabs in the open browser
Figure 2: A user clicks and tears the tab to isolate it from any other tabs in the open browser

A user drops the tab on the taskbar to pin the site to the taskbar
Figure 3: A user drops the tab on the taskbar to pin the site to the taskbar

After the site is pinned, notice that the site renders with custom enhancements. For instance, the Back and Forward buttons match the color of the website.

A pinned site that is customized by using meta elements incorporated in the website
Figure 4: A pinned site that is customized by using meta elements incorporated in the website

We recommend that you encourage users to tear off tabs and use them as pinned sites. For instance, the following sample page from the Internet Explorer 9 Test Drive site includes a prompt (you can dynamically disable this notification later, testing for the msIsSiteMode method to know when it is appropriate to do so).

A website displays a prompt to increase knowledge of pinned sites
Figure 5: A website displays a prompt to increase knowledge of pinned sites

Adding a Website to the Start Menu (All Programs Menu)

With Internet Explorer 9, users can add any website to the Windows Start menu by using menu commands (click the Tools menu and then click Add site to Start menu). The website is then listed in the All Programs folder of the Start menu. In addition to user interaction, your website can promote this functionality programmatically by using the pinned site APIs. After adding a site through your website or the browser, users can then access the website through the Start menu, just as they access a native application running on Windows. As with those webpages pinned to the taskbar, webpages launched from the Start menu provide the fully branded experience once you provide markup to customize the start URL, icon, name, tooltip, and navigation button colors associated with the Start menu entry.

All of the mechanisms designed to add an entry into the Start menu generate a dialog box that asks users to confirm or cancel the operation, as the following screen shot shows.

The dialog box where users confirm whether to add an entry into the Start menu
Figure 6: The dialog box where users confirm whether to add an entry into the Start menu

Adding a website to the Start menu by using the pinned sites APIs

Use the window.external.msAddSiteMode() method to add a site to the Start menu. The API can be triggered from any HTML element by using JavaScript, as in the following code example:

<a onclick="window.external.msAddSiteMode();" href="#">Add Website</a><br />

You can identify if a website has been launched as a pinned site by calling the window.external.msIsSiteMode method. The msIsSiteMode method returns a Boolean value that returns true if the window was launched as a pinned site; otherwise, false.

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:

NameContent
application-nameThe name of the shortcut. If missing, the document title is used instead.
msapplication-tooltipOptional 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-starturlThe 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-colorThe 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-windowThe 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.

Jump List tasks associated with a communication site
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.

A custom notification in Outlook Web Access
Figure 8: A custom notification in Outlook Web Access

Managing 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 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.
  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');
    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 msSiteModeShowJumplist 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);
	

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.

An overlay icon in Outlook Web Access
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.

Thumbnail toolbar buttons to control video
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) {
         alert ("addeventlist:thumbnail btn id" + btn.buttonID);
}
	

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.

Detecting Features

You should use feature detection to verify that a browser supports pinned sites. The following code example evaluates to true if the feature is supported in your browser:

if (window.external.msIsSiteMode) {
    // Check if the website was launched from a pinned site.
    if (window.external.msIsSiteMode())
    {
        // TRUE
    }
    else
    {
        // FALSE
    }
} 
	

Note  The Internet Explorer 9 Beta release requires that the call to test for the API happens in a try/catch block, as follows:

try {
     if(window.external.msIsSiteMode()) { }
     else {}
}
catch(e) { }
	

Conclusion

By using pinned sites, users integrate their favorite websites with the Windows 7 desktop, Start menu, and taskbar as they do for an application running executable code on Windows. Using the pinned sites APIs, your webpages can enhance desktop integration and push information, notifications, and alerts to users without requiring the browser window to be in view. In addition, pinned sites enable a branded experience and promote your website’s capabilities in the taskbar.

Israel Hilerio is a program manager on the Internet Explorer team.


Show:
© 2014 Microsoft. All rights reserved.