Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

msAddSiteMode method

Creates a pinned site shortcut to the current webpage on the Windows Start menu.

This method is not supported for Windows Store apps using JavaScript.

Internet Explorer 9

 

Syntax

object.msAddSiteMode()

Parameters

This method has no parameters.

Return value

Return codeDescription
E_ACCESSDENIED

Method not invoked by user action.

E_FAIL

An error occurred.

E_NOTIMPL

This method is not supported on Windows CE.

 

Standards information

There are no standards that apply here.

Remarks

The msAddSiteMode method adds the current webpage to the Windows Start menu under All Programs and launches the webpage as a pinned site. In Windows Store apps using JavaScript it is pinned to the start screen. This method must be invoked by a user action, such as clicking a button, and the user is given an opportunity to confirm the action.

IE9 site mode add site dialog

The website is not pinned to the taskbar by default. Developers should encourage users to pin the website to the taskbar. Use the msIsSiteModeFirstRun method to determine when a website is installed, and remind users that the pinned site shortcut can be pinned to the taskbar.

When the webpage is launched as a pinned site, the shortcut icon ("favicon") of the website is used as the pinned site taskbar icon, as well as providing a color hint for the Back and Forward buttons in the pinned site browser window. To learn how to create high-resolution site icons, see Customizing the site icon.)

Meta Elements

Optionally, meta elements can be used to customize the default behavior of the pinned site shortcut. The following elements are "install-time" values that can appear in the webpage when it is pinned. You can use these elements to customize the shortcut created by the msAddSiteMode method.

NameContent
application-nameThe name of the shortcut. The value of application-name is also used as the name of the application button on the taskbar, and is appended to the window title for any pinned site window. If missing, up to 128 characters of the document's title element are 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.
msapplication-starturlThe starting page or home URL of the application. If missing, the address of the current page is used instead. Only HTTP or HTTPS protocols are allowed. For Windows Store apps using JavaScript this is pinned to the top of the jumplist.
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)
If pinned from Windows Store apps using JavaScript this is ignored.

 

The remainder of the elements are "run-time" values that might change over time. These elements can appear in the page that was installed, or in the page specified as the start URL for the pinned site.

NameContent
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, Level 3 (CSS3), is valid; however, custom colors should be dark enough to provide sufficient contrast for the white Back and Forward arrows of the buttons to be visible. For more information, see Color Table. If this meta element is absent, the color is based on the shortcut icon. If pinned from Windows Store apps using JavaScript this is ignored.
msapplication-taskYou can define up to five tasks. Tasks appear in the Jump List of the pinned site in the Start menu or when it is pinned to taskbar, even when the application is not running. (You can also create Jump List items by calling msSiteModeAddJumpListItem.) Sub-elements are separated using semicolons.
  • name=STR
  • action-uri=URI
  • icon-uri=URI

The following sub-element is optional:

  • window-type=TYPE (one of the following values)
    • tab (default) — a new tab in the current window
    • self — the current tab
    • window — a new pinned site window
msapplication-task-separatorPlace 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. If pinned from Windows Store apps using JavaScript this is ignored.

 

Examples

The following HTML and script restarts the webpage as a pinned site when the user clicks a button.


<script type="text/javascript">
function addWebApp() {
    try {
        window.external.msAddSiteMode();

    }
    catch(ex) {
        // Site Mode not supported.
        // Add code to provide alternative action if desired. 
    } }
</script>
<button onclick="addWebApp()"
    title="Click to add this webpage to pin this site.">
    Launch in Site Mode</button>

When using an anchor tag <a> to run JavaScript from a serverside ASP.net website, you must return false at the end of the JavaScript block to prevent navigation. By default, ASP.net attempts to navigate to an address contained in an <a> tag. When using a button to launch a pinned site, this isn't an issue. For static webpages, and scripting systems that don't navigate on an <a> tag by default, returning false doesn't affect the behavior.


<script type="text/javascript">
function addWebApp() {
    try {
        window.external.msAddSiteMode();

    }
    catch(ex) {
        // Site Mode not supported.
    } 
    return (false); // Alway return false when launching API from asp.net
}
</script>
<a href="javascript:addWebApp()" title="Click to add this webpage to pin this site.">Launch in Site Mode</a>

The following meta elements customize the pinned site shortcut with a tooltip, start URL, initial window size, navigation button color, and a predefined task.


<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"/>
<meta name="msapplication-task"
 content="name=Task1;action-uri=action1.html;icon-uri=images/icon1.ico"/> 

See also

external
window
Reference
msIsSiteMode
msIsSiteModeFirstRun

 

 

Show:
© 2014 Microsoft