Dragging an Image to Pin the Site
This topic explains how to implement a custom image that you can drag to the taskbar to pin a site.
- The msPinSite class
- Changing the mouse cursor
- Adding callouts to the image
- Hiding the image if the site is already pinned
- Next Steps
- Related topics
The msPinSite class
Any image format can be used as a drag-to-pin image, but we recommend you use the same .ico file that you use for your site icon. Standard image formats, such as PNG, GIF, or JPEG files, also work.
To implement the drag-to-pin image behavior, add the "msPinSite" class to your img element, as shown in the following example:
<img id="pinImage" class="msPinSite" src="Images/radio.ico" />
When Windows Internet Explorer 9 or Internet Explorer 10 detects an image that has this class, it automatically provides the drag-and-drop functionality.
.png)
Be aware that the site icon (not the drag-to-pin image) is used as the image in the drag operation. If you do not declare a site icon, the default Windows Internet Explorer icon is used instead. For the best user experience, your drag-to-pin image should be the same as your site icon. For more information, see Customizing the Site Icon.
Changing the mouse cursor
There are a few more things you can do to improve the discoverability of the drag-to-pin image. The best thing that you can do is to make sure the image that appears can be dragged, by changing the default cursor to a hand cursor icon when the user moves the mouse pointer over the image. The following CSS first attempts to load a custom cursor before defaulting to the hand pointer.
<style type="text/css">
#pinImage {
cursor: url('Images/DragImages/grab.cur'), pointer;
}
</style>
Adding callouts to the image
A more advanced implementation might proactively call attention to the drag-to-pin image by displaying a callout when the page loads and when the user moves the mouse pointer over the image. Callouts can help explain how to use the image to pin the website.
.png)
First, create the elements that make up the pin container, drag-to-pin image, and callout, as follows:
<div id="pinContainer" onmousedown="hideCallout();" >
<img id="pinImage" class="msPinSite" src="Images/radio.ico"
onmouseover="showCallout();" onmouseout="hideCallout();" />
<div id="callout">Drag this image to your taskbar to pin the site.</div>
</div>
Next, define the hideCallout and showCallout functions in JavaScript. The callout is initially visible, but the script hides it three seconds after the page is loaded by using the setTimeout method to call the hideCallout function .
<script type="text/javascript">
function showCallout(e) {
var obj = document.getElementById("callout");
obj.style.display = "block";
}
function hideCallout(e) {
var obj = document.getElementById("callout");
obj.style.display = "none";
}
setTimeout(hideCallout,3000);
</script>
Finally, the following CSS finishes the callout effect.
<style type="text/css">
#pinContainer {
display:none;
margin:10px;
cursor:url('Images/DragImages/grab.cur'), pointer;
}
#callout {
position:relative;
top:-48px;
left:72px;
background-color:#ffc;
width:160px;
padding:3px 5px;
border:1px solid black;
border-radius:5px;
}
</style>
Be aware that the #pinContainer element is initally hidden with display:none. This is its default state. The drag-to-pin image is unnecessary if the browser is not Internet Explorer 9, if the site is already in site mode, or if scripting is disabled. By default, the image should not be displayed in these cases.
Hiding the image if the site is already pinned
Finally, before displaying the drag-to-pin image, you need to detect whether the Pinned site features are available, and make sure the site is not already in site mode. The following script demonstrates how to do this:
<script type="text/javascript">
function initializePinnedSite()
{
try {
if (window.external.msIsSiteMode()) {
// Continue initialization.
}
else {
// Display drag-to-pin image.
obj = document.getElementById("pinContainer");
obj.style.display = "inline-block";
}
}
catch (e) {
// Fail silently. Pinned Site API not supported.
}
}
window.onload = initializePinnedSite;
</script>
Because the #pinContainer container element might be embedded in body text, the preferred display type is inline-block. It is also possible to float the container left or right to wrap text around it.
Next Steps
In the next task, Creating a First-run Experience, you learn how to detect when a site has been launched for the first time. This provides an opportunity to tell users about other Pinned site features of your website.
Related topics
Tasks
Conceptual
Badge Notifications, directly on your Windows 8 Pinned Site
Fresh Tweets 2.0 - demo for Windows 8
How to Improve Discoverability