Deferreds, new in jQuery 1.5, decouple logic dependent on the outcome of a task from the task itself. They’re nothing new to the JavaScript scene; Mochikit and Dojo have implemented them for some time, but with Julian Aubourg’s AJAX rewrite landing in 1.5, deferreds in jQuery was the logical next step. With deferreds, multiple callbacks can be bound to a task’s outcome, and any of these callbacks can be bound even after the task is complete. The task in question may be asynchronous, but not necessarily.

What’s more, deferreds are now built-into $.ajax() so you’ll get them automatically. Handlers can now be bound like this:

// $.get, an ajax request, is asynchronous by default.
var req = $.get('foo.htm')
   .success(function( response ){
      // do something with the response
   })
   .error(function(){
      // do something if the request failed
   });
 
// this might execute before the $.get() above is complete
doSomethingAwesome();
 
// something additional to execute upon success, which might, or might not,
// have fired by now.  With $.ajax deferreds built-in, it doesn't matter.
req.success(function( response ){
   // do something more with the response
   // this will fire when success normally fires, or fire immediately
   // if prior success callbacks have already fired
});

We are no longer limited to one success, error, or complete handler anymore, and instead of simple callback functions, these hooks are now self-managed first-in, first-out callback queues.

As shown in the example above, callbacks may be attached even after the AJAX request – or any observable task – has completed. For code organization this is great; the days of long unwieldy callbacks may be over. It’s almost as if $.queue() meets pub/sub.

Digging a little deeper here, imagine a scenario where we want to call a function after several concurrent AJAX requests have completed. This is easily accomplished with $.when(), deferred’s little helper method:

function doAjax(){
   return $.get('foo.htm');
}
 
function doMoreAjax(){
   return $.get('bar.htm');
}
 
$.when( doAjax(), doMoreAjax() )
   .then(function(){
      console.log( 'I fire once BOTH ajax requests have completed!' );
   })
   .fail(function(){
      console.log( 'I fire if one or more requests failed.' );
   });

View this example on jsFiddle

The reason this works is because all of jQuery’s AJAX methods now return an object containing a "promise", which is used to track the asynchronous request. The promise is a read-only view into the result of the task. Deferreds look for the presence of a promise() method to determine whether an object is observable or not. The $.when() waits for all its AJAX requests to execute, and once they do, the callbacks attached to the $.when() via .then() and .fail() will fire as appropriate (depending on task’s success or failure state). The callbacks fire in the order they were assigned.

It gets better: all deferred’s methods accept either functions or arrays of functions, so you can build your behaviors and assign them all with one call, or in separate calls, as you please.

$.ajax() returns an object packed with other deferred-related methods. I discussed promise(), but you’ll also find then(), success(), error(), and a host of others. You don’t have access to the complete deferred object, though; only the promise, callback-binding methods, and the isRejected() and isResolved() methods, which can be used to check the state of the deferred.

But why not return the whole object? If this were the case, it would be possible to muck with the works, maybe pragmatically "resolve" the deferred, causing all bound callbacks to fire before the AJAX request had a chance to complete. Therefore, to avoid potentially breaking the whole paradigm, only return the dfd.promise().

Registering Callbacks

In the examples thus far I’ve used the then(), success(), and fail() methods to register callbacks onto the deferred, but there are more methods available to you, especially when working with AJAX deferreds. The method you choose ultimately depends on the resolution state(s) you’d like to bind to.

Available to all deferreds (AJAX, $.when, and those created manually):

.then( doneCallbacks, failedCallbacks )
.done( doneCallbacks )
.fail( failCallbacks )

AJAX deferreds have three additional methods, two of which map to one of the above. They are provided as semantic alternatives and match the names of the "old" handlers we’re all used to:

// "success" and "error" map to "done" and "fail" respectively.
.success( doneCallbacks )
.error( failCallbacks )

You can register a complete handler that’ll fire regardless of the success or failure state of the request. Unlike success and error, complete is actually an alias to the done method of a separate deferred. This separate deferred, created internally by $.ajax(), is resolved after an AJAX request completes, regardless of the outcome.

.complete( completeCallbacks )

Therefore, the following three examples are equivalent (success reads better than done in the context of an AJAX request, don’t you think?)

$.get("/foo/").done( fn );
 
// same as:
 
$.get("/foo/").success( fn );
 
// same as:
 
$.get("/foo/", fn );

Creating your own Deferred

We know that $.ajax and $.when implement the deferred API internally, but you can also create your own implementations:

function getData(){
   return $.get('/foo/');
}
 
function showDiv(){
    var dfd = $.Deferred();
 
    $('#foo').fadeIn( 1000, dfd.resolve );
 
    return dfd.promise();
}
 
$.when( getData(), showDiv() )
    .then(function( ajaxResult ){
        console.log('The animation AND the AJAX request are both done!');
 
        // 'ajaxResult' is the server's response
    });

View this example on jsFiddle

Inside showDiv() I’m creating a new deferred object, performing an animation, and returning the promise. The deferred is resolved (think of dequeue() if you’re familiar with jQuery’s queuing methods) after the fadeIn() call completes. Between the time the promise is returned and the deferred is resolved, a then() callback is registered to the successful completion of both asynchronous tasks. Therefore, once both tasks resolve, the callback is fired.

getData() returns an object with a promise method, which allows $.when() to observe its eventual resolution. The manually steps we took to return a promise in showDiv() is handled for us internally by $.ajax() and $.when().

function showDiv(){
    var dfd = $.Deferred();
 
    $('#foo').fadeIn( 1000, dfd.resolve );
 
    return dfd.promise();
}
 
// same as:
 
function showDiv(){
    return $.Deferred(function( dfd ){
        $('#foo').fadeIn( 1000, dfd.resolve );
    }).promise();
}

Defer your Deferreds

We could take this one step further by registering individual callbacks to both getData() and showDiv(), as well as registering their individual promises onto one "master" deferred.

If you wanted something to happen on the success of getData() and on the success of showDiv() (independently of the other), as well as on the success of both getData() and showDiv() combined, simply register a callback to their individual deferreds, and tie them together with $.when:

function getData(){
   return $.get('/foo/').success(function(){
      console.log('Fires after the AJAX request succeeds');
   });
}
 
function showDiv(){
    return $.Deferred(function( dfd ){
        $('#foo').fadeIn( 1000, dfd.resolve );
    }).promise();
}
 
$.when( getData(), showDiv() )
    .then(function( ajaxResult ){
        console.log('Fires after BOTH showDiv() AND the AJAX request succeed!');
 
        // 'ajaxResult' is the server’s response
    });

View this example on jsFiddle

Chaining Hotness

Deferred callbacks can be chained so as long as a promise is returned from the function. Here’s a real world example (via @ajpiano!)

function saveContact( row ){
   var form = $.tmpl(templates["contact-form"]),
      valid = true,
      messages = [],
      dfd = $.Deferred();
 
   /*
      bunch of client-side validation here
   */
 
   if( !valid ){
      dfd.resolve({
         success: false,
         errors: messages
      });
   } else {
      form.ajaxSubmit({
         dataType: "json",
         success: dfd.resolve,
         error: dfd.reject
      });
   }
 
   return dfd.promise();
};
 
saveContact( row )
   .then(function(response){
      if( response.success ){
         // saving worked; rejoice
      } else {
         // client-side validation failed
         // output the contents of response.errors
      }
   })
   .fail(function(err) {
      // AJAX request failed
   });

The saveContact() function first validates the form and saves the result into the variable valid. If validation fails, the deferred is resolved with an object containing a success boolean and an array of error messages. If the form passes validation, the deferred is resolved, except this time the success handler receives the response from the AJAX request. The fail() handler responds to 404, 500, and other HTTP errors that could prevent the AJAX request from succeeding.

Non-observable Tasks

Deferreds are particularly useful when the logic to execute may or may not be asynchronous, and you want to abstract that condition out of the mainline code. Your task might return a promise, but it might also return a string, object, or some other type.

In this example, the first time a "launch application" link is clicked on, an AJAX request tells the server to record (and return) the current timestamp. The timestamp is stored in the element’s data cache after the AJAX request is complete. The application only cares about the initial first click though, so on subsequent clicks, the timestamp is read out of the data cache instead of making an additional trip to the server.

function startTask( element ){
   var timestamp = $.data( element, 'timestamp' );
 
   if( timestamp ){
       return timestamp;
   } else {
       return $.get('/start-task/').success(function( timestamp ){
           $.data( element, 'timestamp', timestamp );
       });
   }
}
 
