Brandon Aaron

Understanding the Context in jQuery

Brandon Aaron — Wed, 24 Jun 2009 19:20:09 +0000

When selecting elements jQuery has an optional second argument called context. This context provides a means to limit the search within a specific node. This is great when you have a very large DOM tree and need to find, for example, all the <a> tags within a specific part of the DOM tree. I’ve seen various articles, usually performance related, stating that you should be using a context for your selectors. While it is true that using a context for your selectors can potentially boost performance, most of these articles misuse the context.

Finding the Context

As of jQuery 1.3 the context is exposed as a property on the jQuery collection. Here is how you can check to see what the context is.

$('a').context; // => document

Running the above code shows that the context is the document element. In fact, the default context for all jQuery collections is the document in which jQuery was loaded. In other words, selectors are run against the whole document by default.

Changing the Context

The context needs to be a node to work properly. This is the part that is often overlooked. I’ve overlooked it in the past as well. Lots of examples out there tell you to just pass a second selector to jQuery to act as the reference node for the search. While this seems to work, it is still running the search on the whole document.

Here is an example of passing a second selector as the context. By looking at the context property you can see that the context is still the document though.

$('a', '#myContainer').context; // => document

When jQuery encounters another selector for the context it actually converts it to say the following instead.

$('#myContainer').find('a');

This conversion also happens the same way if you pass a jQuery collection as the context.

Now lets actually look at how we can change the context for the jQuery collection.

// get the node for the context
var context = $('#myContainer')[0];

// pass the context as the second argument
$('a', context).context; // => <div id="myContainer">

From this example we can see that passing a node as the second argument actually changes the context for the jQuery collection.

jQuery 1.3.3 and .live()

In jQuery 1.3.x, the .live() method binds its event handlers to the document. In the upcoming jQuery 1.3.3 release the .live() method will bind its events to the context of the jQuery collection. This means your .live() events can be more focused and potentially faster.

Automating with Special Events

Brandon Aaron — Wed, 17 Jun 2009 15:44:26 +0000

David Walsh had a great idea to coerce an element that is given a click event to have a pointer for its cursor. The pointer is a universal symbol for users to know that something is clickable. Using this technique it would be “automatic” that any element given a click event would have a pointer. David set out to use the Special Event hooks within jQuery to make this work. Unfortunately for David those hooks are not widely documented, so his first attempt was unsuccessful. So, lets see how we can use the Special Event hooks to make this work as desired.

If you haven’t done so, I recommend reading the Special Events blog post which explains what special events are and how to use them. In the upcoming jQuery 1.3.3 there will be two more event hooks.

The Special Event

The code, once you understand the Special Event hooks, is fairly straight forward. When a click event is bound to an element, we want to make sure it has a pointer for its cursor. Here is what the code looks like to make this work.

jQuery.event.special.click = {
    setup: function() {
        jQuery( this ).css( 'cursor', 'pointer' );
        return false;
    },

    teardown: fuction() {
        jQuery( this ).css( 'cursor', '' );
        return false;
    }
};

So lets break this small piece of code down. There are two hooks, setup and teardown, that are called once per an element. In the setup hook we add the CSS rule to make the cursor a pointer and in the teardown hook we revert the change since it is no longer clickable. The teardown hook is only called after the last click event is unbound.

The only difference here from David’s example is the return false statements in both hooks. The return value in Special Event hooks is particularly important (and easy to overlook). Special Events assume that you will most likely handle the actual binding of the event yourself. In other words, when you don’t return false jQuery skips the actual native binding (addEventListner or attachEvent) of the event to the element. In this particular case we want jQuery to go ahead and run its native binding code so the event is actually registered with the browser. To do this we need to return false from our hooks.

Usage

Using the same example from David’s post, the actual usage stays the same. Just bind a click event handler as you normally would using either .bind() or .click().

jQuery( document ).ready(function( $ ) {
    $( '#click-me' ).click(function() {
        var red   = Math.floor( Math.random() * 256 ),
            green = Math.floor( Math.random() * 256 ),
            blue  = Math.floor( Math.random() * 256 ),
            color = 'rgb(' + red + ',' + green + ',' + blue + ')';
        $( this ).css( 'background', color );
    });
});

You can see this in action here.

Enhancement

There is one enhancement that I’d like to recommend. Instead of adding the styles via JavaScript, lets just add a class name instead. Maybe the name could be “clickable”. Then we can add a rule in our CSS that says anything with the class of “clickable” should have a pointer. This would make it easier to style specific instances of a clickable element. For example, we could add a three pixel blue border to a clickable image. :) So, the final special event with this enhancement would look like this.

