Declaring Pinned Site Metadata

  • Article

The Channel9 Podcast Player sample application uses metadata in the webpage to do the following:

  • Set the starting page of the Pinned site
  • Specify tooltip text that appears when you hover the mouse pointer over the Pinned site button on the taskbar and desktop
  • Constrain the initial size of the browser window
  • Customize the color of the Back and Forward buttons in the Pinned site browser window
  • Add static tasks to the Jump List

This task describes the basic site metadata that customize your Pinned site. In combination with the next task, Adding Tasks to a Jump List, you learn how to use metadata to define a basic Pinned site.

  • Metadata for Installation
    • application-name
    • msapplication-tooltip
    • msapplication-starturl
    • msapplication-window
  • Run-time Metadata
    • msapplication-navbutton-color
    • msapplication-task
    • msapplication-task-separator
  • Putting It All Together
  • More Examples
    • Bing.com
    • BeautyoftheWeb.com
    • Facebook.com
  • Related topics

Metadata for Installation

The following meta elements control how the Pinned site shortcut is created on the Start menu and on the Windows 7 taskbar. All these elements are optional, but highly recommended for more control over where the page starts, its name, better accessibility or recognition, and customized size at startup.

The installation metadata elements are used only when the user pins the site. After that, changes to these values do not have any effect on the Pinned site. Because of this, the following meta elements are sometimes called "install-time" values:

  • application-name
  • msapplication-tooltip
  • msapplication-starturl
  • msapplication-window

If you want to enable users to pin other webpages on your domain, add the install-time metadata to the headers on all the applicable pages.

Note  Windows Internet Explorer 9 and later versions read the rest of the metadata from the start URL of the Pinned site when the site is launched.

 

application-name

The "application-name" metadata defines the name of the Pinned site application instance. This is the name that appears in a tooltip when hovering over the Pinned site button on the Windows 7 taskbar. The application name is also appended to the window title of the Pinned site application instance.

<meta name="application-name" content="Channel 9 Audio Player" />

If this element is missing, the document title is used instead.

msapplication-tooltip

The "msapplication-tooltip" metadata provides additional tooltip text that appears when you hover over the Pinned site shortcut in the Windows Start menu or on the desktop.

<meta name="msapplication-tooltip" content="Channel 9 Podcasts" />

msapplication-starturl

The "msapplication-starturl" metadata contains the root URL of the application. The start URL can be fully qualified, or relative to the current document. Only HTTP and HTTPS protocols are allowed. If this element is missing, the address of the current page is used instead.

<meta name="msapplication-starturl" content="./" />

The "msapplication-starturl" metadata creates a common entry point to your website. When present, the Pinned site launches the start URL instead of the page that was originally dragged to the taskbar. More importantly, run-time metadata declared in the start page redefines the navigation button color and static Jump List tasks each time the site is launched. (For more information, see the Run-time Metadata section.)

As an example of how "msapplication-starturl" might be used, consider a site that offers multiple types of calculator emulators: one with a standard layout, one a scientific layout, and one that has statistics functions. Without a start URL, the user might pin only the scientific calculator to the taskbar and never have an easy way to access the other calculators in the collection. By adding a start URL, the site developer can declare a common entry point for the site.

<meta name="msapplication-starturl" content="./CalculatorHome.html" />

By adding install-time metadata to the emulator pages, the site developer controls how users access the site. Then, by adding Jump List metadata in the start page, the site developer can more easily control how users select the style of calculator they want to use. For more information, see Adding Tasks to a Jump List.

Handling Server Redirects

If your start URL redirects to another webpage, make sure you declare all run-time metadata in the webpage that is served to the client. If the server redirects to a new path, your start URL must include the path and a trailing slash (/).

For example, if "https://contoso.com/" redirects to "https://www.contoso.com/Home/" then the start URL must include the new path and trailing slash, as follows:

<meta name="msapplication-starturl" content="https://www.contoso.com/Home/" />
OR
<meta name="msapplication-starturl" content="/Home/" />

msapplication-window

The "msapplication-window" metadata sets the initial size of the Pinned site window when it is launched for the first time. However, if the user adjusts the size of the window, the Pinned site retains the new dimensions when it is launched again.

<meta name="msapplication-window" content="width=1024;height=768" />

The following table describes the parts that make up the content attribute of the meta element. Both parts are required, and must be separated by a semicolon.

Part Description
width The window width in pixels. The minimum value is 800.
height The window height in pixels. The minimum value is 600.

 

Run-time Metadata

Unlike the install-time values, the following metadata are read each time the user launches the Pinned site. Because of that, site developers can use these values to modify the user experience over time. The best way to control changes to these values is to define them in the start URL of the Pinned site.

  • msapplication-navbutton-color
  • msapplication-task
  • msapplication-task-separator

Note  These elements are also optional.

 

msapplication-navbutton-color

The "msapplication-navbutton-color" metadata define the custom color of the Back and Forward buttons in the Pinned site browser window. Any named color, or hex color value is valid. For a complete list of color names, see Color Table.

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

If this meta element is absent, the default color is based on the color palette of the site icon (or, favicon). To learn how to select a custom icon for your site, see Customizing the Site Icon.

msapplication-task

Like the other site metadata, you define static tasks with meta elements. The next task, Adding Tasks to a Jump List, explains how to do this.

msapplication-task-separator

Place this element between tasks to place a visible line in the Jump List menu. The separators must be made unique by declaring content="[unique value]" if you have more than one.

Putting It All Together

Here is the basic Pinned site metadata used by the Channel9 Podcast Player sample application.

<meta name="application-name" content="Channel 9 Audio Player" />
<meta name="msapplication-tooltip" content="Channel 9 Podcasts" />
<meta name="msapplication-window" content="width=1024;height=768" />
<meta name="msapplication-navbutton-color" content="#FF3300" />
<meta name="msapplication-starturl" content="./" />

More Examples

To help you envision how you might implement these basic features on your own sites, this section includes additional examples from websites that have added Pinned site metadata to enhance their user experience in Internet Explorer 9.

Bing.com

<meta content="Bing" name="application-name" />
<meta content="Bing" name="msapplication-tooltip" />
<meta content="width=1024;height=768" name="msapplication-window" />
<meta content="/" name="msapplication-starturl" />

BeautyoftheWeb.com

<meta name="application-name" content="Beauty Of The Web" />
<meta name="msapplication-tooltip" content="Start the Beauty Of The Web" />
<meta name="msapplication-starturl" content="https://www.beautyoftheweb.com/" />
<meta name="msapplication-navbutton-color" content="#5f6dbd" />

Facebook.com

<meta name="application-name" content="Facebook"/>
<meta name="msapplication-tooltip" content="Start the Facebook App"/>
<meta name="msapplication-starturl" content="/"/>
<meta name="msapplication-window" content="width=800;height=600"/>

Tasks

Adding Tasks to a Jump List

Badge Notifications, directly on your Windows 8 Pinned Site

Customizing the Site Icon

Fresh Tweets 2.0 - demo for Windows 8

High Quality Visuals for Pinned Sites in Windows 8

Pinned Sites in Windows 8

Conceptual

How to Create a Basic Pinned Site

Introduction to Pinned Sites