JS Logo Badges download

UPDATE

Some have asked for a sticker of this badge, so here you go! All proceeds from the sale of this sticker will be donated to TeamJS for Feeding America:

JS Logo Badge Sticker on RedBubble

Resourceful

In REST, URLs are constructed with actions primary revolving around a resource. For example, if we wanted to fetch a user from a server, our URL might look like http://localhost/users/12345, where users is our collection container pointing to the user resource. REST is very popular because URLs are human readable; we can make a pretty good guess of what is happening behind the scenes just by the URL structure.

Making our APIs resource-oriented is very similar to being object-oriented, and so our ultimate goal is for our methods to describe objects and entities, not actions. In many userscripts you might see something like this:

1
2
3
4
5
6
7
8
9
10

var Twitter = {};

Twitter.search = function ( keyword, callback ) {
  // API implementation
};

// And called like so:
Twitter.search( 'lolcats', function ( results ) {
  // Here we can iterate over the tweet results
});

This is supposed to be an API for querying Twitter tweets via JavaScript. While the script may be operational, it is contrary to our goal of being resource-oriented because the method is called search. How can we make this resource-oriented? By describing what we want back, not what we are doing:

1
2
3
4
5
6
7
8
9
10

var Twitter = {};

Twitter.tweets = function ( keyword, callback ) {
  // API implementation
};

// And called like so:
Twitter.tweets( 'lolcats', function ( results ) {
  // Here we can iterate over the tweet results
});

Our API now describes a resources and not an action. Depending on how you form your API, you could change the naming pattern and still be resourceful:

1
2
3
4
5

Twitter.tweets( 'lolcats', handler );

Tweets( 'lolcats', handler );

Tweets.get( 'lolcats', 'handler' );

Now take a moment to look at that last example. You can see that our method call is an action. Isn’t this contrary to what we just said? Not really, because the object we are calling it on directly describes the resource we are getting. Just like in REST, actions (HTTP verbs) determine the representation of a resource; in designing our API we can take advantage of this naming style to improve several aspects of our API.

Readability / Self-Documenting

In the previous paragraph, I mentioned that our naming conventions can improve our API, and one of those aspects is readability. Take this API for instance:

1
2
3
4
5
6
7

Twitter.search( 'lolcats', function ( results ) {
  
  for ( var i = 0, l = results.length; i < l; i++ ) {
      $( '.tweet-container' ).append( results[ i ].message );
  }

});

This single method is doing quite a bit. It performs a search, returns the results, and appends each of those results to the DOM. Readability score: 0. We can design our API better than this:

1
2
3
4
5
6
7

Tweets
  .get( 'lolcats' )
  .done( function ( results ) {
      for ( var i = 0, l = results.length; i < l; i++ ) {
          $( '.tweet-container' ).append( results[ i ].message );
      }
  });

Definitely better. We have split the fetching of results from the processing of the results, and improved the readability of interacting with the API by allowing the results to chain through a Promise-style interface. You could even take this a step further and provide an asynchronous iterating mechanism to process tweets when the results come back. This will save the user from having to build a loop for every call to get tweets:

1
2
3
4
5
6

Tweets
  .get( 'lolcats' )
  .each( function( tweet ) {
      // Ideally you would append this in one chunk, but this is just an example :)
      $( '.tweet-container' ).append( tweet.message );
  });

Very clean and easy to read.

Unobtrusive

Our next goal is to be unobtrusive, and by that I mean leave the user and their code alone:

1. The API should only be accessible through one global variable, which leads to #2:

2. Do not leak variables into the global scope.

3. Provide the user a way to put your API into a no conflict mode.

   If you have a global variable for the fetching of tweets, such as Tweets, allow the user to easily remove the global variable and make it a part of their application. Many APIs do something like this:

    <script src="http://eliperelman.github.com/scripts/tweets.js"></script>
    <script>
        App.tweets = Tweets.noConflict();
    </script>
   

   Calling .noConflict() on the API will remove the Tweets namespace and return all its original functionality, which the consuming application uses to extend their own application. Unobtrusive win.