$('#launchApplication').bind('click', function( event ){
   event.preventDefault();
 
   $.when( startTask(this) ).done(function( timestamp ){
       $('#status').html( '<p>You first started this task on: ' + timestamp + '</p>');
   });
 
   loadApplication();
});

When $.when() recognizes that its first argument doesn’t have a promise (and therefore is not observable), it creates a new deferred object, resolves it with the data, and returns the promise from the deferred. As such, something arbitrary without an initial promise can be observed.

One small gotcha to be aware of (which will most likely be addressed in the next maintenance release), is that you cannot defer an object that implements it’s own promise method. Deferreds are detected by the presence of a promise method, but jQuery doesn’t check to see if the promise actually returns a usable object. Therefore, this will throw a syntax error:

var obj = {
   promise: function(){
      // do something
   }
};
 
$.when( obj ).then( fn );

Conclusion

Deferreds introduce a new, robust approach to writing asynchronous tasks. Instead of focusing on how to organize callback logic into a singular callback, you can assign several individual actions to callback queues knowing that these will be executed, in context, without worrying so much about synchronicity. The info here might be a lot to digest, but once you get the hang of it, I think you’ll find writing asynchronous code to be much easier with deferreds.

Many thanks to Steven Black for editing this post, as well as the #jquery-dev crew for reinforcing my understanding of deferreds. Adam hooked me up with a sweet example, too.

Related posts:

1. A Recursive setTimeout Pattern

Within jQuery UI’s widget factory exists a little method called $.widget.bridge, which acts as a middle man between the object created with $.widget and the jQuery API. Because bridge is a public function you do not need jQuery UI or any other part of the widget factory to use it. This is awesome and i’mma show you how.

What the widget factory calls "bridge" is an important pattern that affords us modularity and loose couping. Both Alex Sexton and Justin Meyer do an excellent job explaining it, and I highly recommend you become familiar with this design pattern if you’re not already.

$.widget.bridge does a few things:

• Connects a regular JavaScript object to the jQuery API.
• Automatically creates instances of said object and stores it within the element(s) $.data cache.
• Allows option changes after initialization.
• Allows calls to public methods.
• Prevents calls to private methods.
• Prevents method calls on uninitialized objects.
• Protects against multiple initializations.

jQuery UI widgets are created using $.widget("foo.bar", {}); syntax to define an object from which instances will be created. Given a DOM structure with five .foo‘s, $('.foo').bar(); will create five instances of your "bar" object. $.widget.bridge works inside the factory by taking your base "foo" object and giving it a public API, so that you can create instances by writing $('.foo').bar(), and call methods by writing $('.foo').bar('baz').

However, the object passed into $.widget.bridge can be your own, not one that was created with $.widget(). But first, bridge has to make a few assumptions about your code for all this to work correctly:

1. Your object must have both an option and an _init method. Initialiation logic goes in _init, and logic to change an option after initilization goes in option.
2. Your option method returns the current instance. If you attempt to re-initialize an instance on an element, option is called first, and immediately chained to that is _init.
3. Your constructor accepts two arguments: options, an object of configuration options, and element, the DOM element this instance was created on.

That said, let’s create an object:

Now hook it up to the bridge:

All this functionality and $.widget.bridge is less than 50 lines of code. Here’s a link to the source so you can study how it works.

Also, view source on this page by jQuery UI core member Scott Gonzales. His code on that page walks through the $.widget.bridge concept and illustrates how to use it.

Related posts:

1. Tips for Developing jQuery UI 1.8 Widgets
2. jQuery UI MultiSelect Widget
3. A jQuery UI Growl/Ubuntu-like Notification Widget

A recent requirement of mine was to convert large CSV files to XML, and then build an accompanying interface to update & manage the data.  jQuery was most useful for traversing & manipulating the large DOM’s, but I did run across a few gotcha’s worthy of discussion.  There doesn’t seem to be much info on the interwebs about XML and jQuery outside of an XHR request, so here’s what I picked up along the way.

You cannot pass an XML string to jQuery’s constructor

Well technically you can, but it’s not supported and jQuery will not treat the string as XML. You’ll still be working with an HTML document object. jQuery has no idea/doesn’t care that the elements are not valid HTML elements though, so this might be just fine as long as your XML remains detached from the DOM. To feed XML to jQuery correctly, you must pass a parsed XML string (a la XML object) to jQuery’s constructor.

A new feature ticket exists to add cross-browser XML compatibility to jQuery, whose summary yields another good nugget of info:

As documented, the $(“<html string>”) method only supports parsing HTML strings, but users often try to parse XML strings with it. This doesn’t work since jQuery uses the .innerHTML property for parsing and implicitly enforces HTML rules on the string. IE in particular will throw errors or misparse XML strings passed to $() in this way.

Furthermore, the second you try to pass any sizable XML or HTML string to jQuery’s constructor, Firefox 3 is going to fail with a “script stack space quota is exhausted” error (see the bug report filed with Mozilla).

As Dave Methuin (core team member) explains:

Firefox seems to be dying on the constructor check for HTML, which uses a RegExp?:

match = quickExpr.exec( selector );

The string you’re passing in is long and html-ish, and I suspect Firefox is backtracking heavily trying to match the huge string. We can either assume a long (>1K chars) string must be HTML or come up with a RegExp? that doesn’t need to backtrack so much.

So how do you convert a string to an XML object? It depends on your browser.

Parse an XML string into a DOM

The following only applies if you’re manually parsing an string. If using XMLHttpRequest the browser does all this automatically – just use the responseXML property.

To re-iterate, jQuery alone is not capable of parsing XML strings. You will need to leverage the DOM parsing method baked into the browser, which all support in one form another. Firefox, Chrome, and Safari have a DOMParser object, and IE uses their proprietary ActiveX object. To create a cross-browser solution:

This snippet checks for the absence of DOMParser in the window scope, and if true, defines it. If the browser has an ActiveXObject (IE), the MLXML.DomDocument method is used to convert the string to an DOM. If ActiveXObject isn’t present but XMLHttpRequest is (fail-safe), a pseudo AJAX request is created and the parsed string is returned in the responseXML property of XMLHttpRequest.

Now that we have a normalized DOMParser, parsing XML is easy:

Converting an XML DOM back to a string

Again, IE has a different implementation than everyone else, but it’s still trivial to normalize. Firefox/Chrome/Safari use the XMLSerializer.serializeToString method, whereas IE has an “xml” property on the XML object.

$.data() is unreliable

First a note on how $.data actually works. When jQuery is loaded, $.expando is set to the current timestamp prefixed with “jQuery”. Expando becomes the name of a property set on elements when data is added via $.data/$.fn.data. The expando’s value is a UUID and acts as jQuery’s link back to the proper store in $.cache – where the data is actually stored. Each key in the $.cache object is the UUID.

That said, the ActiveX object that IE uses for XML parsing has issue with jQuery trying to set expando properties on elements. And instead of working around this issue, it appears that the solution will be to document the fact that $.data doesn’t work cross-browser on XML documents.

Therefore, avoid setting data on XML documents.

getElementById will always return null

If part of your performance plan involves setting id attributes to leverage the speed of getElementById, think again. getElementById does not work on XML documents.

As documented in Mozilla’s MDC:

DOM implementation must have information that says which attributes are of type ID. Attributes with the name “id” are not of type ID unless so defined in the document’s DTD. The id attribute is defined to be of ID type in the common cases of XHTML, XUL, and other. Implementations that do not know whether attributes are of type ID or not are expected to return null.

“ID” is a data type, and in an XML document, the browser has no clue that an attribute named “id” should be interpreted as such. The same applies for the class attribute and getElementsByClassName, but have no fear; getElementsByTagName (and querySelector/querySelectorAll in modern browsers) will continue to work as expected.

jQuery’s Sizzle (and probably all other selector engines) account for this, so $("#id") will continue to work as expected.  Just don’t expect the same performance as getElementById.

The only benefit I see to passing raw XML to jQuery(), without parsing it into an XML DOM first, is the fact that getElementById will continue to work.  I still wouldn’t recommend it though.

$.isXMLDoc()

This little utility method exists for testing whether or not a DOM node is within an XML document:

Useful when you want to be certain you’re correctly passing an XML DOM to jQuery.

No XML love in WebWorkers

Initially, part of my performance strategy in this project was to leverage WebWorkers to avoid locking up the main UI thread.  After consulting the brilliance at Bocoup, Rick Waldron noted that XHR objects used within workers will only return responseText, and never responseXML. This is by design as responseXML is not considered thread safe.  The DOMparser object is not available inside workers either, so unless you want to roll your own XML parser (hint: you don’t) do not try to request or parse XML.

