Most jQuery code sets data values using the higher-level .data() API; for example, $("div").data("imaDiv", true) sets a boolean value on every div in the document. This API, in turn, calls down to jQuery.data() with each element to set the value. For completeness, there are also jQuery.removeData() and .removeData() to remove data elements, and jQuery.hasData() to determine if any data is currently set for an element.

So to recap: At the inception of these APIs, they were only about getting and setting values associated with DOM elements in memory. Most importantly, the data was managed to ensure no memory would leak when the DOM elements were removed. Many internal jQuery features such as event handling and toggle state memory use these data APIs and their benefits.

Enter HTML5

A few years later, HTML5 became popular and associated another concept with the word "data" through its data-* attributes and the associated DOM .dataset property. This isn't quite the same as jQuery's original idea of data: It involves values being associated with HTML elements in markup and not DOM elements in memory. But they are logically close enough that we added the ability to read HTML5 data-* attributes into jQuery's data object starting with version 1.4.

It's not a perfect marriage, though. HTML5 data-* attribute names are more like CSS names; a name like data-shrivel-up is turned into shrivelUp when read in JavaScript-land. No such rules ever applied to jQuery data names in the past, which means we may have to try both shrivel-up and shrivelUp to find a match. We know it's not ideal, but it's a consequence of trying to fit two concepts with differing semantics into a single API.

Rules of the Road for Data APIs

With that history in mind, there are a few important things you should know in order to use the .data() and jQuery.data() APIs effectively. To give you a better sense of what's going on, the items are illustrated with some code. Assume that each code block runs independently of the others and that they all refer the following HTML:

Here are the rules of the road:

1. Only the .data() API reads HTML5 data-* attributes, and it does so once.

   The in-memory data object for an element is initialized from those data-* attributes the first time you call .data() for the element. Any subsequent changes to the attributes are ignored, since jQuery has already cached the data.

   Rule: If HTML5 data-* attributes change during program execution, use jQuery's .attr() method to get the current values.

   PLAIN TEXT
   JavaScript:
   

   1. console.log( $.data( document.getElementById('poem'), 'poet' ) );
   2. //>> undefined
   3.  
   4. console.log( $('#poem').data('poet') );
   5. //>> "Edna St. Vincent Millay"
   6.  
   7. // Change the HTML5 data-poet attribute
   8. $('#poem').attr('data-poet', 'Edmund Spenser');
   9.  
   10. console.log( $('#poem').data('poet') );
   11. //>> "Edna St. Vincent Millay"
   
   

2. The .data() API converts HTML5 data-* values to Javascript types whenever possible.

   That means sequences of digits or exponential-looking values like "11E5" are translated to a Javascript Number type, the string "true" becomes Boolean true, and a valid JSON string becomes a JavaScript object.

   Rule: To get HTML5 data-* attributes as strings without data conversion, use jQuery's .attr() method.

   PLAIN TEXT
   JavaScript:
   

   1. console.log( $('#novel').data('novelist') );
   2. //>> Object> {"firstname": "Jose", "lastname": "Saramago"}
   3.  
   4. console.log( $('#novel').attr('data-novelist') );
   5. //>> '{"firstname": "Jose", "lastname": "Saramago"}'
   
   

3. The lower-level jQuery.data() API does not read HTML5 data-* attributes.

   However, if the .data() API has been called already on that DOM element, jQuery.data() will "see" the values that it has already read from the data-* attributes. Conversely, if jQuery.data() sets a value with the same name as an HTML5 data-* attribute and .data() later reads them, the HTML5 attribute is ignored.

   Rule: To prevent confusion, do not use similar names for HTML5 data-* attributes and strictly internal data stored using jQuery.data() or .data() on the same elements.

   PLAIN TEXT
   JavaScript:
   

   1. // Before reading with .data()
   2. console.log( $.data( document.getElementById('poem'), 'poet' ) );
   3. //>> undefined
   4.  
   5. console.log( $('#poem').data('poet') );
   6. //>> "Edna St. Vincent Millay"
   7.  
   8. // After reading with .data()
   9. console.log( $.data( document.getElementById('poem'), 'poet' ) );
   10. //>> "Edna St. Vincent Millay"
   
   

4. No jQuery data API ever changes HTML5 data-* attributes.

   Most uses of .data() and .removeData() are still for the original purpose of associating data with DOM elements in memory. Updating DOM attributes each time data was changed would slow things down for no good reason. Also, it's not even possible to serialize all data types that might be attached to a DOM element, such as functions, references to other DOM elements, or custom JavaScript objects.

   Rule: To update or remove HTML5 data-* attributes, use jQuery's .attr() or .removeAttr() methods.

   PLAIN TEXT
   JavaScript:
   

   1. console.log( $('#poem').data('poet') );
   2. //>> "Edna St. Vincent Millay"
   3.  
   4. console.log( $('#poem').attr('data-poet') );
   5. //>> "Edna St. Vincent Millay"
   6.  
   7. // Change the HTML5 data-* attribute
   8. $('#poem').attr('data-poet', 'William Shakespeare');
   9.  
   10. console.log( $('#poem').data('poet') );
   11. //>> "Edna St. Vincent Millay"
   12.  
   13. console.log( $('#poem').attr('data-poet') );
   14. //>> "William Shakespeare"
   15.  
   16. // Change .data('poet')
   17. $('#poem').data('poet', 'Edmund Spenser');
   18.  
   19. console.log( $('#poem').data('poet') );
   20. //>> "Edmund Spenser"
   21.  
   22. console.log( $('#poem').attr('data-poet') );
   23. //>> "William Shakespeare"
   
   