4. Unless the specific purpose of your API is DOM manipulation, don’t do it.

   With our Twitter API example, avoid forming the API like this:

    Tweets
        .get( 'lolcats' )
        .appendTo( $('#twitter-container')[0] );
   

   Working with the DOM is outside the scope of your API, and even though it may be convenient, your mechanism may not be able to handle all the use cases users may need when working with the DOM. Best to just provide them as easy a mechanism as possible for getting your API data into the DOM.

5. If possible, avoid creating or changing events in userland code. Provide hooks instead.

6. Reduce or eliminate dependencies.

   It is not a good practice to always assume that the user of your API will always have jQuery available or doesn’t need IE7 support. Remember these things when creating your API. The goal is to reduce dependencies, which has positives and negatives. Eliminating dependencies reduces having to manage upgrades and bugs outside your control, keeps users from having to manage this as well, and also opens up the amount of users able to consume your API. If you force your users to have jQuery in order to consume the API, you could lock out many developers who cannot use jQuery or will not for many reasons. It is best to eliminate dependencies as much as possible.

   That being said, having dependencies could reduce the amount of code you need to write, whether that be from offloading tasks to another third-party script or lessen the amount of cross-browser compatibility code. Browser support also comes into play here. Make reasonable decisions on the what browsers you are able to reasonably support up front, and maybe attempt to support more browsers in the future.

Extensible and Granular

I cannot tell you how many times I have used third-party plugins and APIs and not have them work exactly as needed. As a JS API developer, it is almost impossible to forsee all the situations, environments, and quirks that your script may have to work within. API consumers will know much more about their environment than you, so the easiest solution is provide hooks into your API that a user can latch onto and seize control of a situation. Create as many hooks as possible, even though they may not seem valuable to you at the moment. For example, you could use an event-style system to give the API consumer the ability to make changes at critical stages in the pipeline:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Tweets
  .on( 'beforeget', function ( context ) {
      if ( !context.keyword || context.keyword === 'coffeescript' ) {
          context.abort();
      }    
  })
  .on( 'afterget', function ( context ) {
      context.results = context.results.map( function ( tweet ) {
          return tweet.message;
      });
  })
  .on( 'error', function ( context ) {
      console.log( 'Tweet FAIL.' );
  })
  .get( 'lolcats' )
  .each( function ( tweet ) {
      $( '.tweet-container' ).append( tweet );
  });

By providing hooks into the entire lifecycle of a method call in our API, we can allow the user to do incredible processing with easy mechanisms. Integration into existing applications is made much easier if you provide hooks into your API everywhere possible.

Consistency / Conventions

Last but not least, if you adopt a style for your API, make sure that style is consistent across the entire codebase. Users can become very aggravated if they become accustomed to interacting with the API in one way, only to have to switch styles when working on another method from it. Pick a style and stick with it.

Conclusion

Designing JavaScript APIs can sometimes be difficult, but building them in these ways will ensure that you have made your API as friendly, intuitive, and powerful as possible.

Have I missed or would you add anything to this list?