References

Most of these links are scattered throughout this post, but if you want them all in one place:

• jQuery ticket for “Error ‘script stack space quota is exhausted’” error
  http://dev.jquery.com/ticket/6796
• Mozilla ticket for “Error ‘script stack space quota is exhausted’”
  https://bugzilla.mozilla.org/show_bug.cgi?id=579656
• jQuery ticket for $.data fails on XML documents in IE
  http://dev.jquery.com/ticket/6890
• MDC DOMParser Object
  https://developer.mozilla.org/en/DOMParser
• MDC XMLSerializer Object
  https://developer.mozilla.org/en/XMLSerializer
• MDC getElementById
  https://developer.mozilla.org/en/document.getElementById
• jQuery’s constructor API documentation
  http://api.jquery.com/jQuery/
• $.isXMLDoc() API documentation
  http://api.jquery.com/jQuery.isXMLDoc/
• Add cross-browser XML support to jQuery – feature enhancement ticket
  http://dev.jquery.com/ticket/6693

If you know of any other XML gotcha’s, please leave them in the comments below!

This is the successor and port of my original jQuery MultiSelect Plugin to a jQuery UI widget. While both will actively be maintained, I highly recommend you use this version over the plugin version. It has a more robust feature set, is faster, and is much more flexible. MultiSelect turns an ordinary HTML select control into an elegant drop down list of checkboxes with themeroller support.

This version inherits all the benefits from the jQuery UI widget factory that are not available in the plugin version. The most requested feature was the ability to call methods on instances after initialization (e.g., statefullness), and now there are 10 to choose from! Also present are eight events you can bind to, which in the previous version, had fewer and limited support. Finally, there is support for effects. Just include the jQuery UI effects dependency and specify the name of the opening or closing effect to use (and speed, if you wish!)

• Current version: 1.12 (11/26/2011 – changelog)
• View demos.
• Download source or minified, and the CSS file.
• Follow this project on GitHub.
• Run the unit tests.
• Please report any bugs on the issue tracker.

Demo

See what you’re missing out on? Many more demos are available here.

$("#multiselect-demo").multiselect({
   selectedText: "# of # selected"
});

Advanced usage using optgroups and the filtering extension:

$("#multiselect-demo")
   .multiselect({
      noneSelectedText: 'Select car/boat manufacturers'
      selectedList: 4
   })
   .multiselectfilter();

Usage

Using this widget is simple. First, include the following files:

• jQuery 1.4.2+
• jQuery UI 1.8 widget factory and effects (if you’d like to use them)
• A jQuery UI theme
• This widget: jquery.multiselect.js
• The CSS file: jquery.multiselect.css

Next construct a standard multiple select box. Do not forget the multiple attribute:

<select id="example" name="example" multiple="multiple">
<option value="1">Option 1</option>
<option value="2">Option 2</option>
<option value="3">Option 3</option>
<option value="4">Option 4</option>
<option value="5">Option 5</option>
</select>

Finally, initialize the widget on the select box once the document is ready:

$(document).ready(function(){
   $("#example").multiselect();
});

See the demos for advanced usages and for more documentation!

Options

To further customize multiselect, pass in a object with one or more of the options below.

// example:
$("select").multiselect({
   header: "Choose an Option!"
});

/* button */
.ui-multiselect.myClass {}
 
/* menu */
.ui-multiselect-menu.myClass {}

Events

Hook into any of the events below by either binding to the event name, or passing in the name of the event during initialization:

// bind to event
$("#multiselect").bind("multiselectopen", function(event, ui){
	// event handler here
});
 
// or pass in the handler during initialization
$("#multiselect").multiselect({
	open: function(event, ui){
		// event handler here
	}
});

$("#multiselect").bind("multiselectoptgrouptoggle", function(event, ui){
	/*
	event: the original event object, most likely "click"
 
	ui.inputs: an array of the checkboxes (DOM elements)
        inside the optgroup
 
        ui.label: the text of the optgroup
 
        ui.checked: whether or not the checkboxes were
        checked or unchecked in the toggle (boolean)
	*/
});

$("#multiselect").bind("multiselectclick", function(event, ui){
	/*
	event: the original event object
 
	ui.value: value of the checkbox
	ui.text: text of the checkbox
	ui.checked: whether or not the input was checked
        or unchecked (boolean)
	*/
});

Methods

After an instance has been initialized, interact with it by calling any of these methods:

// example:
$("#multiselect").multiselect("method_name");

Filter Plugin

A filtering widget is available which, once initialized on a multiselect instance, will insert a text box inside the widget header. Typing in the input will filter rows and return matches in real time. To view a demo, download, or read the documentation, head to the demo page.

How do I…?

These questions came out of the comments which others will probably find useful:

Set default options for all multiselect instances?

$.ech.multiselect.prototype.options.selectedText = "# of # selected";

Retrieve all selected values?

var values = $("select").val();

var array_of_checked_values = $("select").multiselect("getChecked").map(function(){
   return this.value;	
}).get();

Retrieve values on the server?

Prevent the selectedList option from increasing the button’s height?

.ui-multiselect { height:25px; overflow-x:hidden; padding:2px 0 2px 4px; text-align:left }

Manually check or uncheck a checkbox?

// manually check (or uncheck) the third checkbox in the menu:
$("select").multiselect("widget").find(":checkbox").each(function(){
   this.click();
});

Show checked values on another part of my page?

Use multiselect in conjunction with the validate plugin?

Issues

If you find any issues, please report them using the GitHub issue tracker. Thanks!

Related posts:

1. jQuery MultiSelect Plugin w/ ThemeRoller Support
2. Using $.widget.bridge Outside of the Widget Factory
3. A jQuery UI Growl/Ubuntu-like Notification Widget

The livequery plugin allows us to bind events and general logic to all current and future elements. After the inclusion of live() in 1.3, an expansion of supported live event types in 1.4, and the introduction of delegate() in 1.4.2, the livequery plugin has more or less become deprecated. However, it still holds a special place in my heart because of it’s ability to listen for the creation of new elements.

Listening for new elements is most useful when you want to apply logic, like initializing a plugin, to elements that will be added via AJAX. Without livequery, this is easily accomplished by re-binding logic at the point where elements are injected:

// apply a plugin to all current div.foo's
$("div.foo").somePlugin();
 
// do some ajax
$.get("bar.htm", function( response ){
 
	// bind the plugin to the new element, and insert it into the DOM
	$(response).somePlugin().appendTo("body");
});

If you have multiple points of entry, however, this syntax can quickly become hard to maintain and is not very DRY. Livequery allows you to bind it once and forget about it:

// apply somePlugin to all current and future div.foo's
$("div.foo").livequery(function(){
	$(this).somePlugin();
});
 
// do some ajax
$.get("bar.htm", function( response ){
	$(body).append( response );
 
	// somePlugin will be applied to any additional 
	// div.foo's present in "response" automagically
});

To me the appearance of a new element always seems like an event, and it would be cool if this was something you could bind to. The idea here is that once jQuery injects an element into the DOM, any handlers attached to the element’s selector would fire. Luckily, most of jQuery’s DOM manipulation methods (append, prepend, after, before, etc.) eventually funnel down into the $.fn.domManip method. With this in mind, I duck punched $.fn.domManip, added a new “create” special event, making this type of syntax possible:

// when a new div.foo element enters the DOM, call somePlugin() on it.
$("div.foo").live("create", function(){
	$(this).somePlugin();
});

To see a demo of this, click here. The only manipulation method $.fn.domManip does not cover is $.fn.html, so this method is hijacked as well.

And the code (download on GitHub):

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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

// version 1.3 - 07/03/2010
 