jQuery.event.special.click = {
    setup: function() {
        jQuery( this ).addClass( 'clickable' );
        return false;
    },

    teardown: fuction() {
        jQuery( this ).removeClass( 'clickable' );
        return false;
    }
};

And in our CSS we would need to add a global rule that adds the pointer to .clickable elements.

.clickable { cursor: pointer; }

Now we can specialize our .clickable class to handle certain elements differently.

img.clickable { border: 3px solid blue; cursor: pointer; }

Last thought…

I had one last thought about this technique. This should not be a replacement for using semantic markup or using progressive enhancement. Most of the time if something should be clickable it should probably be clickable and actually do something when JavaScript is not available.

jQuery Edge: New Special Event Hooks

Brandon Aaron — Thu, 04 Jun 2009 01:05:18 +0000

In jQuery 1.3.3 there are two new special event hooks: add and remove. These two hooks, unlike setup and teardown, are called for each event being bound. The add hook receives the handler, data, and namespaces as arguments. The remove hook receives the data and namespaces as arguments. The add and remove hooks enable the creation of more complex, even customizable, events.

If you haven’t done so, I recommend reading the Special Events blog post which explains what special events are and how to use them. For the following example I assume you already understand the concept of special events in jQuery.

As an example I’m going to build a new special event called “multiclick”. This event tracks clicks on an element and fires at a given threshold or number of clicks. The required number of clicks will be customizable per a handler.

First, here is how you’d use the multiclick event.

$('div')
    .bind("multiclick", { threshold: 5 }, function( event ) {
        alert( "Clicked 5 times" );
    })
    .bind("multiclick", { threshold: 3 }, function( event ) {
        alert( "Clicked 3 times" );
    });

Now lets build it. The skeleton of the multiclick special event looks like this.

jQuery.event.special.multiclick = {
    add: function( handler, data, namespaces ) {
        // called for each bound handler
    },

    setup: function( data, namespaces ) {
        // called once per an element
    },

    remove: function( namespaces ) {
        // called for each bound handler
    },

    teardown: function( namespaces ) {
        // called once per an element
    },

    handler: function( event ) {

    }
};

Behind the scenes we’ll need to use a normal click event. We’ll use the setup hook to bind the initial click event to track the actual clicks. The handler method will be used to properly trigger the multiclick events. Once all the multiclick events are removed, the teardown hook will be triggered. We’ll need to unbind the the click event we used to track the clicks in the setup hook. Here is the updated multiclick event.

jQuery.event.special.multiclick = {
    add: function( handler, data, namespaces ) {
        // called for each bound handler
    },

    setup: function( data, namespaces ) {
        jQuery( this ).bind( "click", jQuery.event.special.multiclick.handler );
    },

    remove: function( namespaces ) {
        // called for each bound handler
    },

    teardown: function( namespaces ) {
        jQuery( this ).unbind( "click", jQuery.event.special.multiclick.handler );
    },

    handler: function( event ) {
        // set correct event type
        event.type = "multiclick";
        // trigger multiclick handlers
        jQuery.event.handle.apply( this, arguments );
    }
};

Next we need to make sure the bound function to a multiclick event isn’t fired until it reaches the number of clicks specified. We’ll utilize the add hook for this. The add hook has the ability to return a function which will take the place of the provided handler. This is a powerful feature and allows us to do all sorts of fun things with special events. In the case of the multiclick event we are going to return a new function that calls the given handler after the specified number of clicks. Here is the add hook.

jQuery.event.special.multiclick = {
    add: function( handler, data, namespaces ) {
        // get the required number of clicks from data
        var threshold = data && data.threshold || 1,
            // number of clicks
            clicks = 0;

        // return a new function that will become the handler
        return function( event ) {
            // increase number of clicks
            clicks += 1;
            if ( clicks === threshold ) {
                // required number of clicks reached, reset
                clicks = 0;
                // call the actual supplied handler
                handler.apply( this, arguments );
            }
        }
    },

    ...
};

The add hook makes use of closures to keep track of the required number of clicks (threshold), the actual number of clicks, and the handler to be called once the required number of clicks is reached. The jQuery event system keeps everything in tact so that when you call unbind with the same named function that you supplied to bind, it still unbinds it as expected.

It ends up that we don’t actually need to use the remove hook for this special event, so we’ll just remove it. Thats it. The multiclick special event is done. You can see it in action here and the complete code follows.