5. All data-* names are stored in camelCase in the jQuery data object, using W3C rules.

   So, data-caMEL-case becomes the camelCase property in the data object and should be accessed using .data("camelCase"). Because many people will use .data("camel-case") instead, we convert that to camelCase as well, but only if no data item named camel-case is found so it's faster to use the first form. If you get the entire data object using code like data = jQuery.data(elem), you must use data.camelCase to access the data item.

   Rule: When accessing data taken from data-* attributes, and especially when accessing the data object directly, use the W3C camelCasing conventions.

   PLAIN TEXT
   JavaScript:
   

   1. // Not recommended:
   2. console.log( $('#story').data('STORY-writer') );
   3. //>> "Raymond Carver"
   4.  
   5. // Better:
   6. console.log( $('#story').data('storyWriter') );
   7. //>> "Raymond Carver"
   8.  
   9. // Broken:
   10. console.log( $('#story').attr('dataStoryWriter') );
   11. //>> undefined
   12.  
   13. // Better:
   14. console.log( $('#story').attr('data-STORY-writer') );
   15. //>> "Raymond Carver"
   
   

Pick What You Like

Over time, jQuery's .data() API has taken on more responsibilities than it originally had when it was just a way to associate in-memory data with DOM elements and prevent IE leakage. If you need only a simple way to read HTML5 data-* attributes as strings, then the .attr() method may be the best choice, even though the siren-song-name .data() may be telling you otherwise. Whether you use .attr() or .data(), they work consistently across browsers all the way back to IE6 — even if the browser doesn't support HTML5 — so just choose the API with the feature set that works best for your needs.

The HTML I tested against was a page of 100 div tags with a class and some content, I cached the selector $('div') to use with each method to exclude the time needed to find all the div elements on the page from the test. I used jQuery 1.4.2 for the testing, but keep in mind that the algorithms behind the method calls can change dramatically from version to version. What is true for 1.4.2 is not necessarily true for other versions of the library.

The methods I tested were .toggle(), .show() & .hide(), .css({'display':'none'}) & .css({'display':'block'}), and .addClass('hide') & .removeClass('hide'). I also tested modifying an attribute of a <style> element.

.show() & .hide()

These were, in fact, comparatively slow methods of hiding DOM elements across all browsers. One of the main reasons is that .hide() has to save the notion of what the display attribute was before, so that .show() can restore it. It does this using the .data() jQuery method, storing that information on the DOM element. In order to do so, .hide() loops through every element twice: once to save the current display value, and then once to update the display style to none. According to a comment in the source, this prevents the browser from reflowing with every loop. The .hide() method also checks to see if you pass in a parameter to animate the hiding with an effect. Even passing in a 0 dramatically slows down the performance. Performance was slowest on the first call to .hide(); subsequent calls were faster.

Browser      hide/show
FF3.6 -         29ms / 10ms 
Safari 4.05 -   6ms / 1ms
Opera 10.10 -   9ms / 1ms
Chrome 5.0.3 -  5ms / 1ms
IE 6.0  -       31ms / 16ms 
IE 7.0  -       15ms / 16ms 

.toggle()

This was, by far, the slowest method of hiding all of the div elements. It iterates through every element returned by the selector, checks to see if the element is currently visible, and then calls .hide() on visible elements one at a time and .show() on hidden ones one at a time. It also has to check to see if you are passing in a boolean to force everything to .show() or .hide() and check to see if you are passing in functions to toggle instead of toggling visibility. There seems to be some opportunity for optimization of this function, as one could select all of the hidden elements of the selector and call .show() on them all at once and then select the remaining elements in the selector and call .hide() on them at the same time. If you are so inclined, I encourage you to check out the source and see if you can eke out any performance gains.

Browser      hide/show
FF3.6 -         80ms / 59ms 
Safari 4.05 -   24ms / 30ms 
Opera 10.10 -   67ms / 201ms
Chrome 5.0.3 -  55ms / 20ms 
IE 6.0  -       296ms / 78ms 
IE 7.0  -       328ms / 47ms 

.addClass() & .removeClass()

These are pretty snappy methods of hiding/showing elements of the DOM, twice as fast as .show() & .hide() in Firefox and three times as fast in Safari. The differences in IE 6, IE7, Chrome, and Opera are negligible. It's also worth noting that with 100 DOM nodes, we're talking a total difference of 18ms in Firefox and 4ms in Safari. The speed difference will only be relevant for very large selections. Adding and removing a class requires a bit more management on your part, since you have to create the class that has a display of none and then have to keep track of CSS priority to make sure your elements get hidden. The way jQuery adds and removes a class is through string manipulation, so I imagine that as the number of classes on an element grows, this method will get slower, but that is untested speculation on my part.

Browser      hide/show
FF3.6   -       11ms / 11ms 
Safari 4.05 -   2ms / 2ms
Opera 10.10 -   6ms / 3ms
Chrome 5.0.3 -  3ms / 1ms
IE 6.0  -       47ms / 32ms
IE 7.0  -       15ms / 16ms

.css({'display':'none'}) & .css({'display':'block'});

These methods were very snappy. They showed an improvement over .addClass() and .removeClass() in Opera and IE 6/7 and about the same in other browsers. They work great if you know the current display style of all the elements you are changing, or at least have not changed the display style inline. If you have changed the display style inline, then you will need to make sure you set the correct value when you make the element visible again. If you are just using the elements' default display value or set the display value in the css, then you can just remove the style like so, .css({'display':''}), and it will revert to whatever value it has in the css or by default. As a library, jQuery can't assume that the display element wasn't set inline, so it has to manually keep track of it. That is the main slowness you can avoid since you know you won't be setting the display inline.

Browser      hide/show
FF3.6   -       14ms / 12ms
Safari 4.05 -   2ms / 1ms
Opera 10.10 -   2ms / 2ms
Chrome 5.0.3 -  2ms / 1ms
IE 6.0  -       16ms / 16ms
IE 7.0  -       0ms / 0ms  // The usual caveat about inaccuracy of IE clocks applies.

Disabling stylesheets

For fun, I thought, "What if instead of manipulating every DOM node and changing things, we just futz with the stylesheet?" Could there be speed improvements there? I mean, the methods benchmarked above are plenty fast for everyday use, but what if I had 10,000 nodes on a page I wanted to show and hide? It would be slow just selecting them all. But, if I could manipulate the stylesheet, I could avoid the entire overhead. Let me just tell you that way is fraught with peril.