(function($, _domManip, _html){
   var selectors = [], gen = [], guid = 0, old = {};
 
   $.event.special.create = {
      add: function( data ){
         selectors.push( data.selector );
      },
 
      // won't fire in 1.4.2 http://dev.jquery.com/ticket/6202
      remove: function( data ){
         var len = selectors.length;
 
         while( len-- ){
            if( selectors[len] === data.selector ){
               selectors.splice(len, 1);
               break;
            }
         }
      }
   };
 
   // deal with 99% of DOM manip methods
   $.fn.domManip = function( args, table, callback ){
 
      // if no create events are bound, just fire the original domManip method 
      if( !selectors.length || $.isFunction(args[0]) ){
         return _domManip.apply( this, arguments );
      }
 
      return logic.call( this, _domManip, arguments );
   };
 
   // deal with the remaining 1% (html method)
   $.fn.html = function( value ){
 
      // if no create events are bound, html() is being called as a setter,
      // or the value is a function, fire the original and peace out.  only string values use innerHTML;
      // function values use append() which is covered by $.fn.domManip 
      if( !selectors.length || $.isFunction(value) || value === undefined ){
         return _html.apply( this, arguments );
      }
 
      // make value an array
      arguments[0] = [value];
      return logic.call( this, _html, arguments );
   };
 
   function logic( method, args ){
      var node, nodes = args[0], html = $(), numSelectors = selectors.length, matches = [];
 
      // crawl through the html structure passed in looking for matching elements.
      for( var i=0, len=nodes.length; i< len; i++ ){
         node = $(nodes[i]);
 
         (function walk( element ){
            element = element || node[0].parentNode;
            var cur = (element ? element.firstChild : node[0]);
 
            while(cur !== null){
               for( var x=0; x<numSelectors; x++ ){
                  if( $(cur).is(selectors[x]) ){
                     if( !cur.id ){
                        cur.id = "jqcreateevt"+(++guid);
                        gen.push(cur.id); // remember that this ID was generated
                     }
 
                     // remember this match
                     matches.push(cur.id);
                  }
               }
 
               walk( cur );
               cur = cur.nextSibling;
            }
         })();
 
         // the html we started with, but with ids attached to elements
         // bound with create.
         html = html.add( node );
      }
 
      // overwrite the passed in html with the new html
      args[0] = html;
 
      // inject elems into DOM
      var ret = method.apply(this, args);
 
      // for elements with a create event...
      $.each(matches, function(i,id){
         var elem = document.getElementById( id );
 
         if( elem ){
            // cleanup generated IDs
            if( $.inArray(id, gen) !== -1 ){
               elem.removeAttribute("id");
            }
 
            // double check to make sure the event hasn't already fired.
            // can happen with wrap()
            if( !$.data( elem, "jqcreateevt") ){
                $.event.trigger("create", {}, elem);
               $.data(elem, "jqcreateevt", true);
            }
         }
      });
 
      return ret;
   }
 
})(jQuery, jQuery.fn.domManip, jQuery.fn.html);

In a nutshell, I’m creating a new special event called “create”, which simply stores the selector used when binding the event into an array. Next, I hijack both $.fn.domManip and $.fn.html methods to walk through any HTML passed in looking for elements with a bound create event. If any matches are found, each element is given a unique ID (if one does not already exist), stored in the matches array, and the original $.fn.domManip method is called to actually inject the HTML into the DOM. Now that the nodes exist in the DOM and not just in a variable, I loop through the matches array, find each element with getElementById, and the trigger the create event. If the element had to be assigned a unique ID it is removed.

Usage Notes

A few notes on how to use this thing/how it works:

• The event must be bound with live() or delegate() because of the way these methods hold onto the this.selector property. This code uses this.selector to determine if injected elements match the elements bound to create.
• If you attempt to do any DOM manipulation with $(this) inside the event handler, you’ll trigger infinite recursion.
• Elements must enter the DOM through one of jQuery’s DOM manipulation functions, or a method that calls it (append, prepend, after, etc.). It won’t work using vanilla JavaScript.
• Don’t forget that you can return false to prevent this event from bubbling.
• If no “create” events have been bound, $.fn.domManip or $.fn.html is called straight up without the extra duck punched logic. However, once all “create” events have been removed (via die()), this plugin won’t have any idea because of this bug in 1.4.2.
• Cross browser compatible (including IE6)!

Download/Demo

Download on Github and view the demos. Unit tests are here. ]]> http://www.erichynds.com/jquery/jquery-create-event/feed/ 15 http://www.erichynds.com/jquery/a-jquery-ui-growl-ubuntu-notification-widget/ http://www.erichynds.com/jquery/a-jquery-ui-growl-ubuntu-notification-widget/#comments Thu, 13 May 2010 00:11:32 +0000 Eric Hynds http://www.erichynds.com/?p=664

Update 7/6/2010: version 1.4.1 is out!

There are about a dozen other plugins out there that do this already, except most seem to come with an enormous footprint: 10-12k of code, X-number of images, and roughly 1000 options to support every plausible use case. For other minimalists like myself out there, here’s one built off the jQuery UI widget factory in approx. 110 lines of code and 100% CSS. In typical widget fashion, this implementation supports the most basic (and arguably most common) uses, but is flexible enough for more advanced cases.

• View demos
• Follow on GitHub
• Download source and css file
• FAQ

Internet Explorer is a big-time downer with no HSLA/border-radius/box-shadow support, so if eye candy is important to you in IE, a transparent png background or similar can be added without much effort.

Usage

Using this widget is a simple four step process:

Step 1:

Include the JavaScript and CSS dependencies. Only the widget factory from jQuery UI is required.

1. CSS file: ui.notify.css
2. jQuery and the jQuery UI widget factory: ui.widget.js
3. This widget: ui.notify.js

Step 2:

Create a container element to hold notifications, and a template from which all notifications will be constructed from. With this, you can have multiple containers on the same page holding different styles of notifications. Each container can contain different templates.

<!-- set the container hidden to avoid a flash of unstyled content
when the page first loads -->
<div id="container" style="display:none">
 
    <!-- 
    Later on, you can choose which template to use by referring to the 
    ID assigned to each template.  Alternatively, you could refer
    to each template by index, so in this example, "basic-tempate" is
    index 0 and "advanced-template" is index 1.
    -->
    <div id="basic-template">
        <a class="ui-notify-cross ui-notify-close" href="#">x</a>
        <h1>#{title}</h1>
        <p>#{text}</p>
    </div>
 
    <div id="advanced-template">
        <!-- ... you get the idea ... -->
    </div>
 
</div>

Once the widget is initialized on the container, each template is cached and removed from the DOM. You can add one or more close links in your template by assigning each anchor the class ui-notify-close. The close link in this example has additional styling through the class ui-notify-cross, which makes the “x” look like an icon.

Define any variables you want to include in this template using #{varname} syntax. You can call these anything you’d like.

Step 3

Initiate the widget on the container, optionally passing in a hash of default options:

// basic
$("#container").notify();
 
// or with options (there are only 2)
$("#container").notify({
    speed: 500,
    expires: false
});

Step 4

Notifications are actually displayed by calling the create method. Pass in an hash of variables to transpose into the template:

// notice the templates in step 2 are expecting title and text variables.
// you can add as many as you like, and call them whatever you want.
$("#container").notify("create", {
    title: 'Test Notification',
    text: 'This is an example of the default config, and will fade out after five seconds.'
});

If you’d like, set specific options for each notification by passing in a second hash:

// example of overriding the expires and speed options for one notification
$("#container").notify("create", {
    title: 'Test Notification',
    text: 'This is an example of the default config, and will fade out after five seconds.'
},{
    expires: false,
    speed: 1000
});

You can specify the template to use by passing in the ID of the template as the second parameter. This is optional, and if not provided the first template defined will be used. Alternatively, you can pass in the index of the template in the container as the second argument.

// create a new notification using the "basic" template
// that we defined in step 2.
$("#container").notify("create", "basic-template", { /* template vars */ });
 
// we can refer to the template by index as well.  this
// statement is equivalent:
$("#container").notify("create", 0, { /* template vars */ });

The create method returns a notification instance object with two public methods: open and close.

// create a new "sticky" notification
var instance = $("#container").notify("create", {}, { sticky:true });
 
// close it
instance.close();
 
// re-open it
instance.open();

Options

These options can be set for all notifications within a container, or on a notification-by-notification basis:

Parameter	Description	Default
speed	The amount of time in milliseconds to fade notifications in and out.	500
expires	Notifications will automatically close after this amount of time, in milliseconds. Set to 0 or false to create a “sticky” notifications.	5000
stack	New in version 1.2.1! Notifications will stack downwards if set to “below” (default), or upwards if set to “above.”	below
custom	New in version 1.3! A boolean value denoting whether or not the widget should apply its own styling classes. Set to false to roll your own notification themes (including ThemeRoller). You could simply overwrite the included CSS, but using this option allows you to create default AND custom notifications within the same containers, as well as maintain a clear upgrade path as you won’t have to touch any of the included files.	false

Events

These events can be bound by passing handlers in as options. Example:

// for a specific notification
$("#example").notify("create", { /* template vars */ },{
   open: function(){
      alert("Notification opened!");
   }
});
 
// or for all notifications within a container
$("#container").notify({
   open: function(){
      alert("Notification opened!");
   }
});

