Monday, February 27, 2012

Building Chrome Extensions From Scratch - Part 2

This is Part 2 of the series - Building Chrome Extensions From Scratch. In this part, we will continue from where we left off in the previous part.

As a quick recap, in Part 1, we covered

  1. The extension descriptor file - manifest.json
  2. How to define a default icon for a chrome extension that appears in the browser's toolbar.
  3. How to install a chrome extension from a local hard drive.

Our extension, whom we named Mr0, just had a name and a face. We used the manifest.json file to define the icon to be used as the default icon in the browser toolbar. But you may remember that there is one important component that I talked about in the previous post but did not discuss - the extension's background page.

A Brief Introduction

If the manifest.json file is the heart of the extension, then the background page can be aptly called the brain of the extension. Its like a Don that sits in the background and monitors its minions. The reason behind why I did not discuss it in the previous post was that in spite of its critical role in an extension, it is not mandatory for an extension to have a background page. Extensions are pretty simple beings. They don't need to think a lot in order to live. Hence, before we go ahead and talk more about the extension background page, lets see another aspect of the extension UI - the popup that appears when you click on an extension.

The Popup Page

Most of the extensions display a popup when you click on their icon in the browser toolbar. Taking our analogy a step further, we can safely assume that the popup that appears when you click on the extension icon is a the body of the extension. Unsurprisingly, the popup is nothing but another ordinary html page. And just like other html pages, you can write the usual CSS, markup and javascript. For instance, if you need to use jQuery, all you need to do is to keep the jquery.js file in your extension folder, and inside your popup, you can reference this file relatively.

