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.

Achieving the "optimum level" of customization is a bit of a balancing act… go too far either way and you've got an unusable plugin!

Bob and Sue

Let's say Bob has created a wicked new gallery plugin (called "superGallery") which takes a list of images and makes them navigable. Bob's thrown in some animation to make it more interesting. He's tried to make the plugin as customizable as possible, and has ended up with something like this:

The first thing that probably comes to your mind (ok, maybe not the first) is the prospect of how huge this plugin must be to accommodate such a level of customization. The plugin, if it weren't fictional, would probably be a lot larger than necessary. There are only so many kilobytes people will be willing to spend!

Now, our friend Bob thinks this is all fine; in fact, he's quite impressed with the plugin and its level of customization. He believes that all the options make for a more versatile solution, one which can be used in many different situations.

Sue, another friend of ours, has decided to use this new plugin. She has set up all of the options required and now has a working solution sitting in front of her. It's only five minutes later, after playing with the plugin, that she realizes the gallery would look much nicer if each image's width were animated at a slower speed. She hastily searches through Bob's documentation but finds no animateWidthDuration option!

Do you see the problem?

It's not really about how many options your plugin has; but what options it has!

Bob has gone a little over the top. The level of customization he's offering, while it may seem high, is actually quite low, especially considering all the possible things one might want to control when using this plugin. Bob has made the mistake of offering a lot of ridiculously specific options, rendering his plugin much more difficult to customize!

A better model

So it's pretty obvious: Bob needs a new customization model, one which does not relinquish control or abstract away the necessary details.

The reason Bob is so drawn to this high-level simplicity is that the jQuery framework very much lends itself to this mindset. Offering a previousButtonTextColor option is nice and simple, but let's face it, the vast majority of plugin users are going to want way more control!

Here are a few tips which should help you create a better set of customizable options for your plugins:

Don't create plugin-specific syntax

Developers who use your plugin shouldn't have to learn a new language or terminology just to get the job done.

Bob thought he was offering maximum customization with his delay option (look above). He made it so that with his plugin you can specify four different delays, "quite short," "very short," "quite long," or "very long":

Not only does this limit the level of control people have, but it takes up quite a bit of space. Twelve lines of code just to define the delaying time is a bit much, don't you think? A better way to construct this option would be to let plugin users specify the amount of time (in milliseconds) as a number, so that no processing of the option needs to take place.

The key here is not to diminish the level of control through your abstraction. Your abstraction, whatever it is, can be as simplistic as you want, but make sure that people who use your plugin will still have that much-sought-after low-level control! (By low-level I mean non-abstracted)

Give full control of elements

If your plugin creates elements to be used within the DOM, then it's a good idea to offer plugin users some way to access those elements. Sometimes this means giving certain elements IDs or classes. But note that your plugin shouldn't rely on these hooks internally:

A bad implementation:

A good implementation:

Notice that we've created a reference to the injected wrapper and we're also calling the 'attr' method to add any specified attributes to the element. So, in our settings it might be handled like this:

The $.extend() method will now recurse through all nested objects to give us a merged version of both the defaults and the passed options, giving the passed options precedence.

The plugin user now has the power to specify any attribute of that wrapper element — so if they require that there be a hook for any CSS styles then they can quite easily add a class or change the name of the ID without having to go digging around in plugin source.

The same model can be used to let the user define CSS styles:

Your plugin may have an associated StyleSheet where developers can add CSS styles. Even in this situation it's a good idea to offer some convenient way of setting styles in JavaScript, without having to use a selector to get at the elements.

Provide callback capabilities

What is a callback? - A callback is essentially a function to be called later, normally triggered by an event. It's passed as an argument, usually to the initiating call of a component. (in this case, a jQuery plugin).

If your plugin is driven by events then it might be a good idea to provide a callback capability for each event. Plus, you can create your own custom events and then provide callbacks for those. In this gallery plugin it might make sense to add an 'onImageShow' callback.

Instead of initiating the callback via traditional means (adding parenthesis) we're calling it in the context of 'this' which will be a reference to the image node. This means that you have access to the actual image node through the 'this' keyword within the callback:

Similarily you could add an "onImageHide" callback and numerous other ones...

The point with callbacks is to give plugin users an easy way to add additional functionality without digging around in the source.

Remember, it's a compromise

Your plugin is not going to be able to work in every situation. And equally, it's not going to be very useful if you offer no or very few methods of control. So, remember, it's always going to be a compromise. Three things you must always take into account are:

• Flexibility: How many situations will your plugin be able to deal with?
• Size: Does the size of your plugin correspond to its level of functionality? I.e. Would you use a very basic tooltip plugin if it was 20k in size? - Probably not!
• Performance: Does your plugin heavily process the options in any way? Does this effect speed? Is the overhead caused worth it for the end user?

1. Update Attribute Selectors

By far the most common stumbling block to the 1.3 upgrade has been the attribute selector. The XPath syntax for this selector — [@attribute] — has been deprecated since version 1.1.4 in August, 2007. Still, many scripts, including some prominent plugins, continued to use the old syntax, which wasn't a problem until jQuery 1.3, at which point it was no longer supported. The correct syntax (since 1.1.4) follows the CSS standard: [attribute].

The fix is quite simple. Simply search your scripts for [@. Go through the matches one by one, and if the string is being used as an attribute selector (and not, for example, in a regular expression), replace it with [.

Removed XPath Syntax

This will break your code in jQuery 1.3+:

Current CSS Syntax

Use this instead:

2. Check Custom Selectors

If you are using custom selectors, either in your own script or within a plugin, you might run across an error if the second argument's object value is a string:

This is another easy fix. Simply change that value to an anonymous function and add what was in the string to the return statement:

So, basically, you just change "jQuery(a).siblings(m[3]).length>0" to function(a,i,m) {return jQuery(a).siblings(m[3]).length>0;}.

When someone on the jQuery Google Group was having trouble with George Adamson's excellent More Selectors plugin, all I had to do to make it compatible with jQuery 1.3 was update the attribute selectors and change custom selectors (my updated script is available here temporarily until George has time to update the original).

3. Note Visible and Hidden Elements

This change didn't occur until jQuery 1.3.2, but if you are upgrading to the latest and greatest jQuery version, you'll want to be sure your scripts aren't relying on a quirk in how jQuery was determining the visibility of elements. Prior to 1.3.2, if you had an element with display:block inside a containing element with display: none, the inner element would still be reported as visible.

Before version 1.3.2, $('#inner'1).is(':visible') would return true and $('#inner1:hidden') would match 0 elements. In order to find out if an element were truly hidden, meaning you couldn't see it, you'd have to check all of its ancestors to see if they were hidden as well. Remy Sharp put together a little custom selector to check if elements were *really* visible.

With 1.3.2, $('#inner').is(':visible) returns false and $('#inner:hidden') match 1 element.

Another Visible Wrinkle

There is one more change in how visibility is detected in 1.3.2: elements with visibility: hidden are now considered visible, whereas before they were considered hidden.

Given the above div structure, jQuery 1.3.2 considers #inner2 visible while prior versions considered it hidden.

Here is a quick demo, with two iFrames showing the differences in determining visibility:

I'm not sure how I feel about the new behavior with visibility:hidden, but I think the change was important for performance reasons.

A Few Others

There are a few other issues that may affect a small minority of users, but the three above represent the lion's share of reported problems that I've seen on the Google Groups. For more information about changes, see the jQuery 1.3 Release Notes

However, I find that after moving to jQuery, I do less array manipulation than I had done with Prototype. Perhaps jQuery has altered my development pattern so I no longer need array manipulation, or perhaps I have shifted most of my data manipulation to the server. Whatever the case, I have only on occasion missed the Prototype array methods.

While there is some overlap in the ways that jQuery and Prototype handle array manipulation, jQuery does a few things Prototype doesn't do, and Prototype does a number of things that jQuery doesn't. I began writing an article about these differences, but soon got side-tracked writing a jQuery plugin to mimic the array methods Prototype provides.

You can find the plugin at http://code.google.com/p/jquery-protify-js/

With this plugin, you can give a particular array all of the methods that Prototype adds to their Array and Enumerable objects. You can use the methods two different ways. The first does not extend the original array:

This will return an array extended with the Prototype library's methods, but leave the original array untouched.

The second extends the original array by passing in true as the second parameter:

In either case, the JavaScript Array prototype is untouched. When you create new arrays, it will not have the new methods. This way of writing code adds the new methods when they are needed while leaving the underlying JavaScript prototypes untouched. The return value of the methods is an array with the extended methods so that they can be chained.

The above code first returns the arr array values in a new array with the Prototype methods, removes any null/undefined values (using compact), finds all the values in the array greater than or equal to 3 and returns an extended array of them (using findAll), and finally returns the first value of that array (using first). It does all of this without touching the prototype for all arrays.

Here are some useful Prototype array methods included in the plugin:

all()

returns true if every member of the array == true and returns false if even one member != true.

any()

returns true if even one member of the array == true and returns false if every member != true.

map()

similiar to jQuery's $.map. It executes the function passed in on every of member of the array and returns an array of the results.

eachSlice(number)

slices the array into an array of arrays of the size passed in. There is an optional second parameter which is a function that acts on each array partition before placing it in the slice.

include(value)

returns true if the value is in the array (using == equality).

max()/min()

returns the maximum/minimum value of the array. Optional parameter is a function that can be used to define the comparison and what gets returned.

partition()

returns an array with two arrays in it. The first array contains the values that == true in the initial array, and the second all of the values != true. There is an optional parameter that is a function used to do the evaluation.

pluck()

And finally, my favorite. The pluck() method iterates through every member of the array and returns an array of the value of the attribute name passed in.

For a full listing and description of all the methods, see the Prototype documentation on arrays and enumerables.

Arrays: http://prototypejs.org/api/array

Enumerables: http://prototypejs.org/api/enumerable

The toJSON method has not yet been implemented because it depends on object methods that Prototype provides. Can you guess what my next project is?

• jQuery UI 1.6 is shaping up to be a rock-solid re-factoring of the entire library. With RC4 released just two days ago, the UI team have further cleaned up the API while providing a set of tools that are even more extensible and configurable than they were before.
• Better project management and greater transparency. Over the last year or so, Paul Bakaus has done much more than lead the development of jQuery UI. He has shaped and nurtured a team of top-notch JavaScript developers and has opened up a lot of the decision-making process to outside scrutiny. This bodes well for the direction of the project.
• Improved jQuery UI ThemeRoller. ThemeRoller, developed and designed by the folks at Filament Group, was already an amazingly useful and elegant complement to jQuery UI. But now it's even better, with a much-improved CSS framework and lighter CSS footprint, a slick default theme, a cool icon sprite set, and more configuration options. Also, it'll soon be easier than ever to create your own UI widgets that take advantage of the ThemeRoller — with upcoming tools, documentation, and tutorials for making your site "ThemeRoller-ready."
• Improved documentation and demos. The documentation wiki has undergone some significant updates in recent months, and the demos went through a complete overhaul in coordination with the 1.6rc4 release.
• More widespread adoption. As the API changes settle down and the core UI developers have more time to spend on providing more widgets and components, such as a spinner, menu, and colorpicker, more sites are sure to join the likes of WordPress in adopting jQuery UI.
• A new blog. While most of the details are still under wraps, a brand new weblog dedicated to learning jQuery UI, similar in quality and scope to Learning jQuery, will be online soon.

Update:

A very exciting CSS theming application was also released with jQuery UI 1.5, called ThemeRoller. ThemeRoller is an amazing way to customize the style and colors across all of the jQuery UI components. It comes with a few preset styles, as well as allowing you to create your own. Once you are done, it packages your theme into a zip file that contains all of the images and CSS you need.

Brief Overview of the jQuery UI Project

The jQuery UI project was originally created to bring you a set of "official" jQuery plugins. Mature components from the plugins repository were pulled together to form the first release of jQuery UI. But since each of these plugins had its own style, having been written by different authors, the first release of the library felt a bit cumbersome when packaged together. With that in mind, the focus of UI 1.5 was on achieving a coherent, standardized API to eliminate much of the differences between the components. Through much time and effort, many bugs and feature requests were addressed along the way as well.

Inside Look at jQuery UI Version 1.5

Before starting, I want to make sure you know where the jQuery UI Documentation is located. You may also want to head to the download page to grab the library for yourself. Note that the development bundle is the easiest to get started with.

First, let's start by including the necessary files for jQuery UI: jQuery latest js file, the Flora theme complete stylesheet, and the core UI file. Each of the components is built on top of these files. Here is how to include them:

You may want to download these files and put them on your own server, but this is just fine for our demonstration.

At this point you may include the jquery.ui.all.js script for testing, or include each of the components individually. Here are the components that we are using for this demo:

Activating Components

Each component has a constructor method, which is the component name. For instance, we can make a div draggable by using the draggable() method:

The component defaults can be overridden by passing in options to the main function. For instance, if we want to make the div drag only horizontally, we can set the axis option to "x" with the following code:

Likewise, the Accordion can be accessed the same way. Here we set a custom option to specify the accordion to slide on the mouseover event:

• Test 1
  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
• Test 2
  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam
  
• Test 3
  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Some of the components, such as draggable and resizable, can even be combined:

This first makes the div draggable, then adds the resize handles to the div.

Now you should have what you need to start with each of the components! Head to the functional demos page to see in-depth examples of each of the components.

Looking at the Future of jQuery UI

With Paul Bakaus hired as (paid) full-time lead of jQuery UI, the project has been energized, charging forward by leaps and bounds. With an ever-growing set of UI components, jQuery UI's future is shaping up to be one of great promise.

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

What is Low Pro?

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

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

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

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

Example 1: Creating a re-usable registration form

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

Our first step is to create our basic form:

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

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

Validation

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

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

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

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

Enhancements

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

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

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

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

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

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

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

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

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

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

All of these methods have optional speed, easing, and callback arguments — although a couple are special cases. The .show() and .hide() methods, when used without a speed, will immediately show and hide the matched set of elements with no animation. When the speed argument is included, the matched elements are shown and hidden gradually by animating their height, width, and opacity simultaneously. The .toggle() method shares its name with a method that takes two arguments that alternate being triggered. All of the other effect methods have a default speed of 400ms.

The Flexible .animate()

jQuery internally uses another method, .animate(), to define these shorthand effect methods, and it makes .animate() available to us to do the same. So, let's create our own method that we can use the same way we would use, for example, .slideToggle().

Custom Animation Methods

Someone on the jQuery discussion list recently asked if there was a .fadeToggle() effect in jQuery. In my reply, I admitted that there wasn't one, but suggested that it wouldn't be too hard to create using .animate(). We just attach .fadeToggle to jQuery.fn and pass in the speed, easing, and callback arguments. Then, we return this.animate() with the effect we want, along with those same arguments:

Try it out:

To create a method that toggles a fade and a slide at the same time, all we need to do is repeat the process, adding a "height" parameter:

Give this one a try:

Blind Toggle

Let's try one more — a "blind" effect. Instead of changing the height of the element, as we do with a "slide" animation, we're going to move the entire element up and down.

The plugin itself will still be fairly rudimentary, but we'll need to set up some CSS to get it to work correctly. Here is the CSS:

Notice that we have two "boxes" styled here. The first one will be in the markup itself, but the second one, since it's only being used to help with the effect, will be created by our script. The important properties here are #box-outer's overflow: hidden and height: 120px. The hidden overflow will allow #box to seemingly disappear as it moves up, while the height (which is #box's height plus its top and bottom padding) will keep the rest of the page from shifting along with the box.

While relatively simple, there are a couple things here that might be confusing to jQuery/JavaScript beginners. The first line inside the function declares a variable for the height of this, plus the top and bottom padding ("this" here refers to whatever is matched by the selector in the script that uses the plugin). The parseInt() JavaScript function function looks at a string from left to right until it encounters a non-numeric character. The string of digits up to that character is converted into an integer, stripping off the trailing non-numeric character. So, "10px" becomes 10.

The line that follows animates the marginTop property. It uses a ternary (conditional) operator to test if marginTop is less than zero. If it is, the element's marginTop property animates to 0; if not, it animates to negative the value stored in the h variable.

Finally, we're ready to put this plugin to use:

Line 2 "caches" our selector, since we're using it more than once. Then we wrap a div around the "#box" div and bind a click handler to a button. Let's see how this one looks:

So, now we have three simple effects methods that we apply to our sites for a little extra flair.

jQuery UI

For really cool effects, check out the demos of jQuery UI effects.

Question: Filter Function

Answer

Question: Filter by Option Value

Answer

Question: Puzzle of "this"

Answer

Question: Swap an Image on Click

Answer

Question: How to Center a DIV Vertically in the Viewport

Answer

Find your plugin's purpose

Open-source the design

The Baskin-Robbins approach

Centralize