Event	Description
beforeopen	Fires before the notification opens. If false is returned inside this callback, the notification will not open.
open	Fires after the notifcation opens.
close	Fires after the notifcation closes.
click	Fires if the user clicks anywhere in the notification itself (not on the close link(s), if present). Useful if you want to close the notification or perform some other action once the user has acknowledged the notice. The callback receives two parameters as arguments: the event object, and the notification instance object. Example: $("#container").notify("create", { title: 'Clickable Notification', text: 'Click on me to fire a callback' },{ click: function(e,instance){ // close the notice if the user clicks anywhere inside it instance.close(); } });

FAQ

How do I use ThemeRoller in my templates?

First, create a template and apply the appropriate ThemeRoller classes, icon classes you want to use, etc.:

<div id="notification-container">
 
   <div id="themeroller" class="ui-state-error">
      <!-- close link -->
      <a class="ui-notify-close" href="#">
         <span class="ui-icon ui-icon-close" style="float:right"></span>
      </a>
 
      <!-- alert icon -->
      <span style="float:left; margin:2px 5px 0 0;" class="ui-icon ui-icon-alert"></span>
 
      <h1>#{title}</h1>
      <p>#{text}</p>
   </div>
 
   <!-- other templates here, if you'd like.. -->
</div>

Next, either when you init the widget or create a notification, ensure the custom parameter is set to false:

// prevent notify from imposing its own styling classes
// on ALL notifications inside this container 
var handler = $("#notification-container")
      .notify({ custom:true })
      .notify("create", { title:"foo", text:"bar" });
 
// or just themeroller templates
var handler = $("#notification-container")
      .notify()
      .notify("create", "themeroller", { title:"foo", text:"bar" }, { custom:true };

How do I add a close icon or link to my templates?

Any link, button, etc. with the class ui-notify-close will close the notification when clicked. To use the X close link as seen in the demos, apply the ui-notify-cross class as well:

<a class="ui-notify-close ui-notify-cross" href="#">x</a>

How do I avoid a FOUC (flash of unstyled content) when the page first loads?

Simply give your container the display: none; CSS property. Once you initialize this widget on the container, it’ll take care of the rest.

Related posts:

1. Using $.widget.bridge Outside of the Widget Factory
2. jQuery UI MultiSelect Widget
3. Tips for Developing jQuery UI 1.8 Widgets

]]>

I’m wrapping up my first jQuery UI widget (see multiselect on GitHub) and thought it would be useful to share some notes I took on the widget factory & widget development in general.  I personally found development on the factory to be quite enjoyable; a lot of functionality is available right out the box (custom events, ability to change options after initialization) and idioms you might not otherwise consider, like widget destruction.  Furthermore, it imposes a clean object-literal development structure with public and private methods, making it much easier to start a project or maintain other’s projects.

Throughout this blog post I will be showing you various ways to modify the jQuery UI dialog widget source to add your own features.  I do not actually recommend doing this however, because widgets can just as easily be extended.  The concepts are the same though and are easily adaptable to your own project. This post also assumes you are already familiar with the widget factory; if you aren’t, be sure to familiarize yourself first.

_init() and _create()

The widget factory automatically fires the _create() and _init() methods during initialization, in that order.  At first glance it appears that the effort is duplicated, but there is a sight difference between the two.  Because the widget factory protects against multiple instantiations on the same element,  _create() will be called a maximum of one time for each widget instance, whereas _init() will be called each time the widget is called without arguments:

$(function(){
 
	// _create() and _init() fire on the first call.
	$("div").mywidget();
 
	// a widget has already been instantiated on the div, so this time
	// only _init will fire.
	$("div").mywidget();
 
	// however, once the widget is destroyed...
	$("div").mywidget("destroy");
 
	// both _create() and _init() will fire.
	$("div").mywidget();
 
});

So how do you know where to place which logic?  Use _create to build & inject markup, bind events, etc. Place default functionality in _init().  The dialog widget, for example, provides an autoOpen parameter denoting whether or not the dialog should be open once the widget is initialized; a perfect spot for _init!

// ui.dialog.js - autoOpen is true by default
_init: function(){
	if ( this.options.autoOpen ) {
		this.open();
	}
}

The best way to visualize the difference is to load up Firebug and navigate to the UI dialog demo page.  Because the autoOpen parameter is true by default, the dialog is created and opened when the page loads. Close the dialog by clicking on the close link in the toolbar, open Firebug, and attempt to reinitialize the demo by running this in your console: $("#dialog").dialog(). The widget factory knows there is already a dialog instance bound to the #dialog DIV; it just happens to be closed. Therefore, the widget factory will only fire the _init() method, which as you can see above, will simply open the dialog.

_trigger

Custom events can be fired from within your widget by using the internal _trigger method:

// call the trigger method passing in the name of the event to fire,
// and optionally an event and data object 
this._trigger("eventName", eventObj, {});

_trigger is provided by the widget factory, and is not the same as the jQuery trigger() method located in the $.fn namespace (notice the underscore prefix in the widget version).  Continuing with the dialog example, developers can execute logic when the dialog opens by either passing in an “open” callback, or later binding to the “dialogopen” event:

// provide an open callback during plugin creation
$("#dialog").dialog({
	open: function(event, ui){
		// do stuff
	}
});
 
// or bind to the dialogopen event
$("#dialog").bind("dialogopen", function(event, ui){
	// do stuff
});

When I was trying to integrate similar functionality into multiselect, I scoured the dialog’s source code looking for a trigger on the “dialogopen” event to see how it was done.  Said trigger does not exist.  Black magic, I thought, but as it turns out there is a call to _trigger("open") inside the dialog’s “open” method.  Success!

// ui.dialog.js
 
open: function(){
	var self = this;
 
	// open logic here
 
	// event is fired 
	self._trigger('open');
}

When self._trigger("eventName") is called:

1. The widget factory automatically prepends the widget’s name to the name of the event you want to trigger – and fires the event.
2. If there is a function with the name of the event you’re trying to trigger inside the options object, that function will be called as well.

A number of other things go down – like copying the original event object if it exists – but for developers, the points above are the most important parts to remember.

Preventing default actions with _trigger

There are a number of events in jQuery UI where, if you bind to them and return false, the default behavior will not fire.  The “select” event in the Autocomplete widget, for example, fires when an item is selected from the menu. From the UI docs:

The default action of select is to replace the text field’s value with the value of the selected item. Canceling this event prevents the value from being updated, but does not prevent the menu from closing.

Applying this to the dialog widget, one might expect that something like this will prevent a dialog from opening:

// no workie
$("#dialog").bind("dialogopen", function(){
	return false;
});

This is not supported with the open event, nor should it to be, because users expect this type of event to fire after the dialog has opened. So let’s modify the source of the widget and add our own custom “beforeopen” event, which will fire immediately once the open method is called. Before the logic to actually display the dialog, and before the open event is fired:

// ui.dialog.js
 
open: function(){
	// bail out of the open method if the returned value from the
	// beforeopen event is false.
	if(this._trigger('beforeopen') === false){
		return;
	}
 
	// continue rest of dialog open logic.
}

Now, we can bind to this new beforeopen event and prevent the dialog from opening simply by returning false:

$("#dialog").bind("dialogbeforeopen", function(){
	return false;
});
 
// or
 
$("#dialog").dialog({
	beforeopen: function(){
		return false;
	}
})

Huzzah!  On the same note, event callbacks take two optional parameters: the event object and an options object. If an event was triggered by another event – like the “close” event being triggered by clicking on the close icon in the dialog’s title bar – the original click event has not been lost.  In this context, event.type equals “dialogclose”, but the “click” event is accessible under the event.originalEvent namespace:

$("#dialog").dialog({
	close: function(event, ui){
 
		alert(event.type); // => "dialogClose"
 
		// when fired programatically: $("#dialog").dialog("close"):
		alert(typeof event.originalEvent); // => "undefined"
 
		// but when called with the esc key or clicking on the
		// close icon:
		alert(typeof event.originalEvent); // => "object"
		alert(event.originalEvent.type); // => "click"
	}
});

Accessing other widget instances

Let’s say you want to ensure that only one dialog can be open at any given time; that is, when a dialog’s open method is called, all other open dialog instances should be closed. Unfortunately the widget factory does not hold an internal cache of widget instances, but this feature is trivial to implement none the less.

First, it is important to understand how a DOM element is related to the widget it was initialized it on.  Most (if not all widgets) follow this pattern:

1. You, the developer, queries the DOM for an element and calls the widget you want to initiate.
2. The widget generates new markup based on that element and injects it into the DOM somewhere.  The entire widget instance is then stored in is the element’s data() cache.
3. Optionally, if it makes sense, the widget hides the original element, seemingly transforming the old element into a new widget.

Let me hit you with that once more in case you missed it: the entire widget instance is stored in the element’s data() cache.  If you were to examine $("#element").data() in firebug, you would see an object with the name of the widget you created on that element.

Once $("#mydiv").dialog() is called, new markup is generated and injected into the DOM, and the original mydiv element is transformed into the content pane of the dialog.  Even through the mydiv element is now apart of the widget, it continues to be our link between the developer and the dialog instance:

// create a new dialog
$("#mydiv").dialog();
 
// #mydiv is still in the DOM, but is hidden.
// it is our link back to the widget.  so, to interact with
// the widget, we call a method on the original element:
$("#mydiv").dialog("open");
 
// or cache it in a var
var foo = $("#mydiv").dialog();
foo.dialog("open");

This explains the relationship of a DOM element to it’s dialog instance, but in order to close all other dialogs, this relationship needs to be reversed.   All instances have to be found first, and then we access the underlying DOM element and perform the close method call.

You may be tempted to hack the dialog’s open method to find every element and aimlessly fire the dialog close method:

// omg no - ui.dialog.js
open: function(){
	$("*").dialog("close");
 
	// continue with open code
}

…which would work, but there is a better way.  Actually, there are twothree better ways:

Method 1: store the original element in the widget’s data cache

I first came across this approach in the Filament Group’s select widget, so here’s a quick shout-out to them.  Since each dialog instance is stored in the element’s data cache, why not store the element inside the widget’s data cache?   This way we can easily query the DOM for all dialog widgets, access the underlying DOM element, and then fire the close method on those elements.  We’ll start by modifying the _create method to store the DOM element in the new widget:

// ui.dialog.js
 
_create: function(){
	// all the original create code here.  
 
	// the dialog's markup is generated and saved into 
	// this 'uiDialog' variable.
	var uiDialog = '<div class="ui-dialog"> ... </div>';
 
	// store the original element (this.element) inside the 
	// widget's data store.
	uiDialog.data("originalelement", this.element);
}

Next, at the top of the “open” method, query the DOM for all dialog widgets (DIV elements with the class ui-dialog) and filter out the current instance.  It is necessary to exclude the current instance because otherwise, given two dialogs A and B where A is closed and B is open, opening A would trigger the close event for both A and B, when the event should only be fired on B.  Finally, loop through the matching ui-dialog DIV’s and grab the element it was originally created with out of the data store.  If the dialog is open, determined by calling the dialog("isOpen") method, then close it:

// ui.dialog.js
open: function(){
	$("div.ui-dialog").not(this.uiDialog).each(function(){
		var el = $(this).data("originalelement");
 
		if(el.dialog("isOpen")){
			el.dialog("close");
		}
	});
 
	// rest of open code
}

Method 2: maintain your own cache

This method is certainly easier to understand, and involves extending the dialog widget to add a public property called “instances”. When you define a widget with the $.widget("namespace.widgetname") syntax, the widget factory instantiates the widget “class” inside $[ namespace ]. All jQuery UI widgets exist in the $.ui namespace, which is reserved for official widgets, so make sure you change this to something unique. Namespaces are used internally for organizational purposes; they do not allow you to create multiple widgets with the same name.

With this in mind, $.ui.dialog can easily be extended to include an instances property, which will start out as an empty array. Each time a dialog in initialized, the associated DOM element will be pushed into it, providing a clear path to all instances. On the token, each instance will be removed from the array on destruction.

Towards the bottom of the ui.dialog.js file, extend $.ui.dialog to include an instances property:

// ui.dialog.js
 
(function($){
	$.widget("ui.dialog", {
		// core of widget code here
	});
 
	// the dialog has some other code here
 
	// extend $.ui.dialog, adding a public "instances" property
	$.extend($.ui.dialog, {
		instances: []
	});
}(jQuery));

Next, push the original DOM element onto the $.ui.dialog.instances array during initialization:

// ui.dialog.js
 
_create: function(){
	$.ui.dialog.instances.push(this.element);
 
	// rest of _create code here
}

The advantage of this pattern is clear: all instances of the widget are accessible publicly AND from within the widget itself. It is trivial to access all elements that have a particular widget bound to them from outside your widget:

// this line becomes valid from both inside and outside the widget
// as soon as ui.dialog.js is loaded into your page:
alert("There are currently " + $.ui.dialog.instances.length + " dialog instances.");

Next, in the open method of the dialog, use $.grep to remove the current instance from $.ui.dialog.instances, saving these “other” instances into the variable otherInstances. Loop through this new array, check if the dialog associated with it is open, and if so, call the close method:

// ui.dialog.js
 
open: function(){
	// the DOM element associated with this instance
	var element = this.element;
 
	// go through each element in the array, returning a
	// new array of instances excluding the current one
	var otherInstances = $.grep($.ui.dialog.instances, function(elem){
		return elem !== element;
	});
 
	$.each(otherInstances, function(){
		var $this = $(this);
 
		if( $this.dialog("isOpen") ){
			$this.dialog("close");
		}
	});
 
	// rest of open code
}

The final step involves cleaning up after ourselves. Each time an instance is destroyed it needs to be removed from the array, trivial enough to implement with jQuery’s $.inArray method and JavaScript’s Array.splice method:

// ui.dialog.js
 
destroy: function(){
	// the DOM element associated with this instance
	var element = this.element;
 
	// the index, or location of this instance in the instances array
	var position = $.inArray(element, $.ui.dialog.instances);
 
	// if this instance was found, splice it off
	if(position > -1){
		$.ui.dialog.instances.splice(position, 1);
	}
 
	// continue destroy logic	
}

Method 3: widget pseudo-selector

In the #jquery IRC channel, Adam Sontag of the yayQuery fame noted an undocumented feature of the widget factory: automatic pseudo selector generation for all widgets. With this, it is super simple to query the DOM for all widgets of a certain type:

// gimme all dialogs
$(":ui-dialog");

The selector above returns an object of DOM elements each instance was created on. No need to maintain your own cache or store the DOM element inside each widget. Closing all other open dialog instances using this pseudo selector is trivial:

// ui.dialog.js
 
open: function(){
 
	// close all open dialogs, excluding this instance
	$(":ui-dialog").not(this.element).each(function(){
		var $this = $(this);
		if($this.dialog("isOpen")){
			$this.dialog("close");
		}
	});
 
	// rest of open code here
}

Nice and easy. Choose whichever you think works best for you. Method #2 gives you immediate access to a public array of instances and does not rely on querying the DOM; however, method #3 could not be any simpler.

Widget destruction & progressive enhancement

If your widget progressively enhances an element – that is, it transforms something that works into something that works better and with a candy coating – always keep in the back of your mind what will happen if it is later destroyed. I cannot think of an appropriate example with the dialog widget, but multiselect fits the bill perfectly. It works like this:

1. A standard HTML multiple select box exists in the DOM.
2. $("select").multiselect() is called which hides the select box and injects new markup into the DOM.
3. Users now interact with the widget using checkboxes instead of option tags.

Just as you would ensure that pre-selected option tags are checked by default when the widget is created, you also want to think in reverse. If a user checks 5 boxes and the widget is then destroyed, one would expect the same 5 option to also be selected. Therefore, when a checkbox receives the checked="checked" attribute, the associated option tag also receives the selected="selected" attribute, even though it is hidden from view. Therefore, the widget can be destroyed and re-created without losing any action the user performed.

Honestly, I cannot think of a legitimate use case where a widget is destroyed. The widget factory supports it, however, so you should too.

Resources

For more widget goodness:

• See a sample widget template using most of the conventions outlined above.
• Widget factory 1.7.2 to 1.8 upgrade guide and sample templates
• Widget factory development & planning documentation
• Widget factory developers guide
• More blog posts about widget development

If you have any feedback, questions, or other useful tips, please leave them in the comments section below.

Related posts:

1. Using $.widget.bridge Outside of the Widget Factory

This is a followup to an older post of mine about notifying & prompting your users for action once they’ve become idle. I’ve since re-written and abstracted the logic, creating a much more useful & customizable plugin. The main issue with my first implementation, which I’ve addressed in this update, is that the server was never actually polled to maintain an active server-side session during long periods of use. The server-side session might be set to expire after 30 minutes, but a user could be active on your application without a page load for longer than that. As such, following a page load after 30 minutes, the user would (presumably) be prompted to log back in… not a great user experience.

The gist of here is that after a user is idle after a configurable period of time, a div/UI dialog/whatever opens, warning the user that his/her session is about to expire. The user has X number of seconds to click a “resume” link in order to continue their session. If this event is not fired, the user is relocated (configurable) to a page where you’d likely implement server-side code to end their session. Idle state is one without any mouse movement or keypresses, and is detected with Paul Irish’s idleTimer plugin.

• See the Mint.com-style demo, or a demo using the jQuery UI dialog widget.
• Download the source & follow on GitHub.

Polling requests keep the server-side session alive

Polling requests are automatically sent to the server at a configurable interval, maintaining the users session while s/he is using your application for long periods of time.  My personal use case for this was an application where the user could write and send emails, but some users took so long to write their message that the server-side session expired before they submitted the form and their e-mail was lost. With ColdFusion and presumably other scripting languages, hitting a CFM file is enough to reset the internal server-side session timer.

Polling is done with a simple setInterval call so requests are not queued per se, but you are protected against failed & built-up requests. If the AJAX request exceeds your configured timeout limit, the request fails, OR the response does not match explicitly what you expect X amount of times, the script aborts itself.  This was designed to prevent long-running requests from building up and unnecessarily polling the server when the server isn’t even responding properly.  The likely scenario here is if the server goes down while the user is working on your page, or is overloaded and sporadically throwing 500′s or similar.

Usage

Here’s a quick mockup of a demo that opens a UI dialog window after the user is idle for 5 minutes. The user can choose to either keep his/her session alive, or end the session. A live demo of this can be found here. First, markup the dialog’s HTML:

<!-- dialog window markup -->
<div id="dialog" title="Your session is about to expire!">
	<p>You will be logged off in <span id="dialog-countdown"></span> seconds.</p>
	<p>Do you want to continue your session?</p>
</div>

Next, initiate the UI dialog widget:

// setup the dialog
$("#dialog").dialog({
	autoOpen: false,
	modal: true,
	width: 400,
	height: 200,
	closeOnEscape: false,
	draggable: false,
	resizable: false,
	buttons: {
		'Yes, Keep Working': function(){
			// Just close the dialog. We pass a reference to this
			// button during the init of the script, so it'll automatically
			// resume once clicked
			$(this).dialog('close');
		},
		'No, Logoff': function(){
			// fire whatever the configured onTimeout callback is.
			$.idleTimeout.options.onTimeout.call(this);
		}
	}
});

Finally, init the idleTimeout plugin. We’ll pass in the #dialog div as the first parameter, and the button that will trigger the “resume” functionality as the second parameter. In this demo, the resume logic needs to be bound to the “Yes…” button, which can be found by retrieving the :first button in the div .ui-dialog-buttonpane.

// start the plugin
$.idleTimeout('#dialog', 'div.ui-dialog-buttonpane button:first', {
	idleAfter: 300, // user is considered idle after 5 minutes of no movement
	pollingInterval: 60, // a request to keepalive.php (below) will be sent to the server every minute
	keepAliveURL: 'keepalive.php',
	serverResponseEquals: 'OK', // the response from keepalive.php must equal the text "OK"
	onTimeout: function(){
 
		// redirect the user when they timeout.
		window.location = "timeout.htm";
 
	},
	onIdle: function(){
 
		// show the dialog when the user idles
		$(this).dialog("open");
 
	},
	onCountdown: function(counter){
 
		// update the counter span inside the dialog during each second of the countdown
		$("#dialog-countdown").html(counter);
 
	},
	onResume: function(){
 
		// the dialog is closed by a button in the dialog
		// no need to do anything else
 
	}
});

Options

Enjoy!

Related posts:

1. Creating a Mint.com Style Idle Logout Timer Using jQuery
2. A Recursive setTimeout Pattern
3. jQuery: modifying the submit button when a form is submitted

If you’ve ever found yourself debugging multiple elements stacked with z-index, and wish you could visualize their boundaries and stack positions without trying to remember numbers, this one is for you.

The picture on the right pretty much sums it up. “Visualize Stack” as I call it applies different shades of a color to elements based on their z-index value, relative to the z-index of other elements. This is particularly useful for developers who are stacking multiple elements on top of each other and would like to visually see their layering. For the time being, this plugin only works on browsers that support CSS3 hsl() coloring. Sorry, IE.

• View an example
• Get the code and follow this project on GitHub
• Get the bookmarklet

Usage

Call the visualizeStack() method on a jQuery object. The plugin will internally filter and only apply logic to the elements with a positive or negative numerical z-index. Example:

$(function(){
 
	// the logic will only apply to div and p elements in this example.  
	// use $("*") for all elements.
	$("div, p").visualizeStack({
 
		// CSS rules to apply.  the percent sign (%) is replaced with 
		// the appropriate color shade.
		properties: {
			background: "%",
			border: "1px solid black"
		},
 
		// the base color of the gradients.  Enter one of the following
		// colors, or a hue number for hsl(). accepted color names: 
		// red, purple, blue, turquoise, green, orange, and yellow.
		color: "red",
 
		// a hex color to apply to very lightly/darkly shaded elements.  
		// the "color" property of these
		// elements will be set to this value.  pass an empty string 
		// to disable.
		lightTextColor: "#fff",
		darkTextColor: "#000"
	});
 
});

The Bookmarket

If you’re like me, you’re probably too lazy to come to this website, download the JS file, include it, and write the selector/plugin call just to debug some simple CSS stack issues. By the time you’ve done all that it’s likely you could have figured the problem out on your own. Therefore, I packaged this code up in a little bookmarklet so you can instantly apply plugin.

A couple caveats first: 1) you must already have jQuery included in the website, and 2) it isn’t configurable unless you change the bookmarklet code yourself. All elements are selected (using $(“*”)) and the default options are automatically applied (the background property changes to shades of red).