But never fear, Google came up with a scheme to index pages that are normally hidden behind an ajax request. To summarize, by placing a hashbang (#!) in your URL, Google will swap that with a query string identifier of ?_escaped_fragment_= when trying to crawl your pages.

For example, let’s take the Account Registration page built into ASP.NET MVC 3. When creating a new project, on the home page there exists a link to this page: http://mysite.com/account/register. Now, when converting the site to be a single-page application (using ajax to navigate), we need to change the URL that retrieves this page to http://mysite.com/#!/account/register. You then use some sort of JavaScript solution (like Ben Alman’s jQuery BBQ plugin) to handle requests based on the hashchange event.

When Google tries to index the Account Registration page, it will change the URL (since the browser will not send the URL hash to the server for processing) to this: http://mysite.com/?_escaped_fragment_=/account/register. They try to follow the URL, and now it’s up to the server to fetch and return the full page to Google for indexing. I will show you my solution to solving this in ASP.NET MVC 3.

With Global Action Filters in MVC, we have the ability to intercept all responses before it goes to a Controller Action for execution. By doing this, we can check to see if Google’s fragment exists in the URL and reroute as needed. We will start by creating a new class:

1
2
3

public class AjaxCrawlableAttribute : ActionFilterAttribute
{
}

By inheriting from ActionFilterAttribute, we are now able to register our class as a Global Action Filter in Global.asax, but we will handle that later. Let’s keep going by intercepting some requests:

1
2
3
4
5
6

public class AjaxCrawlableAttribute : ActionFilterAttribute
{
  public override void OnActionExecuting(ActionExecutingContext filterContext)
  {
  }
}

By overriding the OnActionExecuting method, we are telling ASP.NET we want to intercept the request BEFORE the request is sent to the Controller for processing. Now we can start to work on the magic:

1
2
3
4
5
6
7
8
9
10
11
12

public class AjaxCrawlableAttribute : ActionFilterAttribute
{
  private const string Fragment = "_escaped_fragment_";

  public override void OnActionExecuting(ActionExecutingContext filterContext)
  {
      var request = filterContext.RequestContext.HttpContext.Request;

      if (string.IsNullOrWhiteSpace(request.QueryString[Fragment]))
          return;
  }
}

First up, we grab the current Request and check the query string to see if it contains Google’s magical fragment identifier. Since the method is going to execute on every request (even child requests), we want to exit this method the moment we know we are not dealing with a search engine.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

public class AjaxCrawlableAttribute : ActionFilterAttribute
{
  private const string Fragment = "_escaped_fragment_";

  public override void OnActionExecuting(ActionExecutingContext filterContext)
  {
      var request = filterContext.RequestContext.HttpContext.Request;

      if (string.IsNullOrWhiteSpace(request.QueryString[Fragment]))
          return;

      var parts = request.QueryString[Fragment].Split(new[] {'/'}, StringSplitOptions.RemoveEmptyEntries);
      var routeValues = new AjaxRoute();

      if (parts.Length > 0)
          routeValues.Controller = parts[0];

      if (parts.Length > 1)
          routeValues.Action = parts[1];

      if (parts.Length > 2)
          routeValues.Id = parts[2];
  }
}

Adding a little more code here, I take the value of the query string parameter and split it on / so that we can have the parts of the URL that determine what action to go to. I have created another class, AjaxRoute, to be a container of these values:

1
2
3
4
5
6

public class AjaxRoute
{
  public string Controller { get; set; }
  public string Action { get; set; }
  public string Id { get; set; }
}

This class has very specific properties, because the names of the properties will be used to determine what route values we need for the routing. Since for this example we are only using the default MVC route, these are the only route parameters we need to set in order to get to the right Controller Action.

To finish this implementation off, we only need one more line, and it’s the line that tells MVC to reroute to the controller matching the route values we have set:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

public class AjaxCrawlableAttribute : ActionFilterAttribute
{
  private const string Fragment = "_escaped_fragment_";

  public override void OnActionExecuting(ActionExecutingContext filterContext)
  {
      var request = filterContext.RequestContext.HttpContext.Request;

      if (string.IsNullOrWhiteSpace(request.QueryString[Fragment]))
          return;

      var parts = request.QueryString[Fragment].Split(new[] {'/'}, StringSplitOptions.RemoveEmptyEntries);
      var routeValues = new AjaxRoute();

      if (parts.Length > 0)
          routeValues.Controller = parts[0];

      if (parts.Length > 1)
          routeValues.Action = parts[1];

      if (parts.Length > 2)
          routeValues.Id = parts[2];

  filterContext.Result = new RedirectToRouteResult(new RouteValueDictionary(routeValues));
  }
}

public class AjaxRoute
{
  public string Controller { get; set; }
  public string Action { get; set; }
  public string Id { get; set; }
}

Setting the filterContext result will now reroute to the proper Controller and return the full view that Google is looking for. One last order of business is to register our attribute as a Global Action Filter, thereby making it execute on every request. Add the following line in the RegisterGlobalFilters method in Global.asax:

1
2
3
4
5
6

public static void RegisterGlobalFilters(GlobalFilterCollection filters)
{
  filters.Add(new HandleErrorAttribute());
  // Add this line here:
  filters.Add(new AjaxCrawlableAttribute());
}

And there you have it! Now every time Google crawls your ajaxified single-page website, it can index each page separately successfully.

REST Introduction Video

Every Developer Has Two Full Time Jobs

REST, or Representational State Transfer, can be thought of as a standard way for two parties to communicate about the actions to take on a resource or set of resources. To understand REST, let’s try to break this down into an analogy.

Resources

Yes, that’s right. Cheese. Cheese, for all intensive purposes, will be our resource. Think of a resource as a noun, an item. Something you can interact with, but not the action itself. Going back to grammar lessons, a noun can be a person, place, thing, or idea. That same principal applies to resources as well.

Verbs

Now, what can you do with cheese? You can make cheese, cut it (pun intended), store it, and yes, even eat it. These are all actions you can take on cheese. HTTP defines a standard set of actions that can be performed against all resources, called verbs, and today I am only going to focus on the four most supported ones: GET, POST, PUT, and DELETE.

URLs

In order to communicate with the server for your cheese interaction, you need to understand how to combine resources and verbs to form a request.

Pluarlity

The generally accepted way to identify a resource action in a URL is to use its plural form. For cheese it would be cheeses, user would be users, radius would be radii, and so on. Keep plurality in mind when forming your URL.

Forming the request

When browsing the internet, each request from page to page is a GET request. This same concept applies to accessing pages RESTfully. For example, if we want to go to a page that contains a list of all our cheeses, the URL would look like this:

Notice there is no action stating we want to get a list like http://localhost/cheeses/getall or something similar. The action is provided by HTTP, so we don’t need to pollute our URL with it. This is what REST is all about.

Making any request, I get back a representation of the resource based on what resource I am requesting and the action I am performing on it. Since I am using my browser, I am using the GET verb to request the cheeses resources. Using that syntax, I should expect that the representation_ would be a list of cheeses, maybe in a table.

Now, let’s access a single piece of cheese:

Notice I am still working with my resource of cheeses, but this time I am providing the name or id of the cheese resource. Using the browser’s address bar will execute this as a GET request, so I will receive a page representation of a single cheese resource, possibly a form for editing this piece of cheese.

jQuery, AJAX, and other verbs

In the earlier days of web development before AJAX (yes, it’s true, it did exist at one point), there was not much of a concept of posting a form asynchronously, e.g. submitting a form would take you to another page. This was accomplished through a combination of a form tag’s action and method attributes. This can still be done in a RESTful manner.

1
2
3
4
5
6
7

<p>

    <form action="/cheeses/13579" method="POST">
        <input type="text" name="age" id="age" value="15 years" />
    </form>

</p>

This will cause all of the data included in the form to be placed in the request body, and submitted to the specified URL. A POST request tells the server that we are either adding to or changing information about a certain resource; we are changing something about our cheese.

This works the same way for AJAX requests as well (I am using jQuery since it is the most ubiquitous):

1
2
3
4
5

$.ajax({
    type: 'post',
    url: '/cheeses/13579',
    data: { age: '15 years' }
});

Matching URLs to resources and actions

In order to effectively form URL in the most standard and maintainable way, it’s going to help to know which URL scheme to use, and where:

Request from the server a list view or many resources for display:

GET http://localhost/cheeses

Request from the server a single resource for display

GET http://localhost/cheeses/13579

Request the server to create a resource:

POST http://localhost/cheeses/13579

Request the server to delete a particular resource:

DELETE http://localhost/cheeses/13579

1
2
3
4

$.ajax({
    type: 'delete',
    url: '/cheeses/13579'
});

Request the server to update particular resource:

PUT http://localhost/cheeses/13579

1
2
3
4
5

$.ajax({
    type: 'put',
    url: '/cheeses/13579',
    data: { name: 'Cheddar', age: '1 day' }
});

Response Codes

Notice above that I specifically said “Request the server” to do something. It is important to know that while you may request something, the server does not have to comply and may decide not to perform your request. Your application must handle this gracefully by reacting to HTTP response codes.

You know them, but maybe you didn’t pay much attention. Every time you visit a page that’s not found, you may see a cute message about it, but the browser was returned a 404 error. That is HTTP’s way of saying that what you requested wasn’t found. If you do happen to land on the page you requested successfully, chances are your browser was sent a 200 response.

When working with jQuery, these codes are abstracted away from you with the success and error handlers:

1
2
3
4
5
6
7
8
9
10
11
12
13

var request = $.ajax({
    type: 'post',
    url: '/cheeses/13579',
    data: { age: '15 years' }
});

request.success(function(data, textStatus, jqXHR) {
    // take action if successful
});

request.error(function(jqXHR, textStatus, errorThrown) {
    // take action if failed
});

The success methods are generally executed if the HTTP response was successful, for example if there was a 200, 302, or 304 response. The error function would be called in other instances such as 400 or 500 range responses.

Your ability to handle these responses in a RESTful application are very important. Fortunately jQuery provides an easy way to take different courses of action for different status codes (if necessary):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

var handle200 = function(data, textStatus, jqXHR) {
    // take action if successful
};

var handle404 = function(jqXHR, textStatus, errorThrown) {
    // take action if failed
});