jQuery.event.special.multiclick = {
    add: function( handler, data, namespaces ) {
        // get the required number of clicks from data
        var threshold = data && data.threshold || 1,
            // number of clicks
            clicks = 0;

        // return a new function that will become the handler
        return function( event ) {
            // increase number of clicks
            clicks += 1;
            if ( clicks === threshold ) {
                // required number of clicks reached, reset
                clicks = 0;
                // call the actual supplied handler
                handler.apply( this, arguments );
            }
        }
    },

    setup: function( data, namespaces ) {
        jQuery( this ).bind( "click", jQuery.event.special.multiclick.handler );
    },

    teardown: function( namespaces ) {
        jQuery( this ).unbind( "click", jQuery.event.special.multiclick.handler );
    },

    handler: function( event ) {
        // set correct event type
        event.type = "multiclick";
        // trigger multiclick handlers
        jQuery.event.handle.apply( this, arguments );
    }
};

Thanks

Thanks to Mike Helgeson who helped evolve the special events API to include these two hooks. He also has a handful of special events that he has created: drag, drop, hover, and wheel.

If you knew about the specialAll event hook, it has been removed in favor of using these two extra hooks.

jQuery Edge: Simplified .hover()

Brandon Aaron — Thu, 28 May 2009 16:56:46 +0000

In jQuery 1.3.3 the .hover() method will optionally accept a single method instead of always requiring two methods. This allows you to contain your logic within one method instead of duplicating it among two. I don’t know about you but I’ve avoided using the .hover() method in favor of just manually binding the mouseenter and mouseleave events so that I could use a single function to handle both events. So, lets look at a typical use-case for hover.

$('li')
    .hover(function(event) {
        $(this).addClass('test');
    }, function(event) {
        $(this).removeClass('test');
    });

Now, this is how I’d typically handle this without the use of .hover().

$('li')
    .bind('mouseenter mouseleave', function(event) {
        $(this).toggleClass('test');
    });

Now lets use the new functionality of .hover() instead of manually binding the events.

$('li')
    .hover(function(event) {
        $(this).toggleClass('test');
    });

Sweet!

Sometimes though you’ll need to do more complex interactions than just toggling a class. In these cases you can simply check the event type that is passed to your handler. When the user mouses over, the event type sent to the hover function will be mouseenter. When the user mouses out, the event type sent to the hover function will be mouseleave. Here is an example checking the event type.

$('li')
    .hover(function(event) {
        $(this)[ (event.type == 'mouseenter') ? 'add' : 'remove') + 'Class' ]('test');
    });

In the above example I’m still just toggling the class on the element that was hovered over/out but doing so in a more verbose way to illustrate how you can check the event type.

jQuery Edge: Better Support for other Windows and Documents

Brandon Aaron — Thu, 14 May 2009 11:22:00 +0000

jQuery in the past hasn’t always played well with other windows and documents than the one it was loaded in. However, jQuery is moving in the right direction to help ease the pain of cross window/frame development. There have been several commits recently that make previously window/document dependent methods, well… less dependent. So far .bind(), .css(), .width(), and .height() have all been updated to work with other windows and documents.

So, how might you use this new found jQuery power? First, if you didn’t already know jQuery has a method, called .contents(), that when used on an iframe element returns the document of the iframe.

// Get a reference to the iframe document
var iframeDoc = $('iframe').contents().get(0);

Now we can bind an event to it, get the dimensions, get styles of various elements, etc.

// Get width of iframe document
$(iframeDoc).width();

// Get height of iframe document
$(iframeDoc).height();

// Bind event to iframe document
$(iframeDoc).bind('click', function( event ) {
    // do something
});

// Get the style of an element in the iframe
$('div', iframeDoc).css('backgroundColor');

Simple as that.

jQuery Edge: Bind with a Different "this"

Brandon Aaron — Tue, 12 May 2009 10:50:00 +0000

Brand new to jQuery SVN is the oft-requested feature of providing a different value for the “this” object in an event callback. Previously jQuery would always send the element as the value of “this” in the callback. You can utilize this new feature by passing the object you’d like to represent “this” in the callback as the last argument to either .bind() or .live(). Lets look at some example code!

The typical use-case for this functionality is that you’ll have an object (or a class) and you want to call a method of that class when you click on a particular element. However, the “this” object inside the method will be set to the element the event happened on. Usually in these situations you’d want the “this” object to represent the instance of your class, not the element. Here is an example that tries to illustrate this use-case.