In order to make use of a popup page, i.e. as a page that appears when the user clicks on the extension icon in the broswer toolbar, you need to specify the name of this html page in the manifest.json file. I am going to create a very simple html file called popup.html that says hello world. Below you can see the manifest file.

  "name": "Mr0",
  "version": "1.0",
  "browser_action": {
    "default_icon": "images/icon19.jpg",
 "default_popup": "popup.html"

The manifest.json file has not changed much. The only new addition is to the the browser_action property list. We added a property called the default_popup and specified the page that we wanted to load when the user clicks on the extension icon.

Below is the code for our popup page. As you can see, I made use of the jquery library in the same old fashioned way.

  Hello World

Save these changes. Once you are done, click on the browser icon and you will see a neat little popup near the extension that says hello world. In case the popup does not appear, it may be because the browser did not pick up the changes. You can try clicking again once you have reloaded the extension from the extensions menu.

A Faulty Click Counter

Aint that just sweet! And wasnt it astonishingly simple? But we all know that webpages can never become truly cool unless we introduce a bit of javascript into the them. Lets just say that we want to create some sort of a counter. One that tells us the number of times that you have clicked on the button inside an extension.

Here's what you'd write (at first)

Now if you click on the browser icon, the popup will show you a button that which upon clicking, increments the value of the counter. Now, click somewhere else on the screen to let the popup disappear and then click on the icon again. Now you see the same popup, but notice that the counter starts counting from 0 again. But didn't we increment the coutner when we clicked on the button previously?

Yes, of course we did. However, as it turns out, whenever you click on an extension icon, the popup window gets reloaded. Which means that the counter is initialized to 0 each time we click on the browser icon because we are declaring the variable counter on pageload.

So what do we do in order to maintain a click counter? We need to find a way to maintain state over multiple clicks on the extension icon. We need to store our variables in a place which has a longer lifetime as compared to the popup page. Does it remind you about the http session? Well, if you guessed that we are going to store the counter value in a http session, you are quite wrong. Thats because we dont have any server! But then thats where background pages come to the rescue.

Extension Background Pages

An extension background page, as I briefly discussed earlier, is like a Don who sits in the background and can monitor its minions. Its more like an browser scope page i.e. that it is alive in the background for as long as the extension is acive in the browser. However you should create background pages for extensions only when needed because since a background page is after all nothing but a page, it adds to the memory footprint of the browser.

Coming back to creating our extension, in order to maintain the state of the counter when the user exits the popup window, you will need to store the current state of the variable inside the background page. This is where the chrome extension API's come into play. When you are inside the pages that are a part of the chrome extension, you have access to a set of javascript functions that allow you to do a lot of cool stuff. One of them is the ability to communicate between different pages of the same extension. In our case, we need a channel of communication between the popup page and the background page.

Here's what I want to do. When the user clicks on the extension icon
Check if the background page has a predefined value for the counter. If yes, save as the value of the counter in the popup page. Each time the user increments the counter, save its value in the background page.

Extension Message Passing

In order to send and receive messages in an asynchronous manner between pages and scripts and between background pages and other scripts, chrome has a predefined set of functions.

Send a message to a tab

chrome.tabs.sendRequest(, requestJSON, function(response) {

Send a message to a background page

chrome.extension.sendRequest(requestJSON, function(response) {

Receive a message from either a tab or a background page

  function(request, sender, sendResponse) {
    //console.log( ?"from a content script:" + :"from the extension");
    //console.log(request.sender?'Request from : ' + request.sender:'unknown');

As you see, there are three functions. The first one is used to send a request from any extension script(we will talk more about this soon) such as the on one the popup page to another extension script on the tab.
The second one lets any extension script send a request to the background page, which is actually the main page for the extension.
The next function is nothing but a listener for a request. The syntax is same whether the request comes from a script in a tab or from an extension.

As you can clearly see in the comments written inside each of these functions, you can send a response to the caller via the sendRespose function parameter and pass any information that might have been requested by the caller.

In our example, we are going make use of these functions to store the value of the variable in the background page and then retrieve the stored value whenever the user clicks on the browser icon of the extension before we increment it locally.

A Correct Click Counter

Before we begin writing the code, we first need to create a background page and keep it in the extension folder. And then we need to specify that page to be used as the background page in the manifest.json file.
I created a page called background.html and placed it in the chrome_ext folder. Here's how my manifest.json file looks now.

  "name": "Mr0",
  "version": "1.0",
  "background_page": "background.html",
  "browser_action": {
    "default_icon": "images/icon19.jpg",
 "default_popup": "popup.html"

Then I modified the javascript code in the popup.html to look like this.

 chrome.extension.sendRequest({action:'getCounter'}, function(response) {
  var counter = response.counterValue?response.counterValue:0;
   chrome.extension.sendRequest({action:'setCounter', counterValue:counter}, function(response) {

Then in the background.html page, the following code will do the job for you.


Notice that I have placed the script of the background page inside the script tag. That's because, as I said earlier, the background page is also like a normal html page apart from the fact that it lives as long as the extension is alive and active in the browser.

Now, all you need to do is to reload your browser and when you click on the icon and click the counter, and repeat the same, the counter value will continue from the point where you previously left off.

In the next part of the series, we will take things a step further and try to make an extension that does more than just count clicks. Stay Tuned!

Happy Programming :)
Signing Off


Sunday, February 19, 2012

Building Chrome Extensions From Scratch - Part 1

Browser extensions have been all over the place lately. The past couple of days have been pretty amazing for me since began exploring these nifty little things. I learnt quite a bit, some out of sheer luck, some after a lot of trial and error and some after perusing the documentation a couple of times.

In this series, I plan to cover the topic of creating browser extensions using Google Chrome which undoubtedly is my browser of preference. There are a lot of tiny little things that I will cover in this series, some of which were not as obvious to me at first.

In the first part of this series, we will first understand what exactly is a chrome extension. And what are the most important basic components that you would need in order to make a Chrome extension from scratch. You can use this series as a step by step guide to create your first chrome extension.

What Is Being Covered?
This post intends to answer the following questions

  1. How to build Google Chrome extensions?
  2. What do I need to learn in order to build a Google Chrome extension?
  3. How to install my own extensions in Google Chrome?
  4. How to use setup the icon for a Google Chrome extension?
So, What Exactly Is A Browser Extension?
Well, if you expect me to answer what a browser extension is, you're in the wrong place buddy. However, just in order to give you a brief idea, a browser extension is nothing but a small piece of functionality that you can add to your browser, quite similar to the way you install applications on your personal computer/laptop/other devices.

Why Google Chrome?
Because I like chrome (Yea, you guessed it right, I am -a bit- biased!)

So, lets begin on our journey of trying to understand how to build google chrome extensions.

Getting Started

An extension in google chrome is nothing but a web page.
Wait. Let that line sink in for a moment.

Whoa! What! An extension? Is a web page? You gotta be kidding me!

Fortunately/unfortunately (whatever way you'd like to think about it) I am not kidding. When I first realized that Google chrome extensions are nothing but web pages, and you don't need to know any extra language other that javascript and css and html to build a chrome extension, my heart literally jumped with joy. If you are a fan of jQuery(like I am), you would be glad to know that you can use all the jQuery you wish in a google chrome extension. Why? Simply because its nothing but a web page!

Phew. I hope that relieves you a bit if you were holding back learning how to make extensions dreading the thought that you would need another new language in your arsenal. But then, there are a few caveats. Google chrome extensions are a some kind of special web pages. I say that they are special because these pages have access to the chrome extension javascript API. So, you can make use of all the javascript you know, but you would have to learn about a few functions that make an extension work like an extension. But then, don't tell me you expected it to be a bed of roses either!

Getting Into The Nitty Gritty Of Things

When you think of chrome extensions, think about 2 main things
  1. A file to describe your extension.
  2. An hidden page that runs in the background - the exension's background page.
There are of course many other pages and you can add a tonne of other stuff that you can do to make your extension all the more cool and fancy, but since this a is a step by step guide, I will be talking about each of these components one at a time as elaborately as my time (and mood) permits.

The Extension Descriptor File

I like to think of the descriptor file as the heart of a chrome extension. Without it, the browser would have no way of identifying your extension. Its like spiderman, it has great power and hence great responsibility too. Don't worry, you dont need to battle computer animated creatures to make our spiderman. In fact, its quite the opposite. If you have worked on javascript, I am pretty sure that you might have heard about JSON. It stands for JavaScript Object Notation. If you feel that I mentioned something out of your ken, you need to go back to google and first know what JSON is all about. Fear not, its pretty easy and will barely take you 5-10 mins to understand it. I had also written a post a couple of days ago where I discussed the difference between a JSON and JSONP, in case you are curious.

Coming back to our heart/spiderman, the descriptor file has a predefined name - manifest.json and it contains nothing but a JSON object that describes your extension. As the bare minimum, you need to specify the name and the version of your extension.

Creating Our First Extension. 

We need to think of a name to give our extension. Lets say, we call it "Mr 0". Its not the letter O, its the numeral zero. So, our extension is Mr zero. Why the peculiar name "Mr 0"? Well, everything in programming starts with a 0, like array indexes and blah blah, and even we human beings started from a 0, a zygote, or an egg, or whatever!.

First create a new folder, and call it, lets say chrome_ext and then create a manifest file with the name manifest.json in the newly created folder Now, we need to specify the name and the version of our extension in the manifest file using json. Here's how we do it

  "name": "Mr0",
  "version": "1.0"

That is just about what you need in order to be able to install an extension into your google chrome browser. (Observe that the name of the extension is independent of the name of the folder which contains the extension files, which in our case is chrome_ext). In order to install an extension from your local drive, you need to open the extensions page in google chrome via the Settings(the wrench on the top right)-> Tools->Extensions. A browser window opens up enlisting all of your installed extensions if you have any.

Extensions that you download from the web store are in a available in a particular format - .crx files. Since you are simply installing an extension from a folder, you need to enable 'developer mode' in your chrome extension list panel. So, click on the checkbox that says 'Developer mode' and 2 additional buttons appear on the screen as shown in the screenshot.

Click on the button that says 'load unpacked extension' and browse to the folder 'chrome_ext' that we created earlier and click on ok. The moment you click on OK, the extension gets installed and you will be able to see your first chrome extension among the list of extensions installed. And hail, because Mr0 is just born!

Giving Our Extension A Face

Well, our newly born Mr0, is pretty dumb(as of now). In fact, he is absolutely useless. After all, how can be of any use? He just has a name. In order to be able to seen by others, Mr0 needs a face. So lets give him a face. The face that we are going to give Mr0 is that of an Icon in the toolbar. In order to give Mr0 and icon, we need to specify the image for the icon in the manifest file.

Icons in the chrome toolbar are not more than 19x19 pixels. If you use a larger image, it will simply be scaled down to fit this size. I am going to keep it pretty simple. I am just going to create a 19x19 pixel image using paint and give it a dark red color. Nothing fancy. You can use any image you wish. I am going to name my image "icon19.jpg" and I will place it in a folder called "images" under my chrome_ext directory.

Here's how we can reference this image in the manifest file.

  "name": "Mr0",
  "version": "1.0",
  "browser_action": {
    "default_icon": "images/icon19.jpg"

That was pretty simple, wasn't it? We were quickly able to reference the image relative to the current file(the current file in this case being the manifest.json file).

Also notice that unlike the name and version attributes, the default_icon attribute is a nested attribute under the browser_action attribute. The browser action attribute is a map that contains key value pairs to describe different elements that are used to give the extension a user interface.

Now, if you reload your extension, you will be able to see a little icon at the top in the chrome toolbar and if you hover your mouse over it, a small tooltip comes up which displays the name of your extension. In this case, it(proudly) shows Mr0 in the tooltip that appears.

Our extension, Mr0 has a face now. Hurrah!

We haven't done much till now. In fact we have barely scratched the surface. But as you will see in the next part of the series, we shall slowly build Mr0 and explore the many other files associated while building a chrome extension.

Happy Programming :)
Signing Off


Monday, February 13, 2012

jQuery : Exploring Deferred and Promise

The jQuery Deferred object was introduced as a part of the 1.5 release of the framework. The deferred object in jQuery is based upon the the concept of Promises. In order to understand all about deferred objects, it would wise to try to understand what a Promise is all about.

Many times in our daily lives, we cannot rely on the outcomes of certain actions. However, we may still need to make decisions about the future depending upon an anticipated outcome. All we know for sure is that we are gonna get an outcome. Lets just say that we wrap the term 'outcome' in fancy looking gift wrapper and call it a 'Promise'.

So, what is a 'Promise'? Well, its nothing more than an object returned by a method based upon which you can determine a future course of action.

Lets take a real world analogy.

You decide to take up a job interview for company X - (This is a function that you intend to perform)
The interview has an outcome. You either get the job or you dont.
But you need to have a plan no matter what the outcome of the interview is. And you need to plan that now. You cannot plan it in the future after the interview. For example, you may need to book a travel ticket, ,or may have to book a place for a party if the interview goes through. If it does not go through, then you may have to buy up some books and apply to company Y.

If we were to write this plan programmatically, we would end up writing something like this.

 //Book tickets.
 //Order a crate of beer for a party!
 //Buy some more books to brush up
 //Apply to company Y

Now what is interesting about this is that even though you dont know the exact outcome of the attendInterview function, you are able to chain a method to the 'supposed' outcome and specify the functions that should be invoked upon completion of the 'attendInterview' function. This is possible because the attendInterview function would return a 'Promise' object. An interesting aspect of this pattern is the concept of promise resolution. Promise resolution is said to happen when the task that returns the promise completes in reality. So, when you return a Promise object from the attendInterview function, the Promise is said to be unresolved. Only when the result of the operation is available, i.e. when the actual outcome of the interview is obtained after a period of time, the promise object is said to be resolved. Upon resolution, based upon the result of the resolution, either the successFunction or the failureFunction will be invoked.

The concept of promises is important because of three main reasons 

  1. It helps you to decouple the logic of future handlers from the actual task invocation. 
  2. You can add any number of future handlers. 
  3. If you add a handler to an already resolved Promise, the appropriate(success of failure) function would fire immediately.

The advantages of using a promise become much more clear when used in the context of ajax requests. That's because the result of an ajax request is available at a future point of time, and the amount of time required for the completion of an ajax request cannot be determined beforehand.

jQuery introduced the Deferred object in the 1.5 version of the library to handle this scenario. The Deferred object is actually an implementation of the Promise interface. It provides all the features of a Promise, and in addition, it also allows you to create new deferred objects and attach future handlers to them and resolve them programmatically.

Lets understand the jQuery deferred object in terms of an ajax request.

In versions of jQuery prior to 1.5 , in order to attach a success or a failure handler to an ajax request, one would have declare a success callback function when defining the ajax call. Although much more convenient than the under the covers xmlhttprequest handling, this scheme had one drawback. A function that would be invoked in the future (success or failure) had to be defined as a part of the ajax function. Moreover, one could not attach multiple success or failure handlers to the ajax call.

Here is how one would request using a version of jQuery prior to 1.5

  url: "test.html",
  success: function(){
    alert("ajax request succesful");
  failure: function(){
    alert("ajax request failed");

As shown in the code above, it can be see that you are bound to specify the success function while making the ajax request. Moreover there is only one available callback for success and failure each.

As of jQuery 1.5, the introduction of the Deferred changed the game drastically. And its a progressive change to be honest, because it not only adds more effectiveness to the ajax functionality, but it also adds more functionality to the framework as a whole. We shall see how.

Let us now invoke the same ajax call that we saw earlier using a version of jQuery > 1.5.

var myRequest = $.ajax({  url: "test.html" })
  alert('ajax request was successful');
  alert('ajax request failed');
 //After a few more lines of code
  $('div.myclass').html('Ajax Response ' + data);

As you see, this is far better than the previous method of invocation of the ajax request. The done and fail functions are used to register callbacks on the object returned by the ajax call. The ajax call returns a Deferred object which implements the Promise interface. Since its a promise, you can attach handlers to it so that when the request completes, the future handlers would be invoked.

Not only that, as you see in the example, we were also able to attach a new success handler (the argument to the done function) at a later point of time. If, until reaching that line, the ajax request has not been completed, in that case the function will be queued and will be invoked at a later point of time. If the request is already complete, then the function will fire immediately in case of success. In a similar way, you can add multiple functions as a to the failure queue as well.

This approach gives you a lot of flexibility in writing code and also makes the code more legible. The Deferred object has a number of other functions. One of them that is pretty interesting is the when() function. This function has a lot of appeal because it allows you to group together deferred objects and then set up future handlers after all the objects have been resolved or rejected.

This opens up the door to create interfaces that depend upon input from a number of sources but need to be rendered together. For example, a certain div contains information based upon a user choice. And the user selection leads to the firing of 2 different ajax requests. If your data is of the nature that the information would make sense only if the data from both the requests are shown together, then using the when function becomes a perfect candidate for such scenarios.

In the below example, you can issue a request to two different url's and only after the data from both the url's is retrieved, the future function that is specified as the argument to 'done' will be invoked.

$.when($.ajax("mypage1.html"), $.ajax("mypage2.html")).done(function(a1,  a2){

Observe that there are 2 function calls inside the when function. You can have as many functions as you may like. The only criteria is that the object returned from the function call should be either a Promise or a Deferred. If it is a promise, then well and fine, If it is a Deferred, the promise() function is invoked and the Promise object is retrieved from the deferred object. A parent Deferred object is created and this parent object keeps track of all the deferred objects of the functions defined inside the when function. Once all the functions declared inside the when function resolved, the done function will be invoked. However if any of the functions declared in the when function fails, the failure callbacks are invoked without waiting for the resolution or rejection of the remaining functions.

You can easily use the done and the fail functions to register future callbacks for a deferred object. Another way you can do the same would be to make use of the then function. If you make use of the when - then function combination, it becomes much more easier to read the code, grammatically, because it appears to form some kind of a sentence. Lets see an example of using the when-then pair, and this time we shall also see how one can register multiple callbacks

    function fun1(data1, data2){
        console.log("fun1 : " + data1[0].query + " " + 
        console.log("fun1 : " + data2[0].query + " " + 
    function fun2(data1, data2){
        console.log("fun1 : " + data1[0].query + " " + 
        console.log("fun1 : " + data2[0].query + " " + 
                    data2[0].results.length);    }
    function fun3(data){
        console.log("fun3 called upon faliure");
    function fun4(data){
        console.log("fun4 called upon faliure");
    var successFunctions = [fun1, fun2];
    var failureFunctions = [fun3, fun4];
        $.ajax("", {
            data: {
                q: 'jquery'
            dataType: 'jsonp'
        $.ajax("", {
            data: {
                q: 'blogger'
            dataType: 'jsonp'

In the above example, I created 4 functions. 2 of them will be invoked upon success and 2 will be invoked upon failure. As you can see, instead of passing a single function as a parameter to the then(), I passed in an array of functions for the success as well as the failure callbacks. Another point to be noted here is that since we have 2 ajax requests in the when() function, the success and failure methods can accept 2 arguments. Each argument will contain the jqXhr object that was returned by the corresponding ajax call. So, the above example demonstrates how to use multiple callbacks, and and also how to use the data that is obtained from a json ajax request. 

You may also note that since the ajax functions are making an JSONP request, I have referenced the JSON object in the success callbacks using data1[0] and data2[0] respectively. The data1 and data2 objects are actually arrays of the form [JSONObject, "success",jqXHR]. In case the request was an ordinary ajax request instead of a jsonp request, you would instead have to make use of the jqXHR object and retrieve the responseText as usual. 

Until now we have seen examples where the deferred object was the object that was returned by the ajax call. Although used extensively with ajax, the deferred object can be used in other places as well. An example of that would be running future callbacks after a set of animations have finished executing. You can group together the animations in a when() function and then using a deferred object, you can easily invoke future callbacks using the then() function. 

The catch here is that animations do not return deferred objects. They always return a simple jQuery object. This is where the Deferred constructor comes to the rescue. The deferred constructor can be used to create a new deferred object and then you can wrap your custom code inside the deferred object and return the wrapper instead of the jQuery object. 

Lets see an example for the same. In the following code, we are going to issue an ajax request, and resize a div. After both these tasks are complete, we are going to display the content retrieved via ajax in the div.


    function successFunction(data){
        $('div.animateMe').html('Results : ' + data[0].results.length);
    function animateDiv(){
        //As per the documentation, the argument that is passed
        //to the constructor is the newly created deferred object
        var dfd = $.Deferred(function(dfd){
        return dfd;
    function failureFunction(){
        $.ajax("", {
            data: {
                q: 'jquery'
            dataType: 'jsonp'

You can also see a jsfiddle here

This example is pretty simple because it does nothing but wait for the ajax request as well as the animation to complete before resolving the Deferred object. The main point of interest of this example is the creation of a Deferred object within the animateDiv function. Within this function, we first create a new Deferred object. The constructor of the Deferred object takes a function as a parameter which is invoked just before the constructor is about to return. This function is passed the newly created Deferred object as an argument. Within, this function, we did an animate and upon animation completion, we indicated that the framework resolve the diferred object by passing the resolve function of the diferred object as an argument. In the next line, we simply return the newly created Deferred object.

In the above example, you might have noticed that we made use of a 'resolve' function. This function allows you to explicitly resolve a deferred object. While the ability to resolve a deferred object programmatically is desirable for non ajax requests, the same cannot be said for ajax requests. That's because an ajax request is said to be resolved only when a response is received from the server. So the resolution of an ajax request takes place internally in the ajax function and should not be available to the programmer directly. 

For non ajax requests, as in the example above, the programmer can resolve the deferred object based upon the specific requirement. Since it is the deferred object that has the resolve method and a number of other additional methods, the ajax request actually returns a Promise. This lets you invoke only the methods of the promise interface on the resultant object thereby preventing an explicit invocation of a programmatic resolve before the ajax request actually completes. 

When you are creating an non ajax deferred object, there is another method - reject, which indicates a failure and invokes the functions of the failure queue. Without any doubt, the deferred object has small but useful api. 

Summing It Up

  1. The deferred object in jQuery is an implementation of the Promise specification. This means that you can a promise where-ever a Deferred can be used. 
  2. Future handlers can be added to promise objects. 
  3. The future handlers are invoked upon the resolution(success) or the rejection(failure) of the invoked function. You can attach multiple future handlers to any deferred object. 
  4. The future handlers can receive parameters, which represent the information that was used to resolve the deferred object. 
  5. Non ajax objects can be wrapped in a deferred object by making use of the Deferred constructor. 
  6. The jQuery.when method can be used to group together a number of deferred objects and to attach future handlers to them. 
  7. Success handlers using the when function are invoked once all the deferred objects are resolved. 
  8. Failure handlers using the when function are invoked if any of the deferred object fails irrespective of the status of the remaining deferred objects.

I hope this article has been helpful in helping you gain an understanding of the concept of Promise and Deferred objects. There are a couple of links below that have good explanations of the same. I suggest that you take a look at them too if you still only have a vague idea of things. 

Also, there might be a thing or two, that I might have misunderstood! Make sure you point them out! 
Many thanks :)

Links and References

And then the most important of them all

Happy Programming :)

Signing Off