To use, drag this link into your bookmarks toolbar: Visualize Stack

I suggest giving this thing a run on Digg.com; it’s pretty interesting to see what they have going over there for z-index’d elements.

About hsl() Coloring

This plugin dynamically generates a shade of a color with CSS3′s hsl(h,s,l), or hue, saturation, and lightness syntax. One of the many advantages of hsl() over rgb() for this type of application is that you can begin with a hue color – say 90 for red – and essentially guess a different shade of that color by tweaking the lightness. As such, providing an API where you can either pass in a number of a starting hue, or the name of a color, was trivial. The color name and associated hue number map looks like this:

$.fn.visualizeStack.colors = {
	red: 360,
	purple: 300,
	blue: 240,
	turquoise: 180,
	green: 120,
	orange: 35,
	yellow: 60
};

Unfortunately, support for hsl() is limited to Firefox 3, Google Chrome, Opera 9+, and Safari 3+. IE doesn’t get to play yet, but I believe we’ll be seeing it in IE 9. Also, if you’re into hsl(), check out hsla() on the CSS3 color spec which adds support for alpha transparency as well.

Walking Through The Code

The code for this is not terribly complicated. First, we’ll create a plugin called “visualizeStack” and add it the the $.fn namespace so that it can be called on a jQuery object of elements. We’ll allow an options parameter to be passed in, and then override the default options with the passed in options. This defaults object will be defined later towards the end of the file.

