At first it may look like the new plugin supports barely any of the old options. We'll see how all the old options can be implemented using the three new options and the six events.

The old plugin had two arguments: data or url, and options. Lets start with that data-or-url argument. With the new autocomplete plugin, you'll just pass the data or url to the source option.

So, with the old plugin you'd have this code:

And that becomes, easy enough:

The same applies if you provided a URL as the first argument, although there is a difference between the two plugins for remote data. The old plugin expected a special format with pipes to separate values and newlines to separate rows. That is gone for good, the Autocomplete widget now works with JSON by default. The simplest form is the same as in the example above, an array of string values.

Instead of an array of strings, the widget also accepts an array of objects, with at least a label or value property, or both, in addition to whatever else you need. More on that can be found in the documentation and various demos, eg. the Custom Data demo shows how to use custom properties and even display them.

Lets look through the rest of the options for the old plugin, and what to do with them for the new plugin:

• autoFill: Gone with no immediate replacement available, for good reasons: The default behaviour when selecting items via keyboard now puts the focussed value into the input, like the Firefox Awesomebar does it. It's not the same as what the autoFill option did, but there should be no need to recreate that effect.
• cacheLength: There is no built-in caching support anymore, but it's really easy to implement your own, as shown by the Remote with caching demo.
• delay: Still exists with the same behaviour, but the default is always 300 milliseconds.
• extraParams: Extra params and all other Ajax related options can be customized by using a callback for the source option. Use $.ajax to send the actual request, with the response callback argument passed to source as the success callback for the $.ajax call. The Remote JSONP datasource demo has an example for that.
• formatItem, formatMatch, formatResult, highlight: All gone, instead use the source option to either provide the formatted data from your serverside, or implement a custom source to do special formatting. The combobox demo shows how to do that, with a more extensive explanation of that demo right on this site.
• matchCase, matchContains, matchSubset: All gone, too. The builtin matcher for local data will do a case-insensitive match-contains, everything else has to be implemented on the serverside or using the source option. The combobox linked just above also has an example for that.
• max: Gone; if your server sends too many items, pass a function for the source option that calls $.ajax and truncates or filters the resulting list.
• minChars: Still present, but was renamed to minLength. Behaves just the same, even the default is still the same, with minLength: 1.
• multiple, multipleSeperator: Not built-in anymore, but easy to recreate. There are two demos for this, once with local data, once with remote data.
• mustMatch: Gone, but easy to implement with the select event. Once more, the combobox provides an example for that.
• scroll, scrollHeight: These option are gone, but the underlying Menu widget actually has support for scrolling. If you have enough items and specify a height via CSS, the menu will scroll.
• selectFirst: Similar to autoFill (at the top of this list), this option is gone and has now immediate replacement, nor a need for one. The behaviour for selecting values is solid enough to make this option redundant.
• width: Gone and not required anymore. The menu will automatically be as wide as the input it completes, or wider, as the content requires. And you can always restrict with width using CSS.

And thats about it. If you're still looking for a particular replacement, take a look at the various events available, and study the use of the source-option within the various demos. If you still have a question, post on the Using jQuery UI forum. If you spot some mistake or see something that can be improved in this article, please let us know in the comments.

The jQuery UI 1.8 release brings along the new autocomplete widget. An autocomplete adds a list of suggestions to an input field, displayed and filtered while the user is typing. This could be attached to a search field, suggesting either search terms or just matching results for faster navigation. But what if there is a fixed list of options, usually implemented as a standard HTML select element, where the ability to filter would help users find the right value way faster?

That's a "combobox." A combobox works like a select, but also has an input field to filter the options by typing. jQuery UI 1.8 actually provides a sample implementation of a combobox as a demo. In this article, we'll look under the hood of the combobox demo, to explore both the combobox widget and the autocomplete widget that it uses.

Let's starts with the initial markup:

Nothing special there, just a label and a select element with a few options.

The code to apply the combobox widget to the select is quite simple, too:

Let's look at the code for this combobox widget. First, the full code, to give you an overview. We'll dig into the details step-by-step afterwards.

Let's break this down, piece by piece:

This defines a new widget, in the ui namespace (don't use this for your own widgets, it's reserved for jQuery UI widgets) and adds the only method, _create. This is the constructor method for jQuery UI widgets, and will be called only once. In versions prior to 1.8 it was called _init. The _init method still exists, but it is called each time you call .combobox() (with or without options). Keep in mind that our widget implementation is not complete, as it lacks the destroy method. It's just a demo.

