Sergio Pereira : jQuery, GuidedTour

Guided Tour: jQuery - Array wannabes

sergiopereira — Wed, 23 Dec 2009 05:13:00 GMT

This post is part of a series called the Guided Tours.

In this second installment we are still looking inside the jQuery code. Trust me, even if it's hard to digest, you can still learn enough if you focus on a little bit at a time.

The code we are interested in today is the following.

//from jQuery 1.3.2
get: function( num ) {
	return num === undefined ?

		// Return a 'clean' array
		Array.prototype.slice.call( this ) : 

		// Return just the object
		this[ num ];
},

That's the code for the command jQuery.fn.get(index), which returns the element at the given index or the entire array if the index is omitted.

The JavaScript idiom that is really interesting in this function is that strangely long function call Array.prototype.slice.call( this ).

That line is needed because we need to return an array and, even though they look like one, the jQuery objects aren't arrays. And they aren't alone in that.

If it walks like a duck...

The Array object is one that we can't avoid becoming familiar with in JavaScript. They are everywhere. Data is passed to functions as arrays. Data is returned in arrays. Or are they?

Aside from jQuery objects there are at least two other important occurrences of data structures that are used like arrays but really aren't: the arguments variable and the DOM NodeList collections.

The arguments variable is the list of parameters passed to the current function and the NodeList is what is returned from members of the the DOM API such as document.getElementsByTagName() or element.childNodes. Both of these types have a length property and expose their items with indices, like arguments[1] or elements[0].

But don't let this small coincidence fool you. As soon as you stop paying attention and try to use another array method, like push, shift, join you'll have your dreams shattered and a TypeErrorto handle.

Help me, jQuery

To solve the above problem and return a real array object instead of the jQuery object itself, the code used the technique we highlighted.

Array.prototype.slice.call( this )

The idea is to use the array.slice() instance method to create a new array. The slice method returns a chunk of the array and it takes two optional parameters (the boundaries) that, when omitted, make the function return a copy of the array itself.

I've written about the prototype object and how to invoke functions with call in previous posts, so I won't repeat myself here. I'll just add a reminder that the this object in the get method is the jQuery instance we're working with.

What's going on in call( this ) is that slice is being invoked as if it was a method of the jQuery object (note: the jQuery object does have a method called slice but it does not return an array.)

You may be wondering how can we pass a jQuery object to slice.call() and not get any errors inside the method implementation. Well, it works because the slice method was built to be generic and it only needs that the current object has a length property and items in indexed positions. That's Duck Typing at work.

A Freebie

There's a small variation of this technique that you may come across in JavaScript as well.

[].slice.call( this )

It calls the same slice method but in a tad more wasteful manner because a new Array instance is created each time just to provide access to its slice method.

Well, that's it. I hope you don't scratch your head any longer when you see an expression like XYZ.prototype.someMethod.call(obj) from now on.

Guided Tour: jQuery - guard and default operators

sergiopereira — Wed, 09 Dec 2009 10:50:00 GMT

This post is part of a series called the Guided Tours.

I'm sure I'm not alone when I say that one of the best ways to improve our coding skills is by reading code written by someone else. Sometimes we don't realize how lucky we are to have so much source code at our fingertips, namely Open Source Software.

The guided tours

With this post I'll start another unbound series where I highlight some interesting piece of code that I studied. I'll share my notes and do my best to explain what I learned from it.

jQuery: Eating the elephant one bite at a time

I wouldn't dare to start things off with a complete overview of jQuery. It's a massive chunk of JavaScript and I'm afraid there isn't an easy entry point in the source code.

I chose to find parts of it that are relatively easy to explain separately from the rest and that contain something worth explaining. I'll do at least a few of those from jQuery but my plan is to not keep this series tied to jQuery or even JavaScript.

The code under the microscope

We're going to take a look at jQuery.fn.text(), which returns the textual content of all the elements in the jQuery wrapped set, combined in a single string.

Here's the code from jQuery version 1.3.2.