var request = $.ajax({
    type: 'post',
    url: '/cheeses/13579',
    data: { age: '15 years' },
    statusCode: {
        200: handle200,
        404: handle404
    }
});

With the statusCode object we can take different courses of action based on certain HTTP response codes. Any function can be assigned to a status code, and the arguments provided to it are based on the same criteria used to call one of the success or error methods we would have called before.

Some types of requests may return successful if the request was received successfully but the specific action may not have been immediately performed or is queued up for later execution as is often the case for DELETE requests. You may tell the server to delete a resource, and it may respond saying it was successful, only for you to find out later that nothing was actually deleted.

Understanding this is key: requesting the server to do something is not a guarantee that you will get what you ask for. That’s why it’s called a request. You cannot force the server to do something, and you should assume that it may not. The resiliency of your application will be determined on how you handle the cases where the server does not do as you ask. What may be even more difficult is handling the cases where the server may return something other than what you asked for. Having HTTP response codes will help your application handle each of these cases if you ever run across them or need that level of granularity.

Overview

Using REST in your code will ultimately improve the maintainability of your application, as having a simple, readable, and standard way to access and manipulate resources will assure routes stay decoupled and consistent. Remember to keep URLs descriptive of a resource, and let your verbs determine the action to take.

But all too often, while I do see JavaScript written well organizationally, it is still technically written prodecurally. Take this for instance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// Car constructor function
var Car = function(isNew, color) {
    if (!(this instanceof Car)) {
        return new Car();
    }

    this.isNew = isNew;
    this.color = color;
};