Coming up next is the creation of an input element and applying the autocomplete to it, with data provided by the select element.

It starts with a few variable declarations: var self = this will be used inside callbacks below, where this will refer to something else. The var select references the select element on which the combobox gets applied. To replace the select with the text input, the select is hidden.

The selected and value variables are used to initialized the autocomplete with the current value of the select.

An input element is created from scratch, inserted after the select element into the DOM, and transformed into an autocomplete widget. All three autocomplete options are customized:

• delay specifies the amount of time to wait for displaying data between each key press, here set to zero as the data is local
• minLength is set to 0, too, so that a cursor-down or -up key press will display the autocomplete menu, even when nothing was entered.
• source provides the filtered data to display

Let's break down the source implementation:

There is a bit of matching and mapping involved here: At first, a regular expression object is defined, based on the entered term, escaped with the help of the $.ui.autocomplte.escapeRegex utility method. This regex gets reused in the function below. The response argument, a callback, gets called, to provide the data to display. The argument passed is the result of the call to select.find("option").map(callback). That finds all option elements within our original select, then maps each option to a different object, implemented in another callback passed to the map method.

This callback will return undefined, thereby removing an item, when a search term is present and the text of the option doesn't match the entered value. Otherwise (no term, or it matches), it'll return an object with three properties:

• label: based on the text of the option, with the matched term highlighted with some regexing (another example of a write-only regular expression)
• value: the unmodified text of the option, to be inserted into the text input field
• option: the option element itself, to update the select (via the selected-property) or to pass on in custom events

The label and value properties are expected by the autocomplete widget, the option property has an arbitrary name, used here only by the combobox widget.

Before, I mentioned that the combobox widget customizes all three autocomplete options, but there were actually five options specified. The fourth and fifth properties, select and change, are event. This is the select implementation:

The ui.item argument refers to the data we provided in the source option. Via the ui.item.option property we can update the underlying select to the selected item, as well as triggering a selected events for further customization of the combobox widget.

To cover the case where no selection is made, the change event is used:

Here the entered value is used to try and match a selection. If the value doesn't match anything, it'll get removed, and the underlying select is set to an empty value, too.

The next block customizes the _renderItem method of the underlying autocomplete. This is necessary to output the highlighting on each row, as autocomplete by default will escape any html.

And finally, the last block creates the button that opens the full list of options:

Another element is created on-the-fly. It gets tabIndex="-1" to take it out of the tab order, as it's mostly useful for mouse interactions. Keyboard interaction is already covered by the input element. It gets a title attribute to provide a tooltip and is inserted after the input element into the DOM. A call to .button() with some options together with a bit of class-mangling transforms the button into a Button widget that displays a down-arrow icon with rounded corners on the right (the input has rounded-corners on the left).

Finally a click event is bound to the button: If the autocomplete menu is already visible, it gets closed, otherwise the autocomplete's search method is called with an empty string as the argument, to search for all elements, independent of the current value within the input. As the input handles keyboard input, it gets focused. Having focus on the button would be useless or would require duplicate keyboard interaction that the input already supports.

And that's it! We can see that the autocomplete widget is flexible enough to allow all this with option customization, events, and calling a few methods. We don't have to "subclass" autocomplete (creating a new widget with the autocomplete as the parent prototype instead of $.widget). Instead, we can make the combobox mostly independent of any internal or private autocomplete methods. For the full experience and latest version, check out the combobox demo on the jQuery UI site.

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!

Quick Review

In my last three tutorials, I discussed how to put together a very simple tooltip, and I introduced a different feature or concept in each one. In an effort to continue in the spirit of simplicity, I will refrain from repeating the explanations of previous posts and instead simply direct your attention to them before we begin:

• Simple Tooltip for Huge Number of Elements
• Binding Multiple Events to Reduce Redundancy with Event Delegation Tooltips
• Using setTimeout to Delay Showing Event Delegation Tooltips

Setup

Now I'd like to round off this series with a little exploration of one way to keep the tooltip within view when it might otherwise get clipped to the right or the bottom of the viewable area.

As with the previous tooltip tutorials, I start by setting a few variables:

The first line creates the tooltip container, hides it, appends it to the body, and stores a reference to it for later use. The next line is more for convenience than anything else (though it might provide nominal performance benefit), since I'll be calling jQuery methods on the window object a few times. The third line will be used as a reference to a setTimeout function for delaying the tooltip's visibility.

Position the Tip

Okay. So far, so boring. But here is where things start getting fun. I have a few more pieces I want to store and retrieve, but since they're all related, I figured it would be nice to have them be properties of a single tip object:

Since the position needs to be calculated each time the tooltip is displayed, I've made position a function—in other words, a method of the tip object. This is the part that does the hard work of figuring out where exactly to put the tooltip and whether or not to "flip" it above or to the left of the mouse position. Because this method is going to be called repeatedly as the mouse moves over a link, I wanted to make it as bare-bones as possible. I defined two objects. The first one contains the x and y mouse coordinates. The other contains two sets of numbers: (x) the inner width of the browser window and outer width of the tooltip, and (y) the distance from the top of the document to the bottom edge of the viewable area and the outer height of the tooltip.

Notice that the properties of the dimensions object have the same names as the properties of the positions object. I did that so I could easily loop through the properties of one and use the same loop variable for both, as shown in lines 18-26 above. Within that little loop, I'm testing to see if the tooltip, plus the mouse position, plus our user-defined "offset," is greater than the window dimension—on the x axis and then on the y. If it is, I subtract the tooltip's dimension and its offset from the mouse position; if not, I just add the offset to the mouse position.

Finally, I set the top and left style properties of the tooltip with the appropriate coordinates. I suppose it would have been cool to name the properties of my two objects "left" and "top". That way, I could have written $liveTip.css(positions). But, x and y make more sense to me as I read them, so I figured it would be worth a few extra bytes to help me remember what I was doing here when I look back at the script later on.

Wire it up

Now that the tooltip positioning is taken care of, it's time to hook it up to some events. If you read Binding Multiple Events to Reduce Redundancy with Event Delegation Tooltips, you may remember that I used the .bind() method and passed in three events: mouseover, mouseout, and mousemove. That seemed to work fine, but now that jQuery 1.4.2 has provided us with the more convenient .delegate() method, we can use that one instead. Jordan Boesch recently wrote a nice introductory article on Using Delegate and Undelegate in jQuery, so check that out if you're uncertain about what the method does. One thing I'd like to note about it, though, is that it's currently the only jQuery method (of its kind) that doesn't map the this keyword in the callback function to the current element within the matched set. In the code below, for example, the callback function for other methods would map this to the "#mytable" element; for .delegate(), the function maps to its first argument, "a" — when it is within "#mytable" and when it or one of its ancestors is the event.target element. I hope this little .delegate() excursion didn't confuse matters. Suffice it to say that the method allows us to use this for the link we want to act on, instead of going through the rigamarole of checking for the event target ourselves as I did in my previous tooltip articles.

Since a lot of what's going on in this code snippet has already been discussed in my previous posts, I'll just mention a couple things.

The tip positioning occurs in line 13, triggered by the mouseover event, and in line 34, triggered by mousemove. It only gets triggered in the mousemove, however, if the mouse has been over the link for the time specified in tip.delay for the setTimeout. That's where the link's "tipActive" data attribute is set.

This time around, I also added a little fade effect to show the tooltip. As a safeguard, I hide the tooltip and reset its opacity to 0 (using .fadeout() with a 0ms duration) before fading it in, because jQuery will only fade in elements if they are hidden to begin with. This extra step is only necessary if the fade-in duration is greater than tip.delay.

Conclusion

So that wraps up this tooltip series. As always, if you see something that I could do better, please leave a comment. I always appreciate learning better ways of plying the craft. And if you have any questions about what's going on in the code, please point out what you'd like me to clarify.

To see this one in action, visit the Flip Tip demo page. You can also look at the complete JavaScript file or download a zip of both the HTML and JavaScript.

Then appended some photos via ajax later on:

The click event would still apply to that new image without having to re-bind the event. Handy, isn't it?

Not too long ago, the .live() method was brought up for discussion for a few reasons. One problem discussed is that .live() fails when you try to use it alongside traversals like:

and also when you pass any native DOM elements like:

Unfortunately, when you use .live(), it has to be at the top of the chain like so:

Because this can be frustrating and confusing for many users who are used to the traversing and chainability that jQuery offers, it sparked a discussion about the syntax for .live(). Why does it look like all the other methods, yet does not behave the same? Since changing the syntax would result in a whirlwind of code breakage, the jQuery team decided to introduce .delegate() and .undelegate() to complement .live() and .die(). Here's an example of how you would normally use .live() and .die() and how you can now use .delegate() and .undelegate():

Old way

New way

The benefit of delegate() is that it allows you to specify its context. This way, it ensures that we do not bubble all the way up the DOM tree to capture the target of the element. With the .live() method, it bubbles all the way up the DOM each time unless you set context like so: $('td', $('table')[0]).live('hover', function(){}). That just looks ugly.