There are, of course, cross browser issues when manipulating stylesheets, since jQuery doesn't abstract them away for you. First, I tried to see if I could append a style tag with the css class as a string using jQuery, but got inconsistent results across browsers. Then I tried creating the stylesheet node and class using JavaScript, but there were different APIs and it ended up being too slow to justify. So finally, forgoing an attempt to do this in a programmatic way, I ended up just writing a style tag with a class in the head of the document. It's far too slow to create the stylesheet programmatically, but if it's already there then it is trivial to give it an ID and use its disabled attribute.

Then in javascript…

and BAM, you just displayed all of your elements with a class of “special_hide”. To hide them all again, just do…

and they are now all hidden. The total javascript processing time was 0-1ms across all browsers. The only javascript you are doing is changing an attribute. Of course, there is still the time the browser takes to reflow and repaint the page, but you've virtually eliminated all the javascript processing time. If you call any of the other methods, .toggle(), .hide(), or .css(), this method will stop working on those elements because they set the css style inline, which has higher precedence than other css. To make this method work again, simply do a .css(‘display’, ‘’) to remove the inline style. This method also requires the most work on your part, because you have to define the class and give the class to all of the elements on the page you want to show/hide at the same time, but if you are dealing with extremely large sets, this might just be worth it.

To recap, here is a list of methods to change the display of elements in order from fastest to slowest:

1. Enabling/Disabling a stylesheet
2. .css('display', ''), .css('display', 'none')
3. .addClass(), .removeClass()
4. .show(), .hide()
5. .toggle()

Also note that for the majority of use cases, all of these methods are plenty fast to use. When you start having to manipulate large jQuery collections, .show() and .hide() might become too slow in IE, and you might need to bump up to .addClass() or .removeClass(). Enabling/disabling of stylesheets would only be necessary in the most extreme cases, but if things are hiding to slowly for you, you might want to give it a try.

Collapsible content areas are frequently presented in web sites and applications as a way to let users to control how content is shown or hidden on the page. Also called collapsibles, spin-downs, toggle panels, twisties, and content disclosures, they're ideal for selectively displaying optional information — like instructional text or additional details, for example — so users can focus on the task at hand and view this content only as needed.

The collapsible content area widget is fairly simple — a couple of HTML elements controlled with minimal CSS and JavaScript — but when we were researching our book, Designing with Progressive Enhancement, we discovered that many common approaches to creating collapsible content fail to incorporate accessibility features. Happily, there is a way to build collapsible content with progressive enhancement so it delivers an optimal accessible experience for sighted and screen reader users alike.

The code example described in this article is one of the 12 fully-accessible, project-ready, progressive enhancement-driven widgets that accompanies our new book, Designing with Progressive Enhancement.

View a demo

Before we dive in to the details, let's take a look at the widget in question. Here's an error dialog we created for a photo site, which appears when a photo upload fails — it provides a high-level summary, and a collapsible Details block with supplemental content about which photos failed to upload and why:

NOTE on the demo's "View low bandwidth" link: This demo runs on our EnhanceJS framework, which adds a "View low-bandwidth version" link to allow users to toggle from a basic to enhanced view, and drops a cookie on change. If you click the link to view the low-bandwidth version of the demo, you'll need to click it again to view the enhanced version of this site on future views. (Learn more about EnhanceJS here.)

So what's the problem here?

When we first set out to build an accessible collapsible content widget, we thought that the best way to hide the content and keep it accessible to screen readers would be to position it off-screen. We didn't appreciate that while technically this does make the content accessible, positioning content off-screen doesn’t actually provide an accessible experience.

People using assistive technologies like screen readers want to be able to interact with the page just as sighted users do. As accessibility specialist Adam Spencer noted in a recent CBS News story, “True accessibility is giving blind people the same options to access information as sighted ones” (emphasis ours).

While it’s true that hiding collapsible content off-screen at least keeps it in the page and accessible at a baseline level, it’s decidedly sub-par compared with the standard web user’s experience. For example, when a user with a screen reader encounters an accordion widget with ten sections, just like a sighted user they want to hear only the open section, not all content in every section. Screen reader users also expect to use the keyboard to quickly hear the accordion section headings — the screen reader equivalent of quickly scanning the page. When you simply hide content off-screen, these actions aren’t possible; instead, the screen reader reads all content in all the hidden panes, and the screen reader user has no option but to wade through it all in the order it appears in the markup.

Ideally, the experience for both sighted and visually impaired users should be as functionally similar as possible. The W3C Web Content Accessibility Group (WCAG) has outlined a set of four principles that must be met to ensure that content is accessible. Quickly, they say that it should be:

• Perceivable — Information and user interface components must be presentable to users in ways they can perceive.
• Operable — User interface components and navigation must be operable.
• Understandable — Information and the operation of user interface must be understandable.
• Robust — Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies.

That’s all well and good, but these definitions are a little abstract. What does it really mean? WCAG provides extended definitions that give us some helpful clues — for example, Perceivable content “can't be invisible to all of their senses”; an Operable interface “cannot require interaction that a user cannot perform”; an Understandable interface’s “content or operation cannot be beyond their understanding”; and it is Robust if “as technologies and user agents evolve, the content should remain accessible”.

In light of these principles, many common techniques for presenting collapsible content fall short. Consider these scenarios:

• Hiding content by default in the CSS, and relying on JavaScript events to let the user display it. If JavaScript is disabled or unavailable, the user has no means of accessing the content, and may not even know it's there. In this case, content is neither perceivable nor operable — or worse, if the design provides a hint (like an open/close icon or "View details" link), the hint is perceivable but the content non-functioning.
• Hiding content by positioning it off the page (e.g., position: absolute; left: -9999px;). Doing this ensures that the content is available to screen readers. However, it's always available — the user has no ability to control showing or hiding, or manage whether it's is read aloud. As collapsible content it's not operable; and depending on the widget's content, presenting it all simultaneously may not be understandable.
• Providing only a visual indicator, like an icon, on the clickable element to show that it can manipulate visibility of related content. This works for sighted users, but fails for screen readers. Unless the icon is accompanied by some adequate auditory feedback that content can be shown/hidden, the feature may not be fully perceivable or understandable to the screen reader user.
• Applying JavaScript events to a non-natively-focusable element (such as a heading) to show/hide related content. While it works for mouse users, this approach does not guarantee that the widget is navigable for keyboard users (particularly in browsers that don't properly support the tabindex attribute), which are necessary for both screen readers and many mobile devices. In other words, it's potentially neither operable nor robust.

To create a collapsible content widget that works for everyone — and doesn't compromise the experience for screen reader users — we had to rethink what "accessibility" means when showing and hiding content.

Our approach

This markup provides a usable and natively accessible basic experience in all browsers.

If JavaScript is present, we use it to apply enhancements that transform this markup into a functioning collapsible widget with a number of accessibility features. The enhancement script appends several attributes and elements to the basic markup:

• classes are assigned to the heading element which hide the Details content and apply a visual cue (icon) to indicate that it can be expanded or collapsed
• a span tag is appended to the heading immediately before the text label which contains the word "Show" followed by a single space if the content is hidden by default; when the content is shown, the script dynamically updates this word to "Hide." This span is intended only for screen readers to audibly describe the heading's function as a toggle link (i.e., "Show Details"), so it's hidden from standard browsers with absolute positioning and a large negative left value
• a standard anchor link element is wrapped around the heading content to allow it to receive keyboard focus and be accessed with the Tab key
• an aria-hidden attribute is assigned to the unordered list to ensure that it is truly hidden from ARIA-enabled screen readers when it is hidden from sight (aria-hidden="true"). While display: none; will sufficiently hide the content in current screen readers, future screen readers may not continue to obey visual styles like display, so adding this attribute is considered good, fail-safe practice.
• classes are also appended to the unordered list to show or hide it visually with CSS. To hide the content, we use the display: none CSS property so that the content is completely hidden from all users

The resulting enhanced markup looks like this:

And the enhanced classes for providing feedback are structured as follows – notice that we use a single background image sprite (icon-triangle.png), and simply adjust the background position to show the appropriate state:

NOTE on testing browser capabilities: To ensure that the browser can fully support all enhancements, we recommend using our EnhanceJS framework, which tests browsers' CSS and JavaScript capabilities and applies enhancements only after those tests are passed. Read more about EnhanceJS here: Introducing EnhanceJS: A smarter, safer way to apply progressive enhancement.

What we accomplish

When built as described above, our collapsible content widget incorporates specific features to meet the four accessibility principles outlined by WCAG:

• To ensure that it’s perceivable and understandable, it includes cues for both visual and screen reader users that indicate the heading element will show and hide associated content. Visual users see an icon that changes orientation based on the content's state; for screen reader users, the script conditionally appends the word "Show" or "Hide" before the heading text to describe the content's state and provide appropriate language to indicate how the heading is used. Additionally, the widget provides feedback to ARIA-enabled screen readers with the ARIA attribute, aria-hidden; it's set to true when the content is hidden, and false when shown.
• To make it operable, we ensure that the widget is fully navigable and controllable with the keyboard. When CSS and JavaScript enhancements are applied to the page, the script wraps each heading element's text with an anchor element so that the user can navigate to and focus on the heading with the Tab key, and hide or show related content with the Enter key.
• And our progressive enhancement approach helps us ensure it’s robust: The foundation is semantic HTML, which is accessible and usable on all browsers; only when a browser is capable of enhancements is the markup transformed into a collapsible widget with enhanced styling and behavior.

Looking ahead

The HTML5 spec includes a new element called details, which if implemented as proposed, will provide a native collapsible widget that will require no JavaScript and will be accessible without requiring any additional work. No browsers have adopted the details element at this time, but it does present a potential alternative to this approach that we may be able to use in the future. Bruce Lawson provides an interesting summary of details and an argument in favor of using semantic interactive elements over JavaScript.

How to use the plugin

Download the collapsible content plugin script (see instructions below), and reference it and the jQuery library in your page. You'll also need to append the CSS classes listed above for the collapsed state of the widget. NOTE: You'll likely need to edit this CSS to fit with your own project's design.

Call the collapsible plugin on the heading or other element that you're using to show related content; the plugin then assumes that the next element in the source order is the content block to show/hide. For example, on DOM ready you can call the plugin on all H2 elements:

Where to download it

If you've already purchased Designing with Progressive Enhancement, you can download all twelve widgets at the code examples download page.

For the collapsible content plugin and all others that have been released publicly as open source, download the zip.

To learn more, check out Designing with Progressive Enhancement's open-source plugin Google Code repository: http://code.google.com/p/dwpe/.

Help us improve the code

We keep track of issues (feature requests or found defects) in the DWPE Google Code site. Please take a look at our list, and feel free to add to it if you find a bug or have a specific idea about how to improve the plugin that we haven't identified: http://code.google.com/p/dwpe/issues/list. If you think you can help on a particular issue, please attach a patch and we'll review it as soon as possible.

Thoughts? Feedback?

We'd love to hear what you think of this plugin. Please leave us a comment on our blog!

Event Delegation, Again

The key to having JavaScript handle hundreds, or even thousands, of elements on a page is to use event delegation. As Louis-Rémi Babé described in Working with Events, Part 3: More Event Delegation with jQuery, jQuery's .live() method makes event delegation dead easy. A simple tooltip script using .live() might look something like this:

This script does the following:

• Creates a single tooltip element that will be shown and hidden as the user mouses over links (line 1)
• Hides the tooltip and appends it to the body (line 1)
• Changes the tooltip's contents according to the moused-over link's title and href attributes (lines 7 and 14)
• Places the tooltip on the page 12px below and to the right of the cursor position at the time that it entered the link (lines 9–13)
• Shows the tooltip (line 15)
• Sets the link's title attribute to an empty string when the user mouses over the link; this prevents the browser's default tooltip from appearing (line 8)
• Sets the link's title back to what it was originally and hides the tooltip when the user mouses out of the link (lines 16–19)

A Little Style

At minimum, the tooltip needs to have the position: absolute style declaration for it to be positioned correctly on the page, but I threw in a little extra CSS to make it look more appealing:

Typically I like to include live demos directly in the blog entry, but since this one involves 2,000 links, I've set up separate demo pages. Check out the tooltip demo using .live(), or download the zip.

A Little Less Simple, A Little More Speedy

Using .live() in this way avoids binding event handlers directly to the thousands of links on the page. However, it doesn't prevent jQuery from searching the entire document for all of those links. After all, I'm still using the $('a') jQuery function. Also, at least for now, .live() binds events to document, forcing event bubbling all the way up the DOM each time. If there is a noticeable performance lag when the script is initially executed, it may help to use custom event delegation.

Using custom event delegation, I bind the events to a containing table element:

With this approach, I needed to first make sure I was dealing with a link before I tried to do anything with it. Line 5 uses the .closest() method to select the <a> that is either the event.target or one of its ancestors. Line 6 checks the length property to see if any elements are included in the variable declared in line 5.

Note the use of .bind() instead of .live() and event.target instead of this. I could have used the .mouseover() and .mouseout() shortcut methods, but since I used .live() in the first example, it was easier to simply replace "live" with "bind." Also, you may be wondering why I used mouseover / mouseout when I could have used mouseenter / mouseleave or even the .hover() method (which uses mouseenter and mouseleave internally). The reason is that mouseenter and mouseleave prevent the event bubbling that this script relies on for its event delegation. Those two events would be triggered only when the mouse enters or leaves the full table, while mouseover and mouseout are triggered whenever the mouse enters or leaves any of the table's descendant elements, as well.

View the demo using custom event delegation, or download the zip.

One more Enhancement

Some people like having the tooltip move along with the cursor, as long as the mouse is over the element. Sometimes it's nice to be able move the tooltip a little if it initially overlaps something important. Adding the basic functionality is pretty straightforward. Just bind the mousemove event to the same table element:

With the addition of lines 25 through 32, as the mouse moves over the links, the tooltip's top and left style properties are continually updated based on the mouse's position.

Try the demo and watch the tooltip move along with the mouse position, or download the zip.

The Plugin

The plugin doesn't offer much more than the scripts in this post, but feel free to try it out. One difference is that it doesn't rely on the .closest() method, so it can be used with jQuery 1.2.6 if you're stuck with that version for some reason. The syntax is a little funky:

The containerElement selector provides context so you can specify where exactly the event handlers are bound (unlike .live(), which binds to the document). The first argument of .eztip() is required. It should be a selector that matches the elements for which you wish to show a tooltip. The second argument is the typical options object, allowing for a handful of objects that you might expect to find in a stripped down tooltip plugin.

Let's Make Better Mistakes Tomorrow

The tooltip scripts in this post work fine, but they repeat code where they really shouldn't. Stay tuned tomorrow for a brief tutorial on one way to avoid such code repetition.

Here is a typical example of append misuse:

Ran Once: Profile (308.697ms, 17861 calls, Firefox 3.06)
Ran in a for loop 100 times: Profile (51782.295ms, 1805100 calls)

If you're coming from Prototype to jQuery, chances are this looks quite natural to you. It's the way that Prototype does node creation/insertion, but with a little bit of jQuery chaining thrown in. Let's see how we can improve this.

Ran Once: Profile (107.458ms, 3991 calls, Firefox 3.06)
Loop of 100: Profile (21641.336ms, 399100 calls)

Whoa! Nearly a 3x difference, and much simpler to look at. jQuery can take more then one node at a time and create them all at once. You also don't need to wrap it in $() before appending it. jQuery knows what to do. But wait, there's more!

Ran Once: Profile (30.792ms, 778 calls, Firefox 3.06)
Loop of 100: Profile (8505.37ms, 77800 calls)

Taking full advantage of the ability of jQuery to insert a chunk of html in a string means only having to call insert once. It's much quicker, with an approximately 9-10x speed increase from the initial algorithm! This will be fast enough for 95% of cases, but for strings with lots of string concatenation… Wait, there's more!

Credit for this one goes to Michael Geary
Ran Once: Profile (29.724ms, 778 calls, Firefox 3.06)
Loop of 100: Profile (8298.699ms, 77800 calls)

This version is a bit harder to understand, as the html is not in an easy to read format, and the results vary by browser* (see below for further analysis), but in most current and next generation browsers, adding to an array and joining it into a string at the end is quicker then doing string concatenations. So, if you are looping through a large number of string concatenation and need some more speed, you should consider this method. So, now we're done, right? This is as blazingly fast as we can get it? Not quite.

Ran Once: Profile (29.72ms, 587 calls, Firefox 3.06)
Loop of 100: Profile (8274.359ms, 58700 calls)

As handy as .each() is for small loops, calling a function that executes a callback inside of a loop will always be slower than just creating the loop in pure JavaScript. The difference here isn't so noticeable because the array I used only has a length of 190, but for really large loops it makes a measurable difference. In addition, while the difference is very slight (.000062 vs .000037 ms over 1,000,000 empty loops), it is quicker to save the array length in a variable and use it instead of looking up an object property every loop (thanks Karl Swedberg!).

For most of your uses, the method of creating one really long string and appending it at the end will be the best choice, as it makes the best use of the trade offs of code legibility, ease of programming, and speed.

Please tell me your methods for speeding up array loops or appending using jQuery in the comments below.

For completeness, I used jQuery 1.3.2, Firebug 1.3.3 and Fireunit 1.0a1 on Firefox 3.06 on a Mac to do the profiling. And the reallyLongArray I used was:

var arr = [1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 'cada', 
'2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 
'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 
'ffadscdasc', 'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 
6, 2, 3, 6, 'ffadscdasc', 'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 
'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 
2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 'cada', '2wd', 3, 7, 3, 
2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 'cada', '2wd', 
3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 
'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 
'ffadscdasc', 'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 
6, 2, 3, 6, 'ffadscdasc', 'cada', '2wd', 3, 7, 3, 2, 'sdf'];

Further analysis of += vs array.join, broken down by browser

---------------

FF3 		array.join is ~2x faster
Safari 3 	array.join ~1.5x faster
Opera 9		+= ~3x faster
ie6		array.join ~6x faster
ie7		array.join ~4x faster

FF3.1		+= array.join equal in speed
Chrome		+=  ~1.25x faster
IE8		array.join ~1.6x faster
Webkit		array.join ~2x faster

Raw results

FF3.06 		.2046  -  .25835 .1849  .17045
Opera9 		.1256  -  .12795 .12678 .12197
Safari3 	.1368  -  .14875 .13128 .13032
IE6 		3.359 - took forever, crashed/froze browser sometimes
IE7 		1.68985 - took forever

FF3.1		.0735  -  .0813 .0710 .0683
Chrome 		.0256  -  .025 .021 .031
Webkit 		.0655  -  .06602 .06527 .06533
IE8		.2921  -  .3104 .2905 .2755 

FF3.06 		.1056  -  .10701 .10439 .10541
Opera9 		.3355  -  .33091 .31484 .36066
Safari3 	.0813  -  .08128 .08089 .08172
IE6  		.5086  -  .50609 .50829 .51156
IE7 		.4101  -  .42265 .38875 .41891

FF3.1		.0743  -  .0766 .0721 .0741
Chrome 		.0315  -  .03 .048 .027 .021
Webkit 		.0300  -  .02962 .03123 .02937
IE8		.1832  -  .1841.1872 .1872 .1741

FF3.06 		1.81	-   1.897 2.015 1.518
Opera9 		.6306	-   .631 .634 .627
Safari3 	.9156	-   .931 .884 .932
IE6 		65.657	-   58.078 56.641 89.313 58.594  // I can see where += was a huge problem then.
IE7 		.9316	-   .937 .934 .924

FF3.1		.9141	-   .47 .663 1.123 .705 1.165 1.361 .698 1.128
Chrome 		.031	-   .039 .024 .02 .041
Webkit 		.996	-   .991 1.014 .983
IE8		.09	-   .094 .094 .078 .094 

FF3.06		.9143	-  .923  .83 .99
Opera9		1.773	-  1.832 1.747 1.741
Safari3		.2106	-  .249 .19 .193
IE6		.8368	-  2 .375 .469 2.078 .343 .36 .735 .625 .547
IE7		.4428	-  .531 .516 .391 .375 .438 .406 .609


FF3.1		1.070	-  1.221 .678 1.366 1.508 .665 1.423 .631
Chrome		.0318	-  .02 .022 .059 .026
Webkit		.1773	-  .175 .176 .181
IE8		.4820	-  .14 1.141 .156 .609 .625 .328 .375

Test the hostname

To identify the external links, we test for the location.hostname against the link's hostname, which will be represented by this.hostname once we have the selector in place, and make sure the two don't match. We should also test for the mere existence of this.hostname to avoid problems or false positives with "mailto" links. our tests will look like this: this.hostname && location.hostname !== this.hostname.

Use the filter function

Now let's wrap that test in a filter function. For our example, we'll test all links inside an "extlinks" element that match the above test. Here is what it looks like:

A $(document).ready() is wrapped around the script so that it will execute when the DOM has loaded. Line 4 shows the insertion of the image after each of the external links.

Demo

Here is a little demo using the above code. Of the three links, only the second points to a different site. We should see the external-link icon next to it.

So, that's it. Short and sweet.

Almost immediately upon changing the font-family and font-size of the blog post titles, I noticed a few unsightly widows (just to clarify, we're talking about typographical widows. My mother already suspects me of avoiding her; I don't want to add to her anxiety. ;) ).