// later on:
var car = Car(true, 'green');

if (!car.isNew) {
    getCarWash(car);
} else {
    driveCarAround(car);
}

What’s the problem?

Now you may be thinking, what is the problem with having code like this? The answer is maintainability. If in another part of your application you decide you need to create a car and take a similar action, you must repeat this conditional logic.

The problem stems partially from having easy access to the properties of this object. By having instant access to the properties of this object, your program can look at an object and decide on an action to take. From an object-oriented standpoint, this is bad, because now the object does not manage its own state and actions, but rather the application does.

Is there a better solution?

Of course. When crafting objects its important to provide methods so they have ability to manage their own state (properties) and actions (methods). Let’s rework our example just a tad to see how this could be simply done:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// Car constructor function
var Car = function(isNew, color) {
    if (!(this instanceof Car)) {
        return new Car();
    }

    this.isNew = isNew,
        color = color;
};

Car.prototype.getWashed = function() {
    if (!this.isNew) {
        // do washing functionality
    }
};

Car.prototype.driveAround = function() {
    if (this.isNew) {
        // driving functionality
    }
};

// later on:
var car = Car(true, 'green');

car.getWash();

car.driveAround();

What’s the difference?

The way this example differs from our previous one has to do with who manages when things happen. In each of the snippets, the cars are checked for newness before they get washed. The improvement again lies in its maintainability. If you have other code in the future that instantiates a car, you can call getWash() without fear having to determine whether the car gets washed or not. The car takes care of that for you. That is the power of object-oriented programming as opposed to procedural. Let your objects determine if they need to take action, and leave the application to do other things.

Maintenance will be easier in the future, I promise.

1
2
3
4
5

var func = function(val) {
  if (val === undefined) {
    // do something
  }
};

because I want the code to look like this:

1
2
3
4
5

var func = function(val) {
  if (typeof val === 'undefined') {
    // do something
  }
};

which causes an argument which goes something like this:

Me: Why are you comparing against undefined? You DO know that third party code can inadvertently change the value of undefined, right?

Person: Of course, but my code is contained in a function which redefines undefined to undefined, so it’s all good?

Me: But that won’t work in the global scope.

Person: True, so while in the global scope, I use typeof val === 'undefined'.

