Written Articles

• Getting Started with jQuery – this is the official jQuery getting started guide.
• jQuery for JavaScript Programmers – Simon Willison (creator of django) gives you an introduction to jQuery for people who already understand JavaScript.
• jQuery Crash Course – Nathan Smith gives a quick introduction to jQuery on Digital Web Magazine.
• Introduction to jQuery – Rick Strahl, well-known for his work developing with Microsoft technologies, gives his introduction to jQuery with part two covering using jQuery with ASP.NET.

E-Books

• jQuery Fundamentals – open-source e-book written by Rebecca Murphey in collaboration with other well-known members of the jQuery community.
• jQuery Enlightenment – Cody Lindley’s e-book covers advanced topics on jQuery with links to working code examples in jsbin.

jQuery Books

• jQuery Cookbook – collaborative book by many jQuery team members with recipes on many jQuery topics.
• Learning jQuery 1.3 – walkthrough of learning the jQuery JavaScript library through hands-on examples and explanations. Authored by Karl Swedberg & Jonathan Chaffer
• jQuery Reference 1.4 – practical examples of the entire jQuery 1.4 API. Authored by Karl Swedberg & Jonathan Chaffer
• jQuery in Action 2nd edition – a fast-paced introduction to jQuery that will take your JavaScript programming to the next level. Authored by Bear Bibeault and Yehuda Katz.
• jQuery UI 1.7 – Build highly interactive web applications with ready-to-use widgets from the jQuery User Interface library. Authored by Dan Wellman.

Slideshows

• John Resig
  Introduction to jQuery
  Things You Might Not Know About jQuery

  Improve Your Web App with jQuery

• Remy Sharp
  (PDF download) jQuery for Designers
  (PDF download) jQuery write a bit more, do lots more

  More talks from Remy

• Marc Grabanski
  jQuery Essentials
• Simon Willison
  jQuery in 15 minutes

Learning Screencasts

• jQuery for Absolute Beginners – Net Tuts screencast series starts by downloading the library and eventually work our way up to creating an AJAX style-switcher.
• jQuery for Designers Screencasts – a myriad of screencast videos to teach you jQuery from a designer’s perspective.
• Intro to jQuery – Chris Coyier from CSS Tricks gives you an introduction to jQuery.

  Intro to jQuery Part 2

• Lullbot Introduction to jQuery – this video walks the viewer through the essential concepts and syntaxes needed to start writing simple-yet-powerful JavaScript using jQuery.
• The jQuery Course Prerelease – Marc Grabanski’s project to document all he’s learned from four years of jQuery programming into one educational course.
• Meet jQuery – this Peepcode Screencast teaches you jQuery through building a simple time-tracking application.
• An Intensive Introduction to jQuery – Ben Nadal takes a deep dive into jQuery.

Attend a training course

• Idea Foundry jQuery Training – The brains behind Collective Idea host jQuery classes led by Karl Swedberg in Holland, Michigan.
• jQuery Boot Camp – Ben Nadal’s training course in New York City.
• Thoughtbot Training – look here for training on jQuery from time to time.

Hire a Corporate jQuery Trainer

• appendTo Training – the jQuery company offers corporate training.
• Rebecca Murphey – started the open-source e-book jQuery Fundementals and is a member of the yayQuery podcast.
• Karl Swedberg – wrote the Learning jQuery books and runs this website.
• Marc Grabanski – creator of the jQuery UI Datepicker project and blogger.
• Ordered List – all around great guys, creators of the Harmony CMS, and active speakers and writers.

Conferences

• Carsonified Online jQuery Conference
• Official jQuery Conference – hosted in Boston, San Francisco, and other locations in the future.
• jQuery Summit – online conference.

jQuery Meetups

Another great way to learn more jQuery is to start or join a jQuery Meetup. Check to see if there is a meetup near you, and if not, start one!

Podcasts

• Official jQuery Pocast
• yayQuery video podcast

More Resources

• jQuery on Twitter
• Twitter Directory for Tag jQuery
• jQuery List
• 10 Things I Learned from the jQuery Source

Other Blogs

• Remy Sharp jQuery
• Filament Group
• Nemikor – Scott González
• Ben Alman
• Paul Irish
• Marc Grabanski
• Alex Sexton
• James Padolsey
• Script Junkie
• NCZOnline – Nicholas Zakas
• Perfection Kills – Juriy Zaytsev (kangax)
• Stoyan Stefanov
• Steve Souders
• CSS Tricks
• Web Designer Wall
• Janko At Warp Speed
• Marco Folio

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.

Priced at $199, the two-day conference is one of the best bargains you'll find anywhere for a full-on tech conference. The jQuery team is committed to keeping the price as low as possible, relying on the support of sponsors to help defray the cost of registration. jQuery developers from beginner to advanced will learn a ton, have a great time, and meet many others who are using jQuery in innovative ways to make the web a better place.

On a personal note, this will be the first jQuery conference ever that I won't be able to attend (regrettably, a scheduling conflict is keeping me home this time). But having heard many of the speakers in the past and having been involved a bit in the planning of this conference, I can assure you that you won't want to miss it. While we hope to continue offering a west-coast event on an annual basis, as we have done with the east-coast event a lot will depend on the level of interest and attendance this time around. So, what are you waiting for? Sign up now!

One brief personal plug: I will be teaching a 3-day jQuery class June 2–4 in beautiful Holland, Michigan. If for some reason you can't make it to the conference in April—or even if you can—you might want to consider taking the class. This will be the fourth class I've taught with Idea Foundry, and if it's anything like the others, we'll have a blast, with lots and lots of great learning.

Fortunately, jQuery makes it super easy to differentiate the Ajax requests from normal page views.

X-Requested-With Header

If you were to browse the jQuery source, you would see that jQuery adds a special HTTP header to (almost) every Ajax request it makes with $.ajax(), $.get(), $.getJSON(), $.post() and .load() methods.

Keep in mind, though, that the header is not sent with $.getScript() or any JSONP request made with $.ajax() or $.getJSON(), since they aren't technically Ajax requests.

Detection on the Server

By checking for this header, you can easily determine on the server if the request was initiated by jQuery. Each server-side language and web server combination will give you different ways of accessing this header, but let's look at a few.

In PHP, you can use this function to determine the type of request:

Sinatra and Ruby on Rails have special shortcuts already built in:

Since other libraries outside of jQuery also set the X-Requested-With header, many server languages have special support for reading it. Check the documentation for your favorite server language to see if it has any convenience methods for detecting an Ajax request.

A Small Example

Ok, let's apply this knowledge to add Ajax to a simple email signup form. Here is our existing HTML:

And here is the existing email.php (Note: on a normal error you might redirect back to show a message, or render the form again. This is for example only):

The previous two pages work together to provide a simple signup functionality, without JS or Ajax involvement.

Now let's add the Ajax. We’ll add the following to the form page:

Finally, we replace the initial PHP code block in our email.php file to take advantage of the Ajax submission:

Conclusion

That's it! A few lines of code, and your server side code can now render different content depending on how the request was generated. Now that you know how to detect jQuery Ajax events, you no longer need to resort to passing ajax: true as data on your requests or calling a separate file altogether.

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.