Here is an example of one such widow:

See how the last word, "plugin," appears on its own line? According to a couple designerly friends of mine, that's a no-no. So, I considered for half a minute how to get that title to look more like this:

The lowly yet lovely non-breaking space ( ) would do the trick, but how to replace it for the regular, breaking space? I certainly wasn't about to manually edit all of the entries' titles. Not only would it take too long, but it would also pollute the markup with something that really shouldn't be there. No, what I needed was a little JavaScript.

Selecting the Titles

On this site, entry titles are wrapped in <h2><a href="foo"></a></h2>, which can be selected in jQuery with $('h2 a'). Easy. Now, because I want to manipulate the text of each title independently, I'll need to use the .each() method, which is basically a chainable for loop. Inside the .each() is where I substitute the last breaking space with the non-breaking variety. Here are three ways I came up with to achieve this.

Array

The first approach was to convert the title string into an array of words and then stitch the array items back together, dealing with the last one specially.

A couple things to note about line 5 above: (a) the variable is actually being declared (with a "var") because it's separated from the previous variable declaration by a comma rather than a statement-ending semicolon. (b) The JavaScript .pop() array method "pops" the last item off the array and returns it; so it's no longer part of h2Array, but its value is stored in the h2Last variable. This is especially handy for us, because we don't want the last word to appear twice.