Me: So now your code is inconsistent.

Person: But that’s the way the jQuery style guide says to do it…

And on it goes. In almost any book which speaks of coding conventions, it states that no matter which convention you decide to use, make sure that the convention is strictly adhered to so that code is more readable and maintenance is easier.

But now we have an interesting situation with the creators of the most popular JavaScript framework on earth advocating two different coding styles based solely on whether your code is contained in a function or not:

“Expected an identifier and instead saw ‘undefined’ (a reserved word).” - In jQuery we re-declare ‘undefined’ as we use it internally. Doing so prevents users from accidentally munging the name (assigning to undefined and messing up our tests) and also makes the undefined checks slightly faster.

• Global Variables: typeof variable === “undefined”
• Local Variables: variable === undefined
• Properties: object.prop === undefined

Source: jQuery Core Style Guidelines

Now obviously they are correct in their first method of using typeof to make sure a variable is undefined, because the value of undefined can be changed at any time by any code since in legacy browsers the undefined variable is just that: a variable. ECMAScript 5 compatible browsers (and hence JavaScript running in “strict mode”) forces the undefined variable to be “read only”, although it does this silently (without throwing an error).

The problem is that they adopt a different convention within their own internal code by comparing directly against undefined because they have created their own “internal” undefined variable:

1
2
3

(function( window, undefined ) {
  // jQuery source
})(window);

By not passing a value to the second argument, it has effectively created its own copy of undefined, and can now go on their way to comparing against it directly.

The question arises: why have two different coding styles? They claim speed. Is that justified?

In running my own tests over at jsperf.com, it looks as though in some browsers comparing directly against undefined is a little faster but only marginally. What is interesting is that in Chrome comparing against the typeof value === 'undefined' test is waaaaaay faster than comparing directly value === undefined. If you don’t believe me head on over to jsperf.com and try it out.

So, since the speed difference is negligible in some browsers and in fast much slower in Chrome, is it worth maintaining two different coding conventions for a speed argument that isn’t really there? I say no. Consistency is much more important. But even the jQuery Core isn’t even perfectly consistent. Take a look at this line from the jQuery source for the .data method:

1

