Eric Hynds

Working With XML, jQuery, and JavaScript

Eric Hynds — Sun, 29 Aug 2010 16:44:34 +0000

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 $(“”) 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.

On the same note, 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!

jQuery UI MultiSelect Widget

Eric Hynds — Tue, 06 Jul 2010 22:53:03 +0000

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.3 (07/08/2010 – changelog)
View demos
Download source or minified, and the CSS file.
Follow this project on GitHub
Run unit tests

Demo

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

The code behind this demo:

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

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. If you want this widget to degrade gracefully when JavaScript is turned off, ensure the control has 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!"
});

Option	Description	Default
header	Either a boolean value denoting whether or not to display the header, or a string value. If you pass a string, the default “check all”, “uncheck all”, and “close” links will be replaced with the specified text.	true
height	Height of the checkbox container (scroll area) in pixels. If set to “auto”, the height will calculate based on the number of checkboxes in the menu.	175
minWidth	Minimum width of the entire widget in pixels. Setting to “auto” will disable.	225
checkAllText	The text of the “check all” link.	Check all
uncheckAllText	The text of the “uncheck all” link.	Uncheck All
noneSelectedText	The default text the select box when no options have been selected.	Select options
selectedText	The text to display in the select box when options are selected (if `selectedList` is false). A pound sign (#) will automatically replaced by the number of checkboxes selected. If two pound signs are present in this parameter, the second will be replaced by the total number of checkboxes available. Example: "# of # checked". This parameter also accepts 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. See examples for usage.	# selected
selectedList	A numeric (or boolean to disable) value denoting whether or not to display the checked opens in a list, and how many. A number greater than 0 denotes the maximum number of list items to display before switching over to the selectedText parameter. A value of 0 or false is disabled.	false
show	The name of the effect to use when the menu opens. To control the speed as well, pass in an array: `['slide', 500]`	empty string
hide	The name of the effect to use when the menu closes. To control the speed as well, pass in an array: `['explode', 500]`	empty string
autoOpen	A boolean value denoting whether or not to automatically open the menu when the widget is initialized.	false
multiple	If set to false, the widget will use radio buttons instead of checkboxes, forcing users to select only one option.	true

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
	}
});

Event	Description
beforeopen	Fires right before the menu opens. Prevent the menu from opening by returning false in the handler.
open	Fires after the widget opens.
beforeclose	Fires right before the menu closes. Prevent the menu from closing by returning false in the handler.
close	Fires after the widget closes.
checkAll	Fires when all the options are checked by either clicking the “check all” link in the header, or when the “checkall” method is programatically called (see next section).
uncheckAll	Fires when all the options are all unchecked by either clicking the “uncheck all” link in the header, or when the “uncheckall” method is programatically called (see next section).
optgroupToggle	Fires when an optgroup label is clicked on. This event receives the original event object as the first argument, and a hash of values as the second argument: $("#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) */ });
click	Fires when a checkbox is checked or unchecked. $("#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");

Method	Description
open	Opens the menu.
close	Closes the menu.
update	Updates the current `selectedText`/`selectedList` value. Useful if you manually check/uncheck a box and need the widget’s text to reflect the changes.
disable	Disable the entire widget.
enable	Enable the entire widget.
checkAll	Check all checkboxes.
uncheckAll	Uncheck all checkboxes.
isOpen	Returns a boolean denoting if the widget is currently open or not.
getChecked	Returns an array of all the checked checkboxes.
widget	Returns the menu container (all checkboxes inside).
setOption	Set or change one of the options after the widget has been initialized. The new option setting will take affect immediately.
destroy	Destroy the widget, and revert back to the original select box.

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?

The options object is located in $.ech.multiselect.prototype.options. To configure options that all new instances will inherit, it’s easier to set them in this object instead of on an instance-by-instance basis.

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

Retrieve an array of all selected values?

Call the getChecked method and map a new array:

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

Retrieve values on the server?

Depends on your server-side language. In PHP et. al., you may need to name your select with square brackets on the end so the values can be captured as an array. I will probably wind up implementing this as an option at some point so it’ll degrade a bit better.

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

Open up the CSS file and edit the .ui-multiselect declaration.

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

The height you’ll need to set depends on the font size and padding you use, so it may need adjusting.

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

jQuery “Create” Event

Eric Hynds — Mon, 14 Jun 2010 12:12:47 +0000

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):