Line 6 joins the remaining array items with a space between them and then appends the non-breaking space and the popped last item. Line 7 dumps that concatenated string back into the title, inside <h2><a></a></h2>.

String

The next approach involved working solely with strings, using the slice and lastIndexOf methods to split the the string into two pieces — one leading up to the last space, and one immediately following the last space.

As line 7 demonstrates, the two sliced strings are stitched back together to keep the last two words on the same line.

Regular Expression

The final technique is the one I ended up sticking with, partly because it's the tersest and partly because I have a fondness for regular expressions:

The distinguishing feature here is line 4, which uses the replace regular-expression method. This method takes two arguments, a pattern to match against and a replacement value. For the pattern, which appears between the two slashes, we first match a space and then match one or more "word characters" (letters, numerals, or underscores). The parentheses capture all but that initials space, and the "$" at the end ensures that the match appears at the end of the string. The replacement argument starts with the non-breaking space and follows with $1, which refers to the first (and in our case, only) parenthetical "capture group." (Please forgive me if I've provided too much detail about the regular expression. I'm never quite sure how much of this stuff is worth mentioning, but since this entry is targeting beginners, I suppose it's better to err on the side of too much.)

By the way, all three of these code examples can be reduced in length quite a bit. For example, the regular expression example can be pared down from 7 to 5 lines if we don't bother with the h2Text variable and instead do something like this:

$(this).html($(this).text().replace(/ (\w+)$/,' $1'));

However, the code is usually easier to read and maintain (for me, at least) if the value is first stored in a variable.

Any suggestions for improvement here? Any other approaches that you would recommend instead? Leave a comment.

This was also the same month I discovered a new plugin which has dramatically changed how I develop applications with jQuery. The plugin in question is Dan Webb's Low Pro for jQuery, a port of the plugin of the same name for Prototype.

What is Low Pro?

So what is Low Pro? It's a plugin that provides a way of making more object-oriented JavaScript through event delegation. jQuery's plugin architecture provides a really simple way of extending the core functionality, but there is no easy way of making macros of code that do several types of events on one element. Until now!

Probably the simplest way to explain how Low Pro works is to build a quick demonstration. Sometimes I find that too many tutorials out there expect prior knowledge, so with that in mind, I will try to make the tutorial as simple as possible. However, this example does use another couple of plugins that are outside the scope of this tutorial:

• Live Query - Low Pro uses this plugin to make binding to dynamic elements in the DOM easier.
• jQuery Validation - We'll use this plugin to show how we can bind other plugin functions to events.

Both these plugins already have excellent documentation, so if you wish to extend this example, please check them out.

Example 1: Creating a re-usable registration form

For this example we'll build a simple user registration form. This is something that is common enough on the web, but a nice advantage of this example is that it can be used over and over again with little or no modification. Hopefully once you have learned this pattern, you will be able to see lots of other applications that can be reused over and over again in the same fashion.

Our first step is to create our basic form:

Now, we create our JavaScript file called reg-form.js. In here, we will create our class that we'll attach to the form. Inside this class, we'll create some functions that trigger on specific events. Every class created with Low Pro takes the form of $.klass({...});. Inside the curly braces, we use JavaScript prototype nature to create a pseudo-class. We will call our example RegisterForm.

If you have developed in languages like PHP, Python, or Java, you've probably seen something like this before. This first function, initialize, is a reserved function in Low Pro that accepts one parameter—an options parameter (we'll discuss that later). This function is always called whenever you bind a class to an element. Because it does not require any event to trigger, it is very useful for setting up initial data or events on dynamic DOM elements.