Some often like to think of delegate() like a bind() call. The syntax is a little different as you can see below.

In short, the difference between .bind() and .delegate() is that .bind() will only add events to the elements that are on the page when you call it. .delegate() is listening for new elements and then adding events to them when they appear on the page.

The gotchas of delegate

While it does behave like .bind(), it does not allow you to pass an object map of events like .bind() does. Take this .bind() method for example:

An error will be thrown when you try to do:

I'm not sure the reasoning behind not implementing this, but I guess I'm not the only one pondering it.

Granted, .bind() didn't have this feature until jQuery 1.4. But if you'd like this same feature in .live() and .delegate(), Robert Katic wrote a small piece of code that you can include. Grab the gist here.

I recommend using Robert Katic's patch above, but of course there are other approaches people can take. For example, you can rig up your own custom object map:

Another "gotcha" with both .delegate() and .live() is that when you add the events mouseenter and mouseleave to an element, and then check the event type (e.type) in the callback function, it incorrectly displays as mouseover and mouseout. Using .bind(), on the other hand, it displays as mouseenter and mouseleave as expected. Here is an example:

UPDATE: This has been fixed and will be rolled out in the next version of jQuery.

Overall, the "gothcas" are no match for the benefits that .delegate() and .undelegate() provide. Truly great additions to the jQuery core.

Setting Up

Picking up where we left off last time, I'm going to create the tooltip div, declare a couple variables, and then bind "mouseover," "mousemove," and "mouseout" all at once. In addition to $livetip and tipTitle, I'm declaring showTip (and leaving it undefined for the moment) and delay. The showTip variable will be used as a reference for the setTimeout function, and delay will be used to set the time after which the function within setTimeout's argument will execute (in this case, 300ms).

Of course, you don't have to use a variable for the delay, but I like to have that sort of setting up top where I can find it easily. Also, if I ever decide to convert this script into a plugin, having the delay stored in a variable will make it simpler to convert it to an option.

Setting the Timeout

Inside the .bind(), and after the business of determining whether the event is being triggered by a link or one of its descendants, the setTimeout is called on line 12:

setTimeout is actually a method of the window object; as such, the this keyword inside its function argument will refer to window. It's not of much concern here because, with event delegation, we're relying on event.target rather than this, but I thought it might be worth mentioning anyway.

Note that within the setTimeout function, I'm storing a little data (line 13) for the link to indicate that the tooltip is active on it. This tipActive information then determines what to do on mouseout.

Clearing the Timeout

On mouseout, if the link has the tipActive data, that data is removed (line 29, below), the tooltip is hidden (line 30), and the link's original title attribute value is restored if tipTitle has a value (line 31). If that tipActive data is not associated with the link, then the timeout that was set on mouseover is reset with clearTimeout (line 33).

The mousemove part hasn't changed from what it was in the previous post, except that it first checks if the "tipActive" data is assigned to the link. I figured that setting the top and left properties of the tooltip is probably more work than doing a little check on the link's data, so why bother setting them if I don't have to?

So, that's it. Just add a simple setTimeout delay and conditionally clear it. If you want to set a delay on mouseout, you can do that the same way.