(function($){
 
$.fn.visualizeStack = function(options){
	options = $.extend({}, $.fn.visualizeStack.defaults, options);

The next section involves filtering out only elements that have a numerical z-index, and saving a reference to each element it’s z-index value in an sorted array.  I’ve commented heavily here, so hopefully it explains itself:

// We only want to keep elements that have a legitimate z-index.
// If this plugin is called like $("div").visualizeStack(), for 
// example, not all divs in that selection could have a set z-index.
//
// Because the default z-index property value is "auto" we can
// safely assume a z-index was set if the value is numeric
var elems = this.filter(function(){
	return /^-?\d+$/.test( $(this).css("z-index") );
})
 
// Take those filtered elements and return an array of objects.  The 
// "element" key will be a DOM element, and the "stack" key 
// will be the z-index.  
//
// Ultimately we want to create an array sorted in order of 
// z-indexes, from lowest to hightest. But, we also need 
// to remember which element had which z-index; an array of just 
// z-indexes or just elements does not help us. 
.map(function(){
	return { element:this, stack:parseFloat($(this).css("z-index")) };
})
 
// Turn this mapped jQuery object into a pure-javascript array of
// object literals.  If we didn't call get(), we would still be working
// with a jQuery object of object literals.
.get()
 
// Finally, sort the array ascending based on the "stack" property
// of the object.  Returning hierarchal numbers in sort() determines where
// to place the array item.
.sort(function(a,b){
	return a.stack === b.stack ? 0 : (a.stack < b.stack ? -1 : 1);
});

At this point we’re going to bail out of the script if there aren’t any elements to work with, which could happen one of two ways:  1) either the call to filter() returned an empty set because there weren’t any elements with a numerical z-index, or 2) when this plugin was created using $(expr).visualizeStack() syntax, the $(expr) call did not return any elements.

It is important to return “this” (the jQuery object of matching DOM elements) here to preserve chainability.

// nothing found?  bail.
if(!this.length || !elems.length){
	return this;
}

Set a few variables we’ll use later for calculating the lightness hsl() value:

var 
 
// the last "lightness" number will be recorded here.  We'll start with 90.
lastColor = 90, 
 
// the last z-index level will be recorded here.  Start with the first
// z-index in our elems array, or the lowest z-index.
lastStack = elems[0]['stack'],
 
// To define the gradient spectrum color, users can either pass in a
// name of a color (like red) OR a starting hue color.  If the user
// passed in a name, lookup it's hue value in $.fn.visualStack.colors.
// otherwise, use the number.  I'm making an assumption users will read
// the docs and don't try to enter the name of an unsupported color.
startHue = /\w/.test(options.color) ? $.fn.visualizeStack.colors[options.color] : options.color;

Next, we need to figure out how many unique z-indexes exist so we can correctly calculate a shade of color (or lightness), which is later determined by dividing the number of unique z-indexes by 100, then subtracting the quotient by the last color hue number. We cannot rely on the total number of elements because 8 out of 10 could have the same z-index level. The shades of colors would not be applied evenly across the spectrum.

To see what I’m talking about, this is an example of the shades of red calculated when we use the total number of elements:

If we use the unique number of z-indexes, the shades of red cover a wider spectrum:

To calculate this number we’ll use a self-executing anonymous function to loop through the elems array, and add each element’s z-index to a new array called uniques unless it has already been added. The length of uniques is then returned and set to the variable uniqueStacks.

// figure out how many unique z-index there are
var uniqueStacks = (function(){
 
	// where we'll store the unique z-indexes
	var uniques = [];
 
	$.each(elems, function(i,obj){
		if($.inArray(obj.stack, uniques) === -1){
			uniques.push(obj.stack);
		}
	});
 
	return uniques.length;
})();

Next comes the heart of the plugin. With each element, we need to determine the lightness value to use based its z-index, and apply the CSS properties defined in the option’s “properties” key.

// loop through the array of objects
$.each(elems, function(i, obj){
 
	// jQuerify our element
	var $element = $(obj.element),
 
		// determine the lightness value.  if this z-index
		// is the same as the last z-index, use the last lightness
		// value.  otherwise, create a new, darker shade
		color = lastColor = (obj.stack === lastStack)
			? lastColor
			: lastColor-(100/uniqueStacks);
 
	// loop through the CSS properties to add
	$.each(options.properties, function(prop, val){
 
		// replace the percent sign in the property value with the
		// hsl() color.  "background-color: %" will become
		// "background-color: hsl(h, s, l)"
		$element.css(prop, val.replace("%", "hsl("+startHue+",100%,"+color+"%)") );
 
		// change the text color property when the shade becomes 
		// too light or too dark to read
		if(options.lightTextColor.length && lastColor < = 50){
			$element.css("color", options.lightTextColor);
		} else if(options.darkTextColor.length && lastColor >= 50){
			$element.css("color", options.darkTextColor);
		}
	});
 
	// remember what the last z-index value was
	lastStack = obj.stack;
});

We’re almost done! The final steps are to return “this” so that this plugin can be chained, create a lookup table of color hue’s, define this plugin’s default options, and close off the wrapping closure.

return this;
 
// close $.fn.visualizeStack
};
 