text: function( text ) {
  if ( typeof text !== "object" && text != null )
    return this.empty().append( 
	   (this[0] && this[0].ownerDocument || document).createTextNode( text ) 
	);

  var ret = "";

  jQuery.each( text || this, function(){
    jQuery.each( this.childNodes, function(){
      if ( this.nodeType != 8 )
        ret += this.nodeType != 1 ?
          this.nodeValue :
          jQuery.fn.text( [ this ] );
    });
  });

  return ret;
},

The text() function can be called with or without arguments, so initially it tries to detect if a string argument was passed to it, in which case it will be made the content of the elements in the jQuery object.

Be aware that in all methods defined inside jQuery.fn the value of this will be the current jQuery object.

The first thing that caught my attention was the following expression:

(this[0] && this[0].ownerDocument || document)

In the context of the code it's expected to return a DOM document object, but it's a boolean expression, isn't it? What gives?

Well, yes, it is a boolean expression. That leads me to explain a subtle but powerful difference between boolean operators in JavaScript to many other languages you may be more used to.

Guard and Default operators

The way I like to describe the boolean operators && and || is: They return the operand that short-circuited and resolved the expression. To put in a different way, when the JS interpreter detects that one of the operands has a value that makes the remainder of the comparison irrelevant, it stops right there and that operand (not necessarily true or false) becomes the result of the boolean expression.

Truthy and Falsy: In the context of a boolean expression, any value in JavaScript has a boolean meaning. It's actually easy to memorize which mean which. The values that are treated as false are: false, null, undefined, 0, "" (empty string), and NaN. We call them falsy. Everything else is treated as true and we call them truthy.

Here are some examples:

A	B	A && B
`false`	`123`	`false`
`null`	`123`	`null`
`0`	`123`	`0`
`undefined`	`123`	`undefined`
`undefined`	`null`	`undefined`
`123`	`null`	`null`
`123`	`456`	`456`
`123`	`"text"`	`"text"`
`"text"`	`true`	`true`

A	B	A \|\| B
`false`	`123`	`123`
`null`	`123`	`123`
`0`	`123`	`123`
`undefined`	`123`	`123`
`undefined`	`null`	`null`
`123`	`null`	`123`
`123`	`456`	`123`
`123`	`"text"`	`123`
`"text"`	`true`	`"text"`

Because of the above behavior, these boolean operators are often used as Guard or Default operators. The guard operation is commonly used when you want to avoid a null or undefined reference error:

//someObj can be null. text will also be null in that case.
var text = someObj && someObj.toString();

Which is a shorthand for:

var text = null;
if (someObj !== null) {
  text = someObj.toString();
}

The default operation is arguably a much more common occurrence. We see it a lot when functions support optional arguments with default values. When a value is not given for a function parameter, it becomes undefined. We can detect that and give a default value like this:

function addAll(numbersArray, step) {
  step = step || 1;
  var sum = 0;
  for (var i = 0; i < numbersArray.length; i += step) {
    sum += numbersArray[i];
  }
  return sum;
}
addAll([1, 2, 3, 4, 5, 6]); // ==> 21
addAll([1, 2, 3, 4, 5, 6], 3); // ==> 5

In the above example, the step parameter is optional. Not providing it would cause a problem if we hadn't defaulted it to one right at the beginning of the function.

Wow. We sure covered a lot of stuff just to explain a simple boolean expression. The good news is that we will see a lot of that in the jQuery code (or in pretty much any decent JS code base) so it's good to understand it well.

Back to our original expression.

(this[0] && this[0].ownerDocument || document)

Armed with our new understanding we can finally read this expression as: If this.ownerDocument exists I want that, otherwise just give me the global document object. This returned DOM document object will be the owner document of new text value being inserted.

What about the rest of that function

It's funny that a tiny bit of that function became this long post. But the remainder of the function, in its majority, isn't really all that interesting in terms of JavaScript. It's mostly boring DOM navigation, done recursively. If you know how to use the jQuery.each() utility function, you can figure out that code on your own.

Our time here is up and we have a whole lot more of code sightseeing to do.