Check out the demo or download the zip (or neither, if you're stubborn).

Flipping the Tip

Next time, I'll show how to flip the tooltip from the right side of the cursor to the left if it would otherwise get cut off by the edge of the browser window.

For review, here is the final version of the script from the last post:

Bind Multiple Events at One Time

As I mentioned last time, this repeats code where it really shouldn't. For example, lines 5, 19, and 24 all check that moused-over element (or one of its ancestors) is a link. One way to reduce the repetition is to bind all three events at the same time (line 4):

This modification relies on the type property of the event object, checking it to see which of the three event types were triggered and acting accordingly. That way, I can get away with writing the $link and link declarations and the link check one time instead of two or three.

Other changes

Here are a few other changes worth mentioning:

• Line 1 declares the $livetip variable while at the same time creating the tooltip div and appending it to the body. Now the script can refer to that variable rather than having to call $('#livetip') each time it is shown, moved, hidden, and so on.
• Rather than wrap nearly everything in an if block, I made the function return if there is no link selected. Some people have a philosophical problem with multiple return points in a function, and it can make it hard to decipher and debug code sometimes, but here I think it's okay.
• On "mouseout" (lines 23-28), the script is resetting link.title to tipTitle only if tipTitle has a value. This, I'm hoping, fixes the problem reported by Moritz Peters of the tooltip not displaying correctly if you first mouse over a link before the document is ready.

Try the demo or download the zip (or both).

Adding a Delay

Tomorrow—for realz this time—I'll show how to add a short delay on mouseover before showing the tooltip.

P.S. You see the "$" in "$liveTip" and "$link"? There is nothing special about that—no special meaning given to "$" in JavaScript. It's just a convention that some jQuery folks have adopted to remind ourselves that the variable is holding a jQuery object.

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. For example, here 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.

From traditional event listening to event delegation

Since an event occurring on an element is propagated to all of its ancestors, an event listener can be bound to a single ancestor of numerous elements instead of being bound to all the elements individually.

Consider the following list items:

If we want to display the class of an item when it is clicked, a traditional event listener in jQuery would be written like this:

The event object passed to the handler has a target property which corresponds to the element that has been clicked.

The equivalent using event delegation would look like this:

Event delegation has two main advantages:

1. setting a single event listener instead of multiple ones is obviously faster;
2. any new element later added to the list will have the same behavior (as demonstrated in Working with Events, Part 1).

This translation to event delegation that we've just made is, however, slightly too simple, since our original aim was to display only the class of the list items. Using the previous snippet, the class of the unordered list itself can be displayed (by clicking to the left of a bullet-point). We thus have to make sure that the target of the click is a <li>.

Scanning the ancestors of the event.target: the .closest() method

With such a simple document, event delegation is really that easy to achieve. But things can get more complex if the items have children elements:

In this case, if the user clicks on one of the words item, the event.target will be a <u>. It is therefore necessary to loop through all of the ancestors of this original target to find the element that is "interesting" for us: the <li>

Notice that if the user clicks outside of an <li>, we have to stop looping through the ancestors at some point; in this case when we find the root of the document (which has no parentNode).

jQuery 1.3 introduced the .closest() method, which replaces this loop by a single line of code:

The parameter passed to the .closest() method is a CSS selector that will match the first interesting ancestor.

The context parameter

It can be noted that, when the click occurs outside of an <li>, we could stop looping through the ancestors before hitting the document root, but instead as soon as we hit the <ul>. jQuery 1.4 will introduce an optional context parameter to .closest() for this purpose:

Here this is the <ul> element to which the event listener has been bound. This optional parameter improves the performance of event delegation as it prevents the wasted resources of searching for an ancestor which cannot exist.

Event delegation in a single line: the .live() method

jQuery 1.3 also introduces .live(), a method which binds the event listener and implicitly calls the .closest() method to determine whether your event handler should be executed or not.

Note how different the syntax using the .live() method is. It seems that we have switched back to a traditional event binding. However, a big difference is that the event listener will work for any existing and future element matching our original selector. There is, of course, nothing magic: behind the scenes .live() simply binds the event listener to the document root and filters any event.target using the .closest() method.

A notable difference with the traditional event binding syntax is that we are not using the target property of the event object inside our event handler, but rather the currentTarget. Indeed, the target of the event is possibly a child of one <li>, whereas the currentTarget property refers to the element that has been found by the implicit .closest().

As explained on the Event Object documentation, the currentTarget property is supposed to be the current DOM element within the event bubbling phase, i.e. the element on which the event has been detected by the event listener, which will always be the element on which the event listener was bound. When using .live(), the currentTarget would therefore always be the document root and you would need to use .closest() once again on the original target to find an interesting ancestor.

This kind of code is required with jQuery 1.3, but as of jQuery 1.4, the currentTarget is modified internally and can thus be used to avoid the extra .closest() inside the event handler.

The context parameter

In jQuery 1.3 all live event listeners were effectively bound to the document root. This can hurt the performance of a web page since all events detected by an event listener will trigger the execution of an implicit .closest(), even though the event target might be totally out of interest.

In jQuery 1.4, .live() should be able to bind the event listener to a specific and more focused element of the document by taking advantage of the context of your jQuery object:

The context is the second parameter used to build our jQuery object. To be useful for .live() it has to be set as a pure DOM element, hence the [0] after $("ul"). Brandon Aaron has a useful article explaining the context parameter in detail.

Unbind for .live(): the .die() method

Just like .bind() has its .unbind() counterpart that allows for event listeners to be unbound, .live() has its .die() counterpart.

Unlike .bind(), .live() does not allow for namespaced events to be used.

Dealing with events that don't bubble

There are some events for which event delegation is traditionally not possible, simply because they do not bubble. The promise of jQuery 1.4 is nevertheless to make those events compatible with .live(). How this is achieved will be covered in the upcoming fourth part of this tutorial.