jQuery "Pinify" Plugin Tutorial for Building App-Like Sites

The parameters functionName and options are not mandatory. By default the init function is called and it adds several meta tags to the markup. The plugin gathers the site information and sets the values for the various meta tags. Usually the ‘head’ element of the page is specified as a selector:

$(‘head’).pinify(); 

However, the users of the website might not know that the site can be pinned. It is a developer’s responsibility to advertise this feature. The developer can let users know of this feature by showing a banner on the site or by adding an image that can be dragged to the taskbar. To enable any element on the page for pinning, the functionName must be specified as ‘enablePinning’. Also, a tooltip is shown when the user hovers mouse over the image. The tooltip can be specified as a second argument to the pinify function. If it is not specified, the default tooltip would be shown.

$(‘img’).pinify(‘enablePinning’,’Drag me to the taskbar’);

Another way to advertise this feature is to show a teaser banner below  the address bar.  To add a teaser to the page, the functionName ‘pinTeaser’ is specified.

$('#header').pinify('pinTeaser', {	
               icon: 'favicon.ico',
               pinText: 'Drag this image to the taskbar to pin this site',
               textColor: 'white',
               mainContentSelector: '#body'
});

It is also a good idea to pin a site to the start menu. To do this, specify the functionName as ‘enableSiteMode’. On clicking the page element, a dialog box prompts  users to confirm the action of pinning the site to the start menu.

$(‘a’).pinify(‘enableSiteMode’,click);

The function can also be invoked for other events. The event name can be specified as a second argument to the pinify function. When the event name is not specified, the click event is bound by default.

Customizing the pinned site

The site being pinned can be customized by providing the various site-specific details in the pinify function. These include width and height of the browser window, the icon to be used when the user pins the site, the startUrl, applicationName, tooltip and tasks. A task can be any navigation link or site functionality. This enables users to navigate to a specific page of the site without visiting the home page.

$('head').pinify({
                applicationName: 'mySite1',
                favIcon: 'sample_icon.ico',
                navColor: 'Black',
                startUrl: '/sample/pinify_simple.html',
                tooltip: 'mySite',
                window: 'width=800;height=600',
                tasks: [
             {
               	     'name': 'jQuery Twitter feed',
                    	     'action': 'http://twitter.com/jQuery',
                    	     'icon': 'http://jquery.com/favicon.ico'
                	},
 	              {
                    	     'name': 'Microsoft blog',
                    	     'action': 'http://blogs.technet.com/b/microsoft_blog/',
                    	     'icon': 'http://blogs.technet.com/themes/wireframe/favicon.ico'
                	}]
 });

On right-clicking the pinned site, the specified options are shown. As observed, the navigation links are added under the tasks category. This category can contain up to five items. These navigation links remain same regardless of the status of the application.

Utility Functions

The Pinify plugin contains various utility functions that leverage the new features introduced in Internet Explorer 9 and make a pinned site behave more like a desktop application. Also, these functions perform browser-specific checks and handle exceptions. These plugin functions ensure that Internet Explorer 9-specific functionality does not throw error on other browsers. Therefore, a website developer need not add any browser check nor perform any exception handling explicitly.

Checking whether the site is pinned

Before showing a banner to the user to pin the site, it is important to check whether the site is already pinned. If not, then a notification banner can ask the user to pin the site. The isPinned function returns true if the site in question has already been pinned and false otherwise.

$.pinify.isPinned();

Checking the first run state

Sometimes, it is important to find out when the pinned site is launched for the first time. When launched for the first time from the taskbar or the start menu, some utility functions can be invoked. The firstRunState function is used to determine whether the pinned site has been launched for the first time. It returns ‘0’ if the either the site is not pinned or it is never launched. It returns ‘1’ if the site is launched for the first time from the taskbar and returns ‘2’ if the site is launched for the first time from the start menu.

$.pinify.firstRunState();

Adding a Jump List

On right clicking the pinned site; a menu slides out showing a list of site specific tasks. As mentioned earlier, a set of navigation links can be added to the pinned site by specifying the same as an argument to the pinify function.

The plugin includes a function that allows developers to add a list of navigation links dynamically. These can be specific to an individual user and can appear in a Jump List category that you specify. For example, if a user is viewing books on an online book store and adding few of them to the shopping cart, then links such as ‘Recently viewed’, ‘My shopping cart’, ‘My Wishlist’, etc, can be added to the Jump List. The addJumpList function is used to add a dynamic Jump list to a pinned site:

$.pinify.addJumpList(options);

Example:

$.pinify.addJumpList({
                title: 'My stuff',
                items: [
			{
				name: 'Recently viewed books',
				url: '/recentlyView.html',
				icon: 'book.ico'
			},
			{
				name: 'New book releases',
				url: '/newBookReleases.html',
				icon: 'recent.ico'
			}
		]
});

As observed, a Jump List with the category name ‘My stuff’ appears above the Tasks category. When users wish to the see the books that were viewed last time, then a navigation link on the Jump list lets them  get to the page quickly. Also, the website developer can add links which might interest them. For example, the link ‘New book releases’ would interest  users and encourage them to find out new books available.

Removing a Jump List

To remove a Jump List from a pinned site, the clearJumpList function can be called. This removes all links that were added dynamically.

$.pinify.clearJumpList();

Creating Thumbnail Toolbars

In Windows, on mouse hover  over the taskbar button, a thumbnail preview of the application is shown. In some applications, a toolbar is shown just underneath the thumbnail preview of the application. This toolbar is essentially used as a remote control. For example, when a user hovers’ mouse over a Media player button on the taskbar, a thumbnail preview showing the artwork of the current album appears. Just under the thumbnail preview, buttons ‘Previous’, ‘Play\Pause’ and ‘Next’ are shown. These buttons can be used to control the media being played.

Similarly, when a user hovers’ mouse over the taskbar button of a minimized pinned site, a thumbnail preview is shown. The function createThumbbarButtons allows developers to add a set of thumb bar buttons under the thumbnail preview. These buttons can then be used to control the site behavior. For example, buttons ‘Home’, ‘Search’ and ‘Contact Us’ can be added as thumb bar buttons and on clicking one of these buttons, the user will be navigated to the selected page.

$.pinify.createThumbbarButtons(options);

Example:

$.pinify.createThumbbarButtons({
		buttons: [
				{
					name: 'Home',
					icon: 'Home.ico',
					click: function() {
						document.location = "home.html"
					}
				},
				{
					name: 'Contact Us',
					icon: 'email-icon.ico',
					click: function() {
						document.location = "contact_us.html"
					}
				}
			 ]
});

Showing Notifications

Several web applications look for new data by sending request to the server at regular intervals. If there is any new data available, then the entire page or a part of the page is updated and new content is shown. The plugin includes functions that enable developers to show notification by adding an overlay icon and by flashing the taskbar for the pinned site. These notifications appear only when the user launches the pinned site.

Showing notifications by adding an overlay icon

Overlay icons are small icons drawn over an existing one. Windows uses these overlay icons to distinguish it from other files. For example, an arrow icon is used as an overlay icon for files to indicate them as shortcut files or an application requiring administrator privileges has a shield as an overlay icon. Similarly, in a web application, an overlay icon can be used to notify the user of the new content. The addOverlay function can be used to add a custom overlay icon over the taskbar button for the pinned site. The icon would appear in the lower right corner of the taskbar button.

$.pinify.addOverlay(options);

Example:

$.pinify.addOverlay({
           title: 'New Message',
           icon: 'newmessage.ico'
});

Once a user restores the browser window, the overlay icon should be removed from the taskbar button.  The clearOverlay function can be called to clear any overlay icon.

$.pinify.clearOverlay();

Showing notifications by flashing the taskbar button

Another way to show notification or to grab user’s attention is to flash the taskbar button. The function flashTaskbar flashes the pinned site button on the taskbar. This function would flash the taskbar button only when the browser window is minimized.

This function should be used only when an important event occurs;  events that require immediate attention. For example, if the user session is about to expire, then it would be a good idea to flash the taskbar button to grab the user’s attention.

$.pinify.flashTaskbar();

Summary

The Pinify plugin allows developers to add Internet Explorer 9 site-specific features with minimum effort. A developer can provide rich desktop-like experience to the user using this plugin. The plugin can also be used to encourage the users to pin the site. Once a site is pinned to the taskbar, various utility functions included in the plugin can be used to make the website appear more like a desktop application. The plugin ensures that no errors are thrown on other browsers and therefore, doesn’t require developers to add browser specific checks.