msSiteModeAddThumbBarButton method

Adds a button to the Thumbnail Toolbar.

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

Internet Explorer 9

 

Syntax

object.msSiteModeAddThumbBarButton(iconURL, tooltip, buttonID)

Parameters

iconURL [in]

Type: String

Absolute or relative URL of an icon resource file.

tooltip [in]

Type: String

The button name, which is displayed as a tooltip on hover.

Return value

Type: Integer

Integer that receives the ID of the new button.

Standards information

There are no standards that apply here.

Remarks

The Thumbnail Toolbar lets you create interactive controls that supplement the behavior of your webpage. When a button is clicked, the webpage receives an onmsthumbnailclick event. The buttonID attribute of the event returns the ID of the button that was clicked. It's up to you to decide if the interaction stays local or if it is communicated back to the website.

A Thumbnail Toolbar can hold up to seven buttons. You cannot add more buttons after calling the msSiteModeShowThumbBar method. After the Thumbnail Toolbar has been created, you can hide or disable individual buttons with msSiteModeUpdateThumbBarButton. You can also change the icon and tooltip of a button with a button style. (See msSiteModeAddButtonStyle.)

The same toolbar and buttons are used for the lifetime of a tab, even if the user navigates between pages. To support this scenario, the following apply:

  • If this method is called with an icon URL and tooltip that were previously added or added as a style, even from a page you navigated away from, the same button ID is returned. This allows you to run the same code on different pages without having to check whether the buttons have already been created previously.
  • If this method is called after the Thumbnail Toolbar is shown, icon URLs and tooltips that match existing buttons are allowed. However, if the icon URL and tooltip do not match an existing button or button style, an "Invalid procedure call or argument" exception is thrown.
  • Unless you are sure that the Thumbnail Toolbar is appropriate for all pages of your site, you should consider disabling or hiding the buttons by calling msSiteModeUpdateThumbBarButton during the page onunload event. You will need to show the buttons again when the next page is loaded.

The icon resource must define at least one 16x16 pixel icon at 96 dots per inch (dpi).

Examples

The following example adds two buttons to the Thumbnail Toolbar and responds when they are clicked.


var btn1, btn2;
function init()
{
    document.addEventListener('msthumbnailclick', processSelection, false);
    
    btn1 = window.external.msSiteModeAddThumbBarButton('Images/play.ico', 'Play');
    btn2 = window.external.msSiteModeAddThumbBarButton('Images/stop.ico', 'Stop');
    
    window.external.msSiteModeShowThumbBar();
}
function processSelection(btn)
{
   if (btn.buttonID == btn1) 
   {
       // Play video
   }
   else if (btn.buttonID == btn2) 
   {
       // Stop video
   }
} 

The following example uses the msSiteModeUpdateThumbBarButton method to hide the toolbar when the page is unloaded.


function hideButtons() {
    window.external.msSiteModeUpdateThumbBarButton(btnPrev, true, false);
    window.external.msSiteModeUpdateThumbBarButton(btnPlayPause, true, false);
    window.external.msSiteModeUpdateThumbBarButton(btnNext, true, false);
}
<body onunload="hideButtons()"> ... </body>

See also

external
window
Reference
msSiteModeShowThumbBar
msSiteModeUpdateThumbBarButton

 

 

Show:
© 2014 Microsoft