Validation

The first thing we'll do is create our JavaScript validation rules. This tutorial does not cover the creation of these rules; however, they should be reasonably understandable. If you would like more information, please check out the excellent documentation.

Notice that I am using this.element instead of $('#lowpro-form') inside the function. Low Pro provides this handy alias so you always work with the correct object. If you are going to be writing a complex function, it's always a good idea within the function to assign it to another variable.

But this code isn't actually doing anything yet. This is because we now need to bind the class to the form. Here is where we go back to the good old jQuery we know and love. Below the class, put this in the file:

Now, open up the page in your browser and start to type into the fields. You should start to see the validation rules apply to the fields. Congratulations, you've written your first re-usable class with Low Pro!

Enhancements

Now that we have our validation rules, let's start to make the form a bit more sexy. First, something simple. Let's make sure that the first field (the username field) is always selected first, so the user can easily tab down the form. After the validation method inside the initalize function, add this:

Refresh the page, and your username field should now get the focus.

Now let's introduce another event into the mix. When the user submits the form, we want to let the user know that it's being sent to the server. To do this, we could notify the user by changing the text on the button from "Register" to "Submitting".

So there we have it: A reusable, fully functional Ajax registration form with validation. You can check out a demo here and also grab the source code of this example from my repository.

One final thing I should touch on in this first tutorial is the initialize function's options parameter. When attaching any Low Pro class, the initialize function accepts an object containing any options you want to pass into the function:

In our above example, we'll add a tag to display a message of the day. In the HTML, create a div with a class of motd. Next, add the following code into the initalize function:

Now, when we attach our class to the form, we use the following:

When you now refresh the form, you should see a message on the screen.

Well, that wraps it up for this tutorial. I hope I've given you a small idea of the power that Low Pro contains. In conjunction with LiveQuery, you can really create some dynamic and interesting applications.

If anyone would be interested in more tutorials like this, then please leave a comment and let me know what you think.

How CSS and JavaScript Are Different

So, what's this important difference?

In CSS, style rules are automatically applied to any element that matches the selectors, no matter when those elements are added to the document (DOM).

In JavaScript, event handlers that are registered for elements in the document apply only to those elements that are part of the DOM at the time the event is attached. If we add similar elements to the DOM at a later time, whether through simple DOM manipulation or ajax, CSS will give those elements the same appearance, but JavaScript will not automatically make them act the same way.

For example, let's say we have "<button class="alert">Alert!</button>" in our document, and we want to attach a click handler to it that generates an alert message. In jQuery, we might do so with the following code:

Here we are registering the click handler for the button with a class of "alert" as soon as the DOM has loaded. So, the button is there, and we have a click function bound to it. If we add a second <button class="alert"> later on, however, it will know nothing about that click handler. The click event had been dealt with before this second button existed. So, the second button will not generate an alert.

Let's test what we've just discussed. I've added a script with the above three lines of jQuery code so that the following button will produce an alert message when clicked. Try it: Alert!

Events Don't Work with Added Elements

Now, let's create a new button (if we don't already have a second one) using jQuery code like this:

create the button

Have you clicked the link to create the second button? Great. Now click that button. It does nothing. Just as expected.

CSS Continues to "Work" with Newly Created Elements

Now let's take a look at another example. In this one, we have three list items—two plain items and one with a class of special:

Press the "I am special" button to create a new list item with a class of "special":

• plain
• special I am special
• plain

Notice that, like the first special li, the new one has the yellow background. The CSS has come through for us. But press the newly created "I am new" button and, just as with the second alert above, nothing happens. The jQuery code we're using to add the new item says that upon clicking a button inside a list item with a class of "special" (which itself is inside an element with id of "list1") a new list item with class="special" should be inserted after the list item in which the button was clicked:

So, how can we get the events to carry over to the new elements? Two common approaches are event delegation and "re-binding" event handlers. In this entry, we'll examine event delegation; in part 2, we'll explore ways to re-bind.

Event Delegation: Getting Events to Embrace New Elements

