Upgrading to jQuery 1.2

As I'm sure most of you have already heard, the jQuery Project Team has just released a major new version (1.2) of our beloved JavaScript Library. Hat's off to John Resig and the gang for another spectacular release!

I'm going to upgrade this site to the new version this weekend. On a typical site, I'd feel pretty confident about moving forward without any hiccups—especially after hearing all the success stories on the jQuery discussion list. But since the nature of this site is to demonstrate techniques used with jQuery, its use of the library is probably more comprehensive (for lack of a better word) than most. Therefore, I want to be extra careful. My simple plan for the transition to 1.2 is described below, along with some discussion of the API changes, in the off chance that it helps others who wish to upgrade with caution.

Set Up

The first thing to do is upload three new files to the server: jQuery 1.2, the jQuery 1.1 compatibility plugin, and the XPath compatibility plugin.

Then, after referencing the new scripts on the site's pages, I'll look through my custom scripts and modify those that have methods removed from jQuery 1.2. For the scripts in tutorials, I'll label the parts of each blog entry that require one of the plugins to be used in conjunction with 1.2.

Replace XPath Selectors and Removed DOM Traversal Methods

It seems the main things to look out for are the XPath selectors and the four removed DOM traversal methods. XPath selectors include the single slash for the child selector, the double slash for the descendant selector, the [@attribute] notation for the attribute selector, and the [selector] for the Contains Predicate selector:

  1. The single slash ("/") can be replaced with the greater-than sign (">"). Example: change $('li/ul') to $('li > ul'). This selects all unordered lists that are direct children of a list item.
  2. The double slash can be replaced with a space. Example: change $('#container//p') to $('#container p'). This selects all paragraphs that are descendants of an element with an id of "container"
  3. In jQuery 1.2, the @ symbol in [@attribute] is deprecated. It will still work for attribute selectors, but it isn't necessary and should probably be removed for future compatibility. The [attribute] notation is in line with CSS (and most other JavaScript libraries) selectors rather than XPath. Example: change $('input[@type=text]') to $('input[type=text]'). This selects all input elements that have a type of "text"
  4. In jQuery 1.2, the XPath [selector] notation can be written as :has(selector) Example: change $('p[a]') to $('p:has(a)'). This selects all paragraphs that have a link.

Three of the removed DOM traversal methods — .lt() and .gt() and .eq() — can be rewritten easily with the new .slice() method, or with their corresponding pseudo-classes. The fourth — .contains() — can be replaced with a filter expression:

  1. Replace .lt(n) with .slice(0, n). Example: change $('li').lt(2) to $('li:lt(2)') or $('li').slice(0,2)
  2. Replace .gt(n) with .slice(n+1). Example: change $('li').gt(2) to $('li:gt(2)') or $('li').slice(3)
  3. Replace .eq(n) with .slice(n, n+1). Example: change $('li').eq(2) to $('li:eq(2)') or $('li').slice(2.3) The .eq() method has been restored as of jQuery version 1.2.1
  4. Replace .contains('text') with .filter(':contains(text)'). Example: change $('li').contains('scurryfunge') to $('li').filter(':contains(scurryfunge)')

Check for other Removed Methods

The DOM manipulation method .clone() no longer takes the optional deep argument, so instead of writing .clone(false), we need to write .clone().empty().

There are a handful of Ajax convenience methods that have been dropped in this release, too:

  • .loadIfModfied()
  • $.getIfModified()
  • $.ajaxTimeout
  • .evalScripts

You can find out more about how to replace them in the official jQuery 1.2 Release Notes.

Remove the Compatibility and XPath plugins

After having updated my code, I'll be removing the two plugins that make 1.2 backward compatible — at least for the pages that don't need them. I'll make sure they are still included in pages with tutorials that discuss them. And I'll add notes for how to accomplish the same stuff in 1.2 style.

Start Playing with all the new fun stuff that 1.2 has to offer

The Release Notes also describe a host of new features added to jQuery in this release. I'll be investigating them in the weeks to come and posting what I learn. So, stay tuned.