// Create a class
var MyClass = function() {
    // initialize the class
    this.clicked = false;
    this.element = null;
};
MyClass.prototype.click = function( event ) {
    // handle the click event on an element
    // the "this" object should represent the instance of
    // the class, not the element the event happened on.
    // the element can be retreived using the event.target
    // or event.currentTarget

    // set the clicked property to true
    this.clicked = true;

    // set the element property to the element that was clicked
    this.element = event.target;

    // cancel the event
    return false;
};

// Create an instance of MyClass
var myInstance = new MyClass();

// Bind an event that calls the click method of myInstance
// and make sure the "this" object is set to myInstance
$("li").live("click", myInstance.click, myInstance);

As you can see from the example code the actual element the event happened on can still be retrieved via the event.target or event.currentTarget properties. Both of these properties are normalized/fixed to work cross-browser (as is the event.relatedTarget property). In the example above I used the live method of binding events but the same applies for the bind method.

jQuery Edge: Live Events now with Data

Brandon Aaron — Fri, 08 May 2009 10:22:00 +0000

In jQuery 1.3.3 the .live() method will have the ability to pass data along just like you might do with .bind(). The .bind() (and now .live()) method takes an optional second argument called “data”. The data can then be accessed within the event handler by using the event.data property. Here is what the code would look like to use this feature.

// The data
var eventConfig = {
    selectedClass: "selected"
};

$("li").live("click", eventConfig, function( event ) {
    // Retreive selectedClass from the event data
    var selectedClass = event.data.selectedClass;

    // Toggle the class amongst the siblings
    $(this).addClass( selectedClass )
        .siblings().removeClass( selectedClass );
});

So in the previous example, trivial as it may be, each time you click an “li” element the selected class defined in the eventConfig is assigned to the clicked element and removed from the siblings.

jQuery Edge: Versatile .index()

Brandon Aaron — Thu, 07 May 2009 11:05:00 +0000

Paul Irish and ajpiano (via Google Groups) saw an opportunity to make the .index() method work better for them. Currently the .index() method looks for a given element within the jQuery collection. However, they wanted a quick way to get the index of the current element amongst its siblings. Here is the scenario they laid out.