if ( typeof key === "undefined" ) {

They are type-checking instead of a direct comparison, in direct contrast with the style guidelines.

So this is my point: jQuery Core, please do away with checking directly against undefined. It is only marginally faster in some browsers, much slower in Chrome, and makes the source inconsistent.

The first article was by Thomas Fuchs, Prototype.js team member and script.aculo.us creator, and it argued the perils of large, underutilized frameworks (e.g. jQuery). The article boils down to this:

I for one welcome our new micro-framework overlords—small frameworks and libraries that do one thing only, not trying to solve each and every problem, just using pure JavaScript to do it. Easy to mix and match, and to customize to your needs.

Now the article did make some good points, but I came away from it feeling that his assertion is that large frameworks are essentially evil.

The next day I read an article (Imagine a Beowulf Cluster of JavaScript Frameworks) with an opposing viewpoint by Tom Dale, a SproutCore team member (SproutCore is a large library), which argues that Thomas Fuchs’ ideas sound nice, but they aren’t practical for the reason that amassing several smaller dependencies in software as opposed to one large dependency doesn’t really solve anything, and in fact can introduce problems of incompatibility. It recommended that larger frameworks should be used instead of several smaller ones.

So who is right?

I decided to broach the subject with my colleague, Nate Taylor, to get his thoughts, and he made an excellent point:

Neither of these positions is correct. Holding to one viewpoint may not be the correct choice in every situation.

That’s right, neither viewpoint should be constantly adhered to. In good software engineering, it’s important to always evaluate the tools needed to do the job well and efficiently. If you are writing a large scale application, chances are you are going to need a more fully-featured JavaScript application stack to get the job done, whereas a small mom-and-pop website may only benefit from a few helping libraries.

So come away from these two articles with this: there’s no need to demonize large OR small frameworks, don’t pit them against each other. Rather, carefully evaluate what tools are best suited to solve your problem for the current situation and I guarantee that the decision you come to will be the correct one, whether it’s a large framework or several micro-frameworks.

Now, when jQuery 1.5 came out with the changes to ajax that included the Deferred syntax, it soon became apparent that our current implementation of the ajax wrapper was no longer suitable. With deferred methods available from anywhere, we could no longer control the data that became the arguments of those methods.

Today, I’ll go over how I solved this problem, by creating a new wrapper around jQuery’s $.ajaxwith the new $.Deferred. I’ll keep this generic enough for you to be able to use for your own purposes.

First, let’s start with our application’s ajax module: Application.ajax. I want to be able to pass it an object of options just like jQuery’s ajax:

1
2
3

Application.ajax = function(options) {

};

Next, our ajax wrapper needs to be able to call the deferred methods just like jQuery’s ajax, so let’s create a Deferred object and return a promise.

1
2
3
4
5
6
7
8
9

Application.ajax = function (options) {
  var deferred = $.Deferred(function (d) {
      // implementation going here
  });

  var promise = deferred.promise();

  return promise;
};

Even though we are returning a Deferred, we don’t have those cool .success and .error methods. We need those on our ajax too, and all they really do is just map to the .done and .fail methods of the Deferred’s promise. A little syntactic sugar is all we need; for simplicities sake we’ll add these methods directly to the promise:

1
2
3
4
5
6
7
8
9
10
11
12
13

Application.ajax = function (options) {
  var promise = $.Deferred(function (d) {
      // implementation going here
  });

  var promise = deferred.promise();

  promise.success = deferred.done;
  promise.error = deferred.fail;
  promise.complete = deferred.done;

  return promise;
};

Cool, things are starting to come together. Basically we are telling our deferred that when the success method is called, execute the same function that the Deferred uses for done. Same thing goes for error and complete.

Continuing on the implementation, let’s get a unified settings object so we can get ready for a request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Application.ajax = function (options) {
  var deferred = $.Deferred(function (d) {
      var defaults = {
          cache: false,
          type: 'post',
          traditional: true,
          dataType: 'json'
      },
      settings = $.extend({}, defaults, options);

      d.done(settings.success);
      d.fail(settings.error);
      d.done(settings.complete);
  });

  var promise = deferred.promise();

  promise.success = deferred.done;
  promise.error = deferred.fail;
  promise.complete = deferred.done;

  return promise;
};

What’s going on here? First, I am creating a new settings object which is a merger between our predefined default options and the options argument, with the arguments passed in taking preference. Then we take our three ajax callbacks (success, error, and complete) and attach them using the native deferred methods, effectively attaching them to our Deferred when it resolves.

The code I am going to write next is a little application specific, but the process will remain the same: create new settings which get passed to the native $.ajax and override the success, error, and complete methods. Each of these methods needs to resolve the deferred in a certain manner:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

Application.ajax = function (options) {
  var deferred = $.Deferred(function (d) {
      var defaults = {
          cache: false,
          type: 'post',
          traditional: true,
          dataType: 'json'
      },
      settings = $.extend({}, defaults, options);

      d.done(settings.success);
      d.fail(settings.error);
      d.done(settings.complete);

      var jqXHRSettings = $.extend({}, settings, {
          success: function (response, textStatus, jqXHR) {
              if (settings.dataType === 'json') {
                  if (response && response.success) {
                      d.resolve(response.data);
                  } else {
                      d.reject(response.data);
                  }
              } else {
                  d.resolve(response);
              }
          },
          error: function (jqXHR, textStatus, errorThrown) {
              console.log(jqXHR);
              d.reject(jqXHR);
          },
          complete: d.resolve
      });

      if (!Application.clientValidates()) {
          d.reject();
      } else {
          $.ajax(jqXHRSettings);
      }
  });

  var promise = deferred.promise();

  promise.success = deferred.done;
  promise.error = deferred.fail;
  promise.complete = deferred.done;

  return promise;
};

Our implementation is complete. For this application, I am creating my settings for my ajax request, and overriding the status callbacks to implement my own custom logic. I also do a little client-side validation, which will not even make the ajax request, and instead, reject the deferred and call the registered error callbacks. If the request goes through, then in the success method, I am checking if the request is JSON. If so, see if the response returned from the server was successful and resolve our Deferred, thereby executing all the .done callbacks. If there was a failure, call the .fail callbacks and so on.

We are now free to register as many success or error callbacks as we want, just like $.ajax, but now we also have the power to have our own logic and data passed to those methods as our applications see fit.