// 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.

A jQuery UI Growl/Ubuntu-like Notification Widget

Eric Hynds — Thu, 13 May 2010 00:11:32 +0000

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.

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.

CSS file: ui.notify.css
jQuery and the jQuery UI widget factory: ui.widget.js
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.


<div id="container" style="display:none">
 
    
    <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">
        
    </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">
      
      <a class="ui-notify-close" href="#">
         <span class="ui-icon ui-icon-close" style="float:right"></span>
      </a>
 
      
      <span style="float:left; margin:2px 5px 0 0;" class="ui-icon ui-icon-alert"></span>
 
      <h1>#{title}</h1>
      <p>#{text}</p>
   </div>
 
   
</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.

Tips for Developing jQuery UI 1.8 Widgets

Eric Hynds — Thu, 22 Apr 2010 12:33:32 +0000

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:

The widget factory automatically prepends the widget’s name to the name of the event you want to trigger – and fires the event.
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:

You, the developer, queries the DOM for an element and calls the widget you want to initiate.
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.
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 ~~two~~three 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 = ' ... 
';
 
	// 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	
}

Update 04/22/2010: Adam Sontag pointed out a third method:

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:

A standard HTML multiple select box exists in the DOM.
$("select").multiselect() is called which hides the select box and injects new markup into the DOM.
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.

A New And Improved jQuery Idle Timeout Plugin

Eric Hynds — Mon, 12 Apr 2010 12:42:50 +0000

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:


<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

Parameter	Description	Default
warningLength	The number of seconds after user is idle to show the logout warning.	30
keepAliveURL	A url to call to keep the session alive while the user is active.	30
serverResponseEquals	The response from keepAliveURL must equal this text.	OK
idleAfter	The user is considered idle after this many seconds. 10 minutes default.	600
pollingInterval	A polling request will be sent to the server every X seconds.	30
failedRequests	The number of failed polling requests until the script is aborted.	5
AJAXTimeout	The timeout passed to $.ajax in milliseconds.	250
onResume	A callback to fire when the session is resumed (by clicking the resume link).	function(){}
onIdle	Fires when the user becomes idle.	function(){}
onCountdown	Fires during each second of the warningLength parameter.	function(){}
onTimeout	A callback to fire when the session times out.	function(){}
onAbort	A callback to fire when the script is aborted due to too many failed polling requests.	function(){}

Enjoy!

A Quick Gotcha With CFML & JSON Serialization

Eric Hynds — Mon, 29 Mar 2010 12:39:19 +0000

ColdFusion internally represents structure keys in uppercase when the keys are created using dot notation. Dot notation is typically how programmers write their code and is considered to be best practice when working with structures. To the same effect, ColdFusion’s implementation of serializeJSON() serializes your object with respect to case; therefore, we might end up with something like this:

<cfset struct = {} />
<cfset struct.foo = "bar" />
 
<cfdump var="#serializeJSON(struct)#" />

Bummer. You’d probably expect “FOO” to be lowercase since that’s how you wrote it, but unfortunately it’s uppercase according to CF. Serializing a query forces uppercase JSON keys as well because queries act and function similarly to structures. This is rather annoying seeing how JavaScript is case sensitive, and serializeJSON is the way to push data from CF to JS. jQuery UI’s Autocomplete is a fine example of a widget that was not designed with case in mind; your JSON is expected to be returned with either a label or value key or both… in lowercase.

If you’re trying to serialize a query, there isn’t much you can do other than converting it to a structure and avoiding dot notation. Use bracket syntax, structInsert(), or create your structure literally:


<cfset struct1 = {} />
<cfset struct1["foo"] = "bar" />
 
<cfset struct2 = { "foo" = "bar" } />
 
<cfset struct3 = {} />
<cfset structInsert(struct3, "foo", "bar") />
 
<cfdump var="#serializeJSON(struct1)#" /> 
<cfdump var="#serializeJSON(struct2)#" /> 
<cfdump var="#serializeJSON(struct3)#" />

If you’re using a remote URL for your source parameter with the jQuery UI Autocomplete widget, most likely you’re using a query to retrieve matches from a database. Converting a CF query to JSON has it’s own set of problems because you’re stuck with extraneous data you probably don’t want: “COLUMNS”, “DATA”, and “ROWCOUNT” depending on how you serialize it. Either way, you’ll never be able to pass a serializeJSON(query) directly to the widget, so let’s kill two birds with one stone by converting it to a structure and forcing the keys to a lowercase string:


<cfquery name="q" datasource="#request.ds#">
select product_id as value, product_title as label
from products
where product_title like <cfqueryparam value="%#url.term#%" />
cfquery>
 

<cfset data = [] />
 
<cfoutput query="q">
 
	
	<cfset obj = {
		"label" = label,
		"value" = value
	} />
 
	
	<cfset arrayappend(data, obj) />
cfoutput>
 

<cfoutput>#serializeJSON(data)#cfoutput>

Easy peasy, nice and hackish.

Visualizing Your Z-Index Stacks with jQuery

Eric Hynds — Thu, 18 Mar 2010 12:59:37 +0000

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 &lt; 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.

FamFamFam Silk Icon Set in Base64 Encoding

Eric Hynds — Wed, 24 Feb 2010 15:05:26 +0000

This one can be filed under both “total impractical” and “somewhat useful”. For those who haven’t heard of this trick before, base64 encoding enables you to embed binary image data directly into your HTML or CSS source. Therefore, instead of the browser requesting two files from the server – the CSS file and the image file – only the CSS file need be requested. There are a number of drawbacks/pros/cons to this approach: IE doesn’t support it, file size limitations, larger CSS files, inability to separately cache CSS vs. images, etc. etc., but if you feel the need to use FamFamFam Silk icon’s in base64, look no further.

The CSS file. It’s 2.1mb, so be careful.
Examples

I use icons very liberally on all my projects; they’re classy and aid in usability. I typically start with a “.icon” class that configures the correct padding/background details for the element, followed by a “.icon-*” class, which sets the background-image property to that of the desired icon. For example, this CSS:

.icon { background-position:left; background-repeat:no-repeat; padding:3px 0 3px 19px }
.icon-pdf { background-image: url(/images/icons/pdf.png) }

Applied to this anchor element:

<a href="#" class="icon icon-pdf">Download PDF</a>

Produces: Download PDF

Can you dig it? The same .icon-pdf class in base64 looks like this:

.icon-pdf { background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABGdBTUEAAK/INwWK6QAAABl0RVh0U29mdHdhcmUAQWRvYmUgSW1hZ2VSZWFkeXHJZTwAAAHhSURBVDjLjZPLSxtRFIfVZRdWi0oFBf+BrhRx5dKVYKG4tLhRqlgXPmIVJQiC60JCCZYqFHQh7rrQlUK7aVUUfCBRG5RkJpNkkswrM5NEf73n6gxpHujAB/fOvefjnHM5VQCqCPa1MNoZnU/Qxqhx4woE7ZZlpXO53F0+n0c52Dl8Pt/nQkmhoJOCdUWBsvQJ2u4ODMOAwvapVAqSJHGJKIrw+/2uxAmuJgFdMDUVincSxvEBTNOEpmlIp9OIxWJckMlkoOs6AoHAg6RYYNs2kp4RqOvfuIACVFVFPB4vKYn3pFjAykDSOwVta52vqW6nlEQiwTMRBKGygIh9GEDCMwZH6EgoE+qHLMuVBdbfKwjv3yE6Ogjz/PQ/CZVDPSFRRYE4/RHy1y8wry8RGWGSqyC/nM1meX9IQpQV2JKIUH8vrEgYmeAFwuPDCHa9QehtD26HBhCZnYC8ucGzKSsIL8wgsjiH1PYPxL+vQvm5B/3sBMLyIm7GhhCe90BaWykV/Gp+VR9oqPVe9vfBTsruM1HtBKVPmFIUNusBrV3B4ev6bsbyXlPdkbr/u+StHUkxruBPY+0KY8f38oWX/byvNAdluHNLeOxDB+uyQQfPCWZ3NT69BYJWkjxjnB1o9Fv/ASQ5s+ABz8i2AAAAAElFTkSuQmCC) }

With this strategy in mind, I took each Silk icon and created a .icon-* class, where * is the name of the icon (underscores replaced with a hyphen). Each icon has a background-image property of the base64 encoded image.

The Code

The code to convert a directory of icons into base64 representation is very straightforward and revolves around ColdFusion’s fileReadBinary() and toBase64():

<cffunction name="base64CSS" output="false" returntype="void">
	<cfargument name="imgdir" required="true" type="string" hint="the directory of images to base64 convert" />
	<cfargument name="destination" required="true" type="string" hint="the path and name to dump the css file" />
	<cfargument name="examples" required="false" type="string" hint="the path and name to dump the example html" />
	<cfset var images = "" />
	<cfset var icon = {} />
 
	
	<cfdirectory name="images" directory="#arguments.imgdir#" />
 
	
	<cfset filewrite(expandpath(arguments.destination), "") />
	<cfif structkeyexists(arguments, "examples")>
		<cfset filewrite(expandpath(arguments.examples), "") />
	cfif>
 
	
	<cfloop query="images">
 
		
		<cfset icon.data = toBase64(fileReadBinary(directory &'/'& name)) />
 
		
		<cfset icon.name = replace(replace(name, "_", "-", "all"), '.png', '') />
 
		
		<cfset icon.css = ".icon-" &icon.name& " { background-image:url(data:image/png;base64," &icon.data& ") }" />
		<cfset icon.html = '&icon.name&'">' & icon.name & '' />
 
		
		<cffile action="append" file="#expandpath(arguments.destination)#" output="#icon.css#" />
 
		
		<cfif structkeyexists(arguments, "examples")>
			<cffile action="append" file="#expandpath(arguments.examples)#" output="#icon.html#" />
		cfif>
	cfset>cfloop>
cffunction>
 
<cfset base64CSS("/home/ehynds/Assets/icons/silk/", "icons.css", "examples.htm") />

I started by creating a “base64CSS” function which accepts three arguments: a path to a directory of images, the CSS file to generate, and the examples HTML file to generate. cfdirectory reads the image directory, the two CSS/example files are created, and then I loop through each image in the directory. Each image is read as binary data and converted to base64, given a name (separated with hyphens instead of underscores), and the CSS and HTML is generated. Finally, the CSS is appended to the CSS file and the HTML to the examples file.

Simple, right? Does anyone else use some kind of icon class? I’d like to see other approaches!

CFIMAGE resize after CFFILE upload

jQuery MultiSelect Plugin w/ ThemeRoller Support

Eric Hynds — Mon, 01 Feb 2010 14:47:03 +0000

07-09-2010 – This plugin has been re-written!

I’ve re-written this plugin using the jQuery UI widget factory. As such, a number of new features have been added, bugs fixed, and performance issues addressed. While this version will still be supported, I highly recommend you use this new version instead!

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:

Parameter	Description	Default
showHeader	A boolean value denoting whether or not to display the header containing the check all, uncheck all, and close links.	true
maxHeight	The maximum height in pixels of the scrolling container that holds the checkboxes.	175
minWidth	The minimum width in pixels of widget. Setting to `auto` (default) will inherit the width from the original select element.	200
checkAllText	The default text of the “Check all” link.	Check all
unCheckAllText	The default text of the “Uncheck all” link.	Uncheck all
noneSelectedText	Renamed from `noneSelected` in 0.5! The default text the select box when no options have been selected.	Select options
selectedList	A boolean/numeric value denoting whether or not to display the checked opens in a list, and how many. A number greater than 0 denotes the maximum number of list items to display before switching over to the `selectedText` parameter. A value of 0 or `false` is disabled.	false
selectedText	The text to display in the select box when options are selected (if selectedList is false). The pound sign (#) is automatically replaced by the number of checkboxes selected. If two pound signs are present in this parameter, the second will be replaced by the total number of checkboxes available. Example: “# of # checked”. New in 0.5! As of 0.5, this parameter can also 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. See the examples.	# selected
position	The position of the options menu relative to the input control: top, middle, or bottom.	bottom
shadow	A boolean value denoting whether to apply a CSS shadow (class ui-multiselect-shadow).	false
fadeSpeed	How fast (in ms) to fade out the options menu on close.	200
state	New in 0.5! The default state of the widget. Either open or closed.	closed
disabled	New in 0.5! Whether or not to disabled the widget by default. Important: see the “Known Issues” section below for more documentation on this.	false
onCheck	A callback to fire when a checkbox is checked.	Function
onOpen	A callback to fire when the options menu is opened.	Function
onCheckAll	A callback to fire when the “Check all” link is clicked.	Function
onUncheckAll	A callback to fire when the “Uncheck all” link is clicked.	Function
onOptgroupToggle	A callback to fire when the opgroup header is clicked. An array of checkboxes inside the optgroup is passed as an optional argument.	Function

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.