// remember how you can pass in a color name as the "color"
// property?  these are the supported colors and their hue
// equivalents for CSS3's hsl()
$.fn.visualizeStack.colors = {
	red: 360,
	purple: 300,
	blue: 240,
	turquoise: 180,
	green: 120,
	orange: 35,
	yellow: 60
};
 
// plugin defaults
$.fn.visualizeStack.defaults = {
	color: "red",
	properties: {
		"background": "%"
	},
	lightTextColor: ""
};
 
// close the wrapping closure, passing in the jQuery object
// so $ can be used inside this plugin without conflict
})(jQuery);

That’s all there is to it.

I’ve been working on a multiple select plugin on and off for the past couple months and finally have it stable enough for a first release. When I started this project my intentions were only to re-factor Cory LaViska’s MultiSelect implementation, but it quickly turned into a complete re-write with a focus on speed and ThemeRoller support. This plugin turns an ordinary HTML select control into an elegant drop down list of checkboxes.

• Current version: 0.6 (05/04/2010 – Changelog)
• View demos
• Download source (12.5 kb) or minified (6.8 kb), and the CSS file.
• Follow this project on GitHub

Features

• Full ThemeRoller support.
• Optgroup support with clickable labels.
• Optional header with check all / uncheck all / close links.
• Degrades gracefully.
• Keyboard support.
• Ability to hook into 5 different event callbacks.
• Display the checked options in a list with a configurable maximum.
• Easily change the position, fade speed, scroll container height, links text, and input text.
• The widget width inherits from the original element, but is also configurable as a parameter.
• Pre-selected & disabled option/widget support.
• bgiframe support.
• Only 6.9kb minified (2kb Gzipped).

Compatibility

MultiSelect is compatible with jQuery 1.4.0+ and all themes from jQuery UI 1.7+. This plugin is known to work in (but not limited to):

• Firefox 2 – 3.6
• IE 6 – 8
• Chrome Beta/4
• Safari 4
• Opera 10

Usage

First ensure you’ve included jQuery 1.4, a jQuery UI theme of your choice, and the jquery.multiselect.css file. You don’t need the jQuery UI library itself, just the theme files. The simplest use of MultiSelect is to bind the widget to your select box:

<select id="MySelectBox" multiple="multiple" name="MySelectBox">
<option value="1">Option 1</option>
<option value="2">Option 2</option>
</select>

$(document).ready(function(){
    $("#MySelectBox").multiSelect();
});

Do not forget to set your select boxes to multiple="multiple" if you want this plugin to degrade gracefully. Any option tags with the selected="selected" attribute will automatically be checked by default, and any option tags with the disabled="disabled" attribute will automatically be disabled by default.

Callbacks

Inside the onOpen callback, this refers to the container holding the header and checkboxes. If you want to gather all the checkboxes inside the multiselect that just opened, for example:

$("#MySelectBox").multiSelect({
	onOpen: function(){
		var $checkboxes = $(this).find('input');
	}
});

Inside the onClick callback, this refers to the checkbox that received the event. Example:

$("#MySelectBox").multiSelect({
	onClick: function(){
		if(this.checked){
			alert("I was just checked!");
		}
	}
});

See the options below for a full list of callbacks.

Overriding Options

Options for this plugin are exposed in $.fn.multiSelect.defaults, so you can override the default options for all instances like such:

// set the minWidth parameter for all instances to 500 pixels
$.fn.multiSelect.defaults.minWidth = 500;

Passing a function to the selectedText parameter

As of 0.5, the selectedText parameter can accept an anonymous function with three arguments: the number of checkboxes checked, the total number of checkboxes, and an array of the checked checkbox DOM elements. As you can see in the example, this gives you 100% control of the display:

$("#MySelectBox").multiSelect({
	selectedText: function(numChecked, numTotal, checkedInputs){
 
		// example: emulating the default behavior
		return numChecked + " checked"; 
 
		// example: emulating the selectedList option
		return (numChecked < = 5) 
			? checkedInputs.map(function(element){ return element.title; }).join(', ')
			: numChecked + " checked";
	}
});

Options

This plugin is configurable with the following options:

Known Issues

A few issues are still outstanding:

• No onClose callback yet.
• The position should automatically change if the current position will prevent the options menu from showing. E.g., if the input is at the bottom of the page, the options should appear not appear below the input.
• In IE, the shadow parameter increases the width and height of the container, rendering it a few pixels wider than the input and throwing off the alignment. You can easily edit the CSS file and remove the IE-specific shadow filters, however, or opt not to use it.
• If the select box you’re transforming into a multiselect is disabled, the option tags will actually inherit the disabled property only in webkit; Firefox and IE do not display this behavior. I’ve filed a bug on this. Therefore, to be cross-browser compatible, if the entire widget is disabled by default, the class ui-state-disabled is applied and the disabled attribute is removed. This is important to note because checkbox values could be transmitted during submit, even if the select is disabled. To toggle disabled state, toggle the ui-state-disabled class on the widget.

  This bug does NOT effect the disabled state of specific option tags.

Related posts:

1. jQuery UI MultiSelect Widget
2. jQuery Related (Dependent) Selects Plugin