IE Pinned Sites Part 7: How to implement Thumbnail Toolbar Buttons
When you hover the mouse over a Taskbar button of a running application or website, a “thumbnail” pops up. This is a little image of the running window.
With pinned sites, you can create thumbnail toolbar buttons, which are small buttons that will display directly under the thumbnail in that popup. Here is one example, from the site https://www.jango.com which I’ve pinned.
Jango is a site with free streaming music. I’ve customized a station based on my favorite musicians, and it finds other similar artists that I would probably like as well. When I’m playing music from the site and I hover over the taskbar button, a thumbnail pops up with 2 thumbnail toolbar buttons, to pause the music and to skip to the next song.
This is a really cool feature. I can be coding and have Jango playing in the background, and if a song comes on that I don’t like, I can just hover over the Jango Taskbar button and then click the “Next” button on the thumbnail toolbar. I don’t even have to bring up the main Jango window! Thumbnail toolbars let you interact with the site without having to restore or activate the site's window.
You can have a maximum of 7 buttons in a thumbnail toolbar.
You can implement thumbnail toolbar buttons in your pinned sites using JavaScript. First, add a thumbnail toolbar button using msSiteModeAddThumbBarButton. This takes two parameters – a link to the icon resource file (*.ico) and a button name or description, which is displayed as a tooltip on hover. It then returns an integer identifier of the new button. In the code snippet below, I will add a “Next” button.
btnNext = window.external.msSiteModeAddThumbBarButton('Images/next.ico', 'Next');
Then, you need to set up an event handler to react when that button is clicked. Use the addEventListener method which takes 3 parameters: the event type to respond to (you should use “msthumbnailclick” for this), the event handler function to associate with the event, and a Boolean value that specifies to add the event handler for the capturing or bubbling phase of the event (true is the capturing phase and false is the bubbling phase).
document.addEventListener('msthumbnailclick', onThumbnailButtonClicked, false);
Next, enable the thumbnail toolbar using msSiteModeShowThumbBar.
window.external.msSiteModeShowThumbBar();
Then, you need to update the button(s) using msSiteModeUpdateThumbBarButton. This is a little strange since we just “showed” the thumbnail toolbar, but what it essentially does is enable and make visible the individual buttons. For each button, you would call this method, passing in the button ID that we got from msSiteModeAddThumbBarButton, a Boolean value on whether the button should be enabled, and a Boolean value on whether the button should be visible. In the code below, I will make our “Next” button enabled and visible.
window.external.msSiteModeUpdateThumbBarButton(btnNext, true, true);
Finally, you can optionally add button styles using msSiteModeAddButtonStyle and show the button styles using msSiteModeShowButtonStyle. This is useful if you have a play/pause button like the Jango example above. This is a single button that toggles between two states – when the music is playing, it’s a “Pause” button, and when the music is paused, it’s a “Play” button. You could define a “Play” style and a “Pause” style, and then just swap styles on the button when appropriate. The msSiteModeAddButtonStyle method takes 3 parameters: the button ID that we got from msSiteModeAddThumbBarButton, the URI to the icon resource file (*.ico), and an optional description of the button. It then returns the ID of the new button style. The msSiteModeShowButtonStyle method takes 2 parameters: a button ID and a style ID, to apply the specified style to the specified button.
stylePlay = window.external.msSiteModeAddButtonStyle(btnPlayPause, 'play.ico', 'Play');
stylePause = window.external.msSiteModeAddButtonStyle(btnPlayPause, 'pause.ico', 'Pause');
// Initially, make it a play button.
window.external.msSiteModeShowButtonStyle(btnPlayPause, stylePlay);
Here’s a more sophisticated code example that puts it all together. This is the code that I wrote for the Windows Development Boot Camp site. If you pin this site and hover over the taskbar button when the site is running, you will see this:
There are “Previous” and “Next” thumbnail toolbar buttons to iterate through the pages in the website. If you look at the menu across the top of the site, you will see that there are only 6 pages to the website: Home, Locations, What to Bring, Agenda, Resources, and Trainers. Clicking on the “Next” button in the thumbnail toolbar will navigate you to the next page in the site, in that order.
In the code below, I set up these “Next” and “Previous” thumbnail toolbar buttons. When either of these buttons is clicked, it calls the onThumbnailButtonClicked method. This method uses two helper methods (getPrevPage and getNextPage) to figure out the previous or next page in the site based on the current page. It forms a new URL and then navigates to it.
<script type="text/javascript">
// Thumbnail Toolbar Buttons
if (window.external.msIsSiteMode()) {
// Add buttons listener
document.addEventListener('msthumbnailclick', onThumbnailButtonClicked, false);
// Add buttons
btnPrev = window.external.msSiteModeAddThumbBarButton('Images/prev.ico', 'Previous');
btnNext = window.external.msSiteModeAddThumbBarButton('Images/next.ico', 'Next');
// Show thumbbar
window.external.msSiteModeShowThumbBar();
// Make the buttons enabled and visible.
window.external.msSiteModeUpdateThumbBarButton(btnPrev, true, true);
window.external.msSiteModeUpdateThumbBarButton(btnNext, true, true);
}
function onThumbnailButtonClicked(e) {
// Scroll to the next or previous page in the site
var itemURL;
switch (e.buttonID) {
case btnPrev:
itemURL = "https://" + window.location.host + getPrevPage(window.location.pathname);
break;
case btnNext:
itemURL = "https://" + window.location.host + getNextPage(window.location.pathname);
break;
}
window.navigate(itemURL);
}
function getNextPage(currentPage) {
var retVal;
switch(currentPage) {
case "/":
retVal = "/Location.aspx";
break;
case "/Default.aspx":
retVal = "/Location.aspx";
break;
case "/Location.aspx":
retVal = "/WhatToBring.aspx";
break;
case "/WhatToBring.aspx":
retVal = "/Agenda.aspx";
break;
case "/Agenda.aspx":
retVal = "/Resources.aspx";
break;
case "/Resources.aspx":
retVal = "/Trainers.aspx";
break;
case "/Trainers.aspx":
retVal = "/Default.aspx";
break;
default:
alert(currentPage); // To see what is being missed
break;
}
return retVal;
}
function getPrevPage(currentPage) {
var retVal;
switch (currentPage) {
case "/":
retVal = "/Trainers.aspx";
break;
case "/Default.aspx":
retVal = "/Trainers.aspx";
break;
case "/Location.aspx":
retVal = "/Default.aspx";
break;
case "/WhatToBring.aspx":
retVal = "/Location.aspx";
break;
case "/Agenda.aspx":
retVal = "/WhatToBring.aspx";
break;
case "/Resources.aspx":
retVal = "/Agenda.aspx";
break;
case "/Trainers.aspx":
retVal = "/Resources.aspx";
break;
default:
alert(currentPage); // To see what is being missed
break;
}
return retVal;
}
</script>
There is also a great sample online from the IE Test Drive site: the Pin Site Radio.
I’ve already provided a real-world example of a thumbnail toolbar from a popular site (Jango), but another great example is the Discovery Channel website. If you pin that website and hover over the Taskbar button, you will see a thumbnail toolbar with 4 buttons for sharing on popular social media sites.
Finally, there are some important best practices around thumbnail toolbar buttons. First, create all buttons on the Start URL page. (Go back to this post if you don’t remember the Start URL stuff.) Secondly, create and show your buttons on every page load, and hide your buttons on every page unload. Let me illustrate why this is important.
As an example, take the Jango pinned site. Remember that it has two thumbnail toolbar buttons for pausing the music and skipping to the next song, like so:
But a pinned site, even though it has been customized for a particular site, is still in a web browser. Therefore, you can still navigate elsewhere. I’m now going to navigate to https://xkcd.com from inside of my Jango pinned site:
Now, if I hover over the Jango taskbar button, I still see the “pause” and “next” buttons, even though they don’t make any sense in the context of xkcd (which is a webcomic). That is why you should hide your thumbnail buttons on unload.
In tomorrow’s post, we’ll learn how to make the taskbar button for a pinned site flash.
Other Blog Posts in this Series
IE Pinned Sites Part 1: What Are Pinned Sites?
IE Pinned Sites Part 2: Why Implement Pinned Sites?
IE Pinned Sites Part 3: How to implement basic site properties
IE Pinned Sites Part 4: How to implement Jump List Tasks
IE Pinned Sites Part 5: How to implement dynamic Jump List Categories
IE Pinned Sites Part 6: How to implement Overlay Icons
IE Pinned Sites Part 7: How to implement Thumbnail Toolbar Buttons
IE Pinned Sites Part 8: How to implement a Flashing Taskbar Button
IE Pinned Sites Part 9: Patterns to make your pinned site code play nice in all browsers