$("#sometable th img").click(function() {
    // Need to find out the index of the <th>

    // get the <th>
    var $th = $(this).parent();

    // find the index, two options with jQuery 1.3.2
    var index = $("#sometable th).index($th);
    var index = $th.parent().children().index($th);
});

Both options in 1.3.2 aren’t horrible but it could be a little more straightforward. With the new functionality to be in 1.3.3, you could do the following instead.

$("#sometable th img").click(function() {
    // find out index of img's parent <th> in its own <tr>
    var index = $(this).parent().index();
});

By not passing anything to the .index() method, it will look for the first matched element of the jQuery collection within its siblings. So in the case of the above example we first select the image, then grab its parent (which is the <th>), and finally call .index() which looks at its siblings to find its index among the other <th> elements.

That isn’t the only new functionality though. You can also supply a selector to indicate which elements it should search within. For example we could find the index of the clicked image among all the images like this.

$("#sometable th img").click(function() {
   // find the index of the image among all images
   var index = $(this).index("img"); 
});

jQuery Edge: Enhanced .toggleClass()

Brandon Aaron — Wed, 06 May 2009 09:35:00 +0000

In jQuery 1.3.3 the .toggleClass() method will have a couple more modes of operation. Currently in jQuery 1.3.2 the .toggleClass() method can only toggle one class name at a time. The new .toggleClass() method will be able to toggle multiple class names and will also be able to toggle all the classes on or off. Here are the different ways you’ll be able to use .toggleClass().

// With the following element
// <div class="a b c"></div>

// Toggle all classes
$('div').toggleClass();        // <div class="" />
$('div').toggleClass();        // <div class="a b c" />
$('div').toggleClass( false ); // <div class="" />
$('div').toggleClass( true );  // <div class="a b c" />

// Toggle multiple classes
$('div').toggleClass( "a b" );          // <div class="c" />
$('div').toggleClass( "a c" );          // <div class="a" />
$('div').toggleClass( "a b c", false ); // <div class="" />
$('div').toggleClass( "a b c", true );  // <div class="a b c" />

By calling .toggleClass() without passing any class names, it will toggle all the current classes on the element. To toggle multiple class names, just separate the class names with a space. The optional boolean can force the removal (false) or force the addition (true) of the class names.

Special Events

Brandon Aaron — Thu, 26 Mar 2009 01:57:10 +0000

jQuery, since 1.2.2, has had an API for “special events”. These events are special because they have the ability to do some extra work for specific events and even the option to bypass some of the internal jQuery event system. With these special events you can create custom events that require some setup work or you can completely overwrite the behavior of native events.

We use special events in jQuery to create the “mouseenter” and “mouseleave” events. In addition to those two events we used it to make the “ready” event and I use it to normalize the “mousewheel” event in the mouse wheel plugin.

A Special Event: “tripleclick”

To illustrate the API I’m going to create a new event type called “tripleclick”. To be fired it will require the user click the element three times. If we were to make this a typical jQuery plugin we would create jQuery.fn.tripleclick. However, I want to be able to take advantage of the bind syntax along with the other benefits like event normalization, data, and namespaces that the jQuery event system provides.

The first thing we need to do is create the special event. Each special event has a setup and a teardown method. The setup method gets called when the event is bound and the teardown method gets called when the event is unbound.

It is important to note that these two methods only get called the first time an event of a particular type is bound/unbound per an element. This is because the jQuery event system actually only binds one handler per an event type per an element and manages the other bound handlers itself. In jQuery 1.3 there is a new special event type called “Special All” that operates for all handlers but has a slightly different behavior. However, that is for another article.

The skeleton of our “tripleclick” special event looks like this.

jQuery.event.special.tripleclick = {
    setup: function(data, namespaces) {
        var elem = this;
    },

    teardown: function(namespaces) {
        var elem = this;
    }
};

Notice that the setup event gets passed the data and namespaces that were used when binding the event. Also that the teardown event gets passed the namespaces that were used when unbinding the event. Although, they are only marginally useful here since this is the data and namespaces associated with the very first event handler bound to a particular element. But you could use the data to configure the event for all the handlers of that type for an element. The scope, or the value of this, for these two methods is the element the event is being bound to.

Behind the scenes we are actually going to utilize the native “click” event to keep track of the number of clicks on an element. We’ll also need a handler that actually does the heavy work of keeping track. I’m going to add a third method called handler to the tripleclick special event. To make the code a little more simple I’m going to track the number of clicks on an element by using the jQuery data API.

The updated tripleclick special event looks like this.

jQuery.event.special.tripleclick = {
    setup: function(data, namespaces) {
        var elem = this, $elem = jQuery(elem);
        $elem.bind('click', jQuery.event.special.tripleclick.handler);
    },

    teardown: function(namespaces) {
        var elem = this, $elem = jQuery(elem);
        $elem.unbind('click', jQuery.event.special.tripleclick.handler);
    },

    handler: function(event) {
        var elem = this, $elem = jQuery(elem), clicks = $elem.data('clicks') || 0;
        clicks += 1;
        if ( clicks === 3 ) {
            clicks = 0;
            // set event type to "tripleclick"
            event.type = "tripleclick";
            // let jQuery handle the triggering of "tripleclick" event handlers
            jQuery.event.handle.apply(this, arguments)
        }
        $elem.data('clicks', clicks);
    }
};

To quickly break down the handler code. First we get the number of clicks via the data API and increment the number by 1. Then we check to see if it has been clicked 3 times. If so, we then need to reset the number of clicks and trigger the other event handlers as the comment indicates. Finally, we store the new value for the number clicks on the element via the data API.

The handler has to set the event type to “tripleclick” because behind the scenes we actually use a click event. jQuery uses the event type to know which handlers it should call and we want it to call the event handlers for our “tripleclick” event.

The Example

We can now use our special event just like we’d use any other event via the bind method. For example to bind a “tripleclick” event to all divs we’d write the following code.

jQuery('div').bind('tripleclick', function(event) {
    alert('triple clicked');
});

You can see an example of this new special event in action here.

You could enhance this event by requiring all three clicks to be within a certain timeframe. You could achieve this by also storing the event.timeStamp property of the previous click and comparing the distance between it and the latest click.

The `return` Value

I mentioned in the beginning of this article that a special event had the ability to bypass some of the internal jQuery event system. The functionality that can be skipped is the actual binding of the event to the element using the addEventListener or attachEvent methods. This functionality is skipped based on the return value. Any value other than false prevents jQuery from actually binding the event to the element. In other words if you add return false to the setup and teardown methods of your special event, it will actually use the native DOM APIs to bind the event to the element. In the case for our “tripleclick” event we didn’t want to actually bind the event to the element using the native DOM APIs so we didn’t return anything (undefined).