This project is read-only.

Utility Functions

Once a user has pinned your site, you’ll can make use of several new features in IE9 that allow your site to behave more like a full desktop application. These include the ability to:

  1. Determine if the user has pinned the site (isPinned()) or if a pinned site is being launched for the first time (firstRunState())
  2. Create Dynamic Jump Lists (addJumpList, clearJumpList)
  3. Create Thumbnail Toolbars and respond to click events (addOverlay, clearOverlay)
  4. Create overlay (icon) on the taskbar (createThumbbarButtons)
  5. Flash the taskbar (flashTaskbar)

 

All of these functions are accessible via the pinify namespace:

$.pinify.functionName

In some cases, these methods merely wrap what appears to be single-line call to a window.external function (firstRunState and isPinned), but, in fact, these methods perform browser-specific

checks and exception handling to ensure that calls to IE9-specific functionality does not result in errors in other browsers. As such, you are safe to use all of these utility functions in your own sites

without adding your own browser-checking and error handling.

$.pinify.firstRunState()

Determines whether a pinned site has been launched for the first time. Return values are:

  • 0 – The pinned site is not in a first-run state, or is not pinned
  • 1 – Pinned site is in a first-run from a drag-and-drop operation
  • 2 – Pinned site is in first-run from a shortcut added to the user’s Start menu

$.pinify.isPinned()

Determines whether the site in question has been pinned. Returns true or false

$.pinify.addJumpList(options) (and $.pinify.clearJumpList())

Adds dynamic jump-list items to a pinned window. For example, consider a photo gallery application. When the user pins the site, we want to retrieve a list of popular galleries and create a jump-list that

enables the user to navigate directly to each gallery. We would do so with the following call to jQuery.getJSON and our addJumpList function, as below:

 

$.getJSON('Gallery/List', function (data) {
   var itemList = [];

   $.each(data, function (key, val) {
      var item = {
         'name': data[key].name,
         'url': 'Gallery/View/' + data[key].id,
         'icon': '/Content/Images/icon-gallery.ico'
      };

      itemList.push(item);
  });

  $.pinify.addJumpList({
        title: 'Photo Galleries',
      items: itemList
  });
});

In our photo gallery, this code will result in the creation of a new jump-list that displays when the user right-clicks on the pinned site in the taskbar:

image

To clear the current jump lists, $.pinify.clearJumpList() can be called.

$.pinify.addOverlay(options) (and $.pinify.clearOverlay())

Adds a custom icon over the taskbar button in the lower right corner. Intended to notify the user of some external event that they might be interested in (i.e. new messages or chats in Facebook, new email in

Outlook Web Access, etc.). Considering the same photo gallery application, for pinned users, our application will poll our server every several seconds to determine if any new comments have been posted

on the user’s photos. If a new comment is retrieved, we’ll instruct pinify to add a comment icon overlay on the taskbar, as below:

setInterval(function () {
      $.getJSON('Photo/CommentsForUser/' + new Date().getTime() , function (data) {
         $.pinify.clearOverlay();

         var itemList = [];
         var commentCount = parseInt($('#commentCount').val());

         if (data.length > commentCount) {
            $('#commentCount').val(data.length);

            $.pinify.addOverlay({
               title: 'New comment: ' + data[0].text + ' (' + data[0].date + ')',
               icon: '/Content/Images/comment.ico'
            });
      }
   });
}, 5000);
<!-- Code inserted with Steve Dunn's Windows Live Writer Code Formatter Plugin. http://dunnhq.com -->

When a new comment is received, the taskbar will be changed to include our custom icon:

image

To clear the overlay icon, $.pinify.clearJumpList() can be called, as in the example above, which clears any existing overlays at the start of each check for new comments.

$.pinify.flashTaskbar()

Flashes the taskbar button. Intended to notify the user of some external event that they might be interested in. In the previous code sample, we can add another level of user notification by adding

$.pinify.flashTaskbar() before we set the overlay icon.

if (data.length > commentCount) {
   $.pinify.flashTaskbar();
   $('#commentCount').val(data.length);

   $.pinify.addOverlay({
      title: 'New comment: ' + data[0].text + ' (' + data[0].date + ')',
      icon: '/Content/Images/comment.ico'
   });
}
<!-- Code inserted with Steve Dunn's Windows Live Writer Code Formatter Plugin. http://dunnhq.com -->

image

Note that calling this function will cause the taskbar to continue flashing until the user re-activates the site.

$.pinify.createThumbbarButtons(options)

Creates buttons on the pinned site preview window thumbbar, and wires events to respond to button clicks. For example, Slacker Radio (www.slacker.com) uses this feature to place Play/Pause, Forward, Favorite and Ban buttons when the user pins the radio player. The end-result is a set of controls that enable the user to interact with the site without activating the browser window. Continuing with our Photo Gallery example, say I want to provide buttons that enable users to quickly navigate to the download or tags pages. I can add the following script to my page:

 

$.pinify.createThumbbarButtons({
   buttons: [{
      icon: '/Content/Images/download.ico',
      name: 'Download Images',
      click: function () {
         // Do all kinds of awesome, interactive stuff here
         document.location = 'Gallery';
      }
   },
   {
      icon: '/Content/Images/icon-tags.ico',
      name: 'Tag Images',
      click: function () {
         // Do all kinds of awesome, interactive stuff here
         document.location = 'Tag';
      }
   }]
});
<!-- Code inserted with Steve Dunn's Windows Live Writer Code Formatter Plugin. http://dunnhq.com -->

image

The function expects an array of button objects, each defining the location for an icon file, the name of a button and a callback function to execute when the button is clicked. The result is a couple of quick-access thumb bar buttons that the user can click to trigger all kinds of awesomeness. These buttons are more than just hyperlinks (unlike jump-list items), so you’re free to script away inside the callbacks!

Last edited May 11, 2011 at 6:35 PM by bsatrom, version 16

Comments

No comments yet.