The general idea of event delegation is to bind the event handler to a containing element and then have an action take place based on which specific element within that containing element is targeted. Let's say we have another unordered list: <ul id="list2"> ... </ul>. Instead of attaching the .click() method to a button — $('#list2 li.special button').click(...) — we can attach it to the entire surrounding <ul>. Through the magic of "bubbling," any click on the button is also a click on the button's surrounding list item, the list as a whole, the containing div, and all the way up to the window object. Since the <ul> that gets clicked is the same one each time (we're only creating items within the <ul>), the same thing will happen when clicking on all of the buttons, regardless of when they were created.

When we use event delegation, we need to pass in the "event" argument. So, in our case, instead of .click(), we'll have .click(event). We don't have to name this argument event. We can call it e or evt or gummy or whatever we want. I just like to use labels that are as obvious as possible because I have a hard time keeping track of things. Here is what we have so far:

So far, the code is very similar to our first attempt, except for the selector we're starting with (#list2) and the addition of the event argument. Now we need to determine whether what is being clicked inside the <ul> is a "special" button or not. If it is, we can add a new <li class="special">. We check the clicked element by using the "target" property of the event argument:

Line 4 above puts the target element in a jQuery wrapper and stores it in the $tgt variable. Line 5 checks whether the click's target is a button. If it is, the new list item is inserted after the parent of the clicked button. Let's try it:

• plain
• special I am special
• plain

I put an additional two lines at the end to demonstrate that a click on one of the buttons is still considered a click on the <ul> You'll see that clicking anywhere within the <ul> toggles its background between pink and blue.

It's probably worth noting that jQuery makes working with the event argument cross-browser friendly. If you do this sort of thing with plain JavaScript and DOM nodes, you'd have to do something like this:

var list2 = document.getElementById('list2');
list2.onclick = function(e) {
  var e = e || window.event;
  var tgt = e.target || e.srcElement;
  if (tgt.nodeName.toLowerCase() == 'button') {
    // do something
  }
};

As you can see, it's a bit of a hassle.

Another Huge Benefit of Event Delegation

Event delegation is also a great way to avoid crippling the user's browser when you're working with a huge document. For example, if you have a table with thousands of cells, and you want something to happen when the user clicks on one, you won't want to attach a click handler to every single one of them (believe me, it can get ugly). Instead, you can attach the click handler to a single table element and use event.target to pinpoint the cell that is being clicked:

Note that I had to account for the possibility of clicking in a child/descendant of a table cell, but this seems a small inconvenience for the great performance increase that event delegation affords.

Coming Up Next

In part 2 of this tutorial, we'll look at how to get events to carry over to newly created elements through careful placement of function calls. We'll also, necessarily, examine unbinding events and using namespaced events. In the meantime, I hope you find part 1 useful. If I've made any mistakes, especially in my terminology, please don't hesitate to point them.

Here is the simple definition list structure that I'll be using for the example:

First Steps

As usual, we start the script with a "document.ready" line so that it can be fired when the DOM has finished loading. Next comes our primary selector expression. For this example, I've given the targeted <dl> element a class of "expander" so that we don't inadvertently attach the behavior to other <dl>s. And since we're manipulating the contents of each <dd> independently of one another, we can make things happen inside an .each() method:

We ought to declare some variables now. The first two will go right after the document.ready line, while the others will appear inside the .each() method because they change with each <dd> element.

• slicePoint (integer): the number of characters at which the contents will be sliced into two parts. Note: any tag names in the HTML that appear inside the <dd> before the slicePoint will be counted along with the text characters.
• widow (integer): this is a threshold of sorts for whether we want to initially hide part of the <dd>'s contents. If after slicing the contents in two there are fewer words in the second part than the value set by widow, we won't bother hiding anything.

• allText (string): the full contents of the <dd>
• startText (string): the first part of the <dd>'s contents — the part that is immediately visible. First, all characters up to the slicePoint are included, and then any "word" characters at the end of the string are removed to avoid ending with a partial word. Keep in mind that in almost every case this approach will leave us with fewer characters than we indicated in the slicePoint variable
• endText (string): the second part of the <dd>'s contents. This part is initially hidden from view, replaced by a "read more..." link.

Here is what we have so far:

Although jQuery has its own .slice() method, which operates on a jQuery object, we're using JavaScript's native method, which can operate on both strings (as is the case here) and arrays. Our first use of .slice(), declaring the startText variable, has two arguments — one for the beginning position of the string and one for the ending. Our second has only one argument, for the starting position; the (allText) string's length is the implied ending position. Also, note that for startText, we're chaining .slice() and the .replace() regular expression method.

Manipulating the Contents

Now that we have our two blocks of content, we're going to add a "read more..." link after the startText and wrap the endText in a span (with a class of "details"), but only if there are more words than the value defined by the widow variable. (tangent: am I the only one who can't type "widow" right the first time, always typing "window" instead?). There are many ways to create new elements and insert them into the DOM with jQuery. For this example, we're going to use the .html() method, create an array of strings inside it, and join those strings.

I picked up that technique of creating an array and joining its elements from the jQuery Google Group. It seems cleaner than string concatenation somehow, and rumor has it that it's a bit faster, too.

Finishing Touches

We have everything in place now, so all we need to do is hide the content inside our newly created <span class="details"> and attach a click handler to the "read more" link. Here is the completed code:

I used a .fadeIn() because I like the way it looks, but a simple .show() would do. The return false; line is important to prevent a jump to the top of the page on click.

the Demo

Here is a little demo:

Benedick's Question: I pray you, what is he?

Beatrice's Answer: Why, he is the prince's jester: a very dull fool; only his gift is in devising impossible slanders: none but libertines delight in him; and the commendation is not in his wit, but in his villany; for he both pleases men and angers them, and then they laugh at him and beat him. I am sure he is in the fleet: I would he had boarded me. (Much Ado About Nothing, II.1)

Benedick's Question: I do love nothing in the world so well as you: is not that strange?

Beatrice's Answer: As strange as the thing I know not. It were as possible for me to say I loved nothing so well as you: but believe me not; and yet I lie not; I confess nothing, nor I deny nothing. (Much Ado About Nothing, IV.1)

Karl's Question: Why aren't you using another question from Much Ado About Nothing here?

Karl's Answer: Because I'm lazy. And besides, this demo is getting a little too pretentious.