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?

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?

Most jQuery methods return the jQuery object itself, which allows methods to be chained.

The interesting thing about the jQuery object is that while its datatype is an object, it has array-like characteristics:

• its property names (the ones that refer to DOM elements, at least) are numeric
• it has a length property

Have you ever noticed, for example, a snippet of jQuery code that directly accesses a DOM element by using the bracket operator with the jQuery function?

Now, the jQuery function returns an object, but it looks like we just treated it as an array. It can also be written like this:

If this is confusing, let's see if we can clear it up with some code. Go to the jQuery.com homepage, open up Firebug using Firefox, and run the following line of code in the console.

You should be looking at this in the console:

Looky there! The jQuery function is returning an object with a bunch of properties. If we tack on the bracket operator to the jQuery function, which returns an object, we can access the properties of that object because inside the object are properties with a numeric property name. Fascinating isn't it?

I know what you're thinking: this tutorial is about arrays, not objects. Right, so let's get to the array part. Since we now know that the jQuery function returns an object that only masquerades as a JavaScript array the question at hand is how do I get a true JavaScript array from a jQuery wrapper object. This is actually very simple. Most of you might not have been aware (if not, I showed you earlier) that $('div')[0] and $('div').get(0) return a reference to the first element in the jQuery wrapper object. But, the get() method actually has another purpose. It can quickly turn the DOM elements found in the jQuery wrapper into an array of DOM elements.

Let's return to jQuery.com and open up Firebug again. Inside the console run the following line of code.

You should now be looking at this in the firebug console:

"[{}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}]"

Essentially the .get() method placed all of the DOM elements inside the jQuery wrapper into an array and returned that array. So now you can use default array methods on your array of elements. For example:

Additionally, since we now have an array we can write a statement like this:

There is something worth noting here that might not be obvious to those starting out with jQuery or JavaScript. Since we are now returning an array, the chain is broken. You can't chain any jQuery methods after using the .get() method.

But, heck, you have an array. Now you can use the utility functions that jQuery provides ($.each(), $.grep(), $.map(), $.inArray(), $.unique()), as well as core JavaScript methods and properties, to work on the array. I'm not going to demonstrate all of the jQuery utility functions that can be used on an array, but I do want to examine one of them here in this tutorial.

The $.each() utility function, not to be confused with the $('selector').each() method used to operate on a set of DOM elements in a jQuery wrapper, can be used to seamlessly iterate over an array or object. For example, let's say that you would like to store (or cache) a set of <li> elements in an array, because maybe you are going to remove them from the DOM temporarily but eventually will be placing them back on the page. To do this you could use the $.each() utility function to loop over an array and append each <li> element back to the page. In the code example below this is done on page load by converting and storing the jQuery wrapper of <li> elements to an array, and then looping over this array in order to place them back on the page.

Notice that I am forgoing the use of the .ready() event by simply placing my jQuery code before the closing body element.

So, hopefully it's obvious how extremely handy it can be at times to make an array out of a jQuery wrapper. In fact, once you are dealing with an array, you can use a handy plugin called Rich Array. This plugin provides the following additional utility functions for arrays. And yes, there is a bit of duplication here with some of the core utility functions.

$.richArray.in() //Checks whether an array contains some value
$.richArray.unique() //Produces the duplicate-free version of the array
$.richArray.diff() //Finds the difference between two arrays.
$.richArray.intersect() //Finds the intersection of two arrays
$.richArray.filter() //Applies filter to the array, using callback function
$.richArray.map() //Applies callback function for each element in the input array, and returns array of values that this function returned
$.richArray.sum() //Computes the sum of all array elements
$.richArray.product() //Calculates the production of all elements of the array
$.richArray.reduce() //Reduces the array. One-element arrays are turned into their unique element
$.richArray.compact() //Creates new version of array without null/undefined values
$.richArray.without() //Creates a new version of the array that doesn't contain the specified value

Cloning Nodes

This time, we'll take a look at re-binding event handlers. But before we do, I should mention that, as of jQuery version 1.2, event handlers can be cloned along with elements. Consider this unordered list:

We can make a copy of <li class="special"> and insert it after the original, while at the same time retaining any event handlers that were attached within the original. The plain .clone() method doesn't work that way; instead, it just copies the element:

• plain
• special I am special
• plain

As you can see, the original button is able to keep creating new list items, but the buttons inside the "dynamically generated" list items can't create new ones.

To get the event handlers copied over as well, all we have to do is pass in true to the method's single argument:

Note: I've added .append(' I\'m a clone!') here only as visual reinforcement of what is going on.

Try it now:

• plain
• special I am special
• plain

Using .clone(true) is great when we want to make a copy of existing elements and their event handlers, but there are plenty of other situations that don't involve cloning in which we might want event handlers to persist.

Re-binding Basics

The basic concept behind re-binding is fairly straightforward: We create a function that binds the handlers and then call it whenever new elements are introduced. For example, with our unordered list above, we first create a function called addItem that registers the click handler, which in turn will add a new item:

Next, we call that function when the DOM initially loads:

Finally, we can call the function inside the click handler—and inside itself. That way, it will bind the event handlers to the new list item as well.

We'll add one more click handler to the button, but this one will not be re-bound, so that we can see the difference.

Here is what the code for buttons in #list5 looks like, all together:

Try this one out:

• plain
• special I am special
• plain

We can see that "pressed" is appended to the first list item each time it is clicked, but it is not appended to any of the list items created by our clicks. On the other hand, the created buttons are able to generate further list items because that function is being rebound.

However, what we've just done produces unwelcome results if we click on a button more than once. The click handler is bound again with each click of a button, producing a multiplier effect. The first click of a button creates one extra list item; the second creates two; the third, four; and so on.

Unbind, then Bind

To avoid the multiple binding, we can unbind first and then re-bind. So in line 2, instead of this ...

$('#list5 li.special button').click(function() {

... we'll have this ...

$('#list6 li.special button').unbind('click').bind('click', function() {

Note the use of .bind() here. This is the universal event binder that jQuery uses. All the others, such as .click(), .blur(), .resize(), and so on, are shorthand methods for their .bind('event') equivalent.

The complete new code, again with the additional non-rebinding click handler for contrast, looks like this:

See how this one works:

• plain
• special I am special
• plain

Unfortunately, our attempt to unbind the addItemUnbind() function went too far, unbinding the "non-rebinding" click handler as well, before it even had a chance to run once (it's evident because there is no "pressed" text after the "I am special" button here). Clearly, we're going to have to be more careful about what we're unbinding.

Event Namespacing

One way to avoid the over-reaching event unbinding is to apply a "namespace" to the click event for both binding and unbinding. So, instead of .bind('click') and .unbind('click), we'll have, for example, .bind('click.addit') and .unbind('click.addit). Here is one last code sample, which looks identical to the previous, except that it now has the namespaced event (and the list id is list7):

We should now — finally! — have a set of behaviors attached to these buttons that act the way we intend them to:

• plain
• special I am special
• plain

For more information about event namespacing, read Brandon Aaron's article, Namespace Your Events.

Bonus: Unbind by Function Reference

If you've made it this far, then you must have extraordinary patience, in which case I'll reward it with one final method of rebinding. Rather than namespace the events, we can reference the function in the second argument of the .bind() and .unbind() methods. We have to shuffle things around a bit to avoid "too much recursion," but it'll do just fine like so:

Note here that there are no parentheses after "addItemFinal" when it appears inside the bind/unbind, because we are referencing the function, not calling it. So let's test it out one last time:

• plain
• special I am special
• plain

Plugin Options

There are three great plugins that can do a lot of this work for us:

• Live Query by Brandon Aaron
• Listen by Ariel Flesler
• Intercept by Ariel Flesler

If this entry left you bewildered, or if you want a quick, well tested solution, you should definitely try one of them. Each works a little differently, but they're all super plugins.

Update: Event Namespacing with Add and Remove

In response to the comment by Nick Johns below, I'm providing an example that allows for both adding a row and removing a row. The code is based on the "Event Namespacing" example above:

I added an "addone" class to the initial button, but otherwise the list is the same as the others. You can try it out here:

• plain
• special I am special
• plain

There are a few requirements that I feel this pattern handles nicely:

1. Claim only a single name in the jQuery namespace
2. Accept an options argument to control plugin behavior
3. Provide public access to default plugin settings
4. Provide public access to secondary functions (as applicable)
5. Keep private functions private
6. Support the Metadata Plugin

I'll cover these requirements one by one, and as we work through them we'll build a simple plugin which highlights text.

Claim only a single name in the jQuery namespace

This implies a single-plugin script. If your script contains multiple plugins, or complementary plugins (like $.fn.doSomething() and $.fn.undoSomething()) then you'll claim multiple names are required. But in general when authoring a plugin, strive to use only a single name to hold all of its implementation details.

In our example plugin we will claim the name "hilight".

And our plugin can be invoked like this:

But what if we need to break up our implementation into more than one function? There are many reasons to do so: the design may require it; it may result in a simpler or more readable implementation; and it may yield better OO semantics.

It's really quite trivial to break up the implementation into multiple functions without adding noise to the namespace. We do this by recognizing, and taking advantage of, the fact that functions are first-class objects in JavaScript. Like any other object, functions can be assigned properties. Since we have already claimed the "hilight" name in the jQuery prototype object, any other properties or functions that we need to expose can be declared as properties on our "hilight" function. More on this later.

Accept an options argument to control plugin behavior

Let's add support to our hilight plugin for specifying the foreground and background colors to use. We should allow options like these to be passed as an options object to the plugin function. For example:

Now our plugin can be invoked like this:

Provide public access to default plugin settings

An improvement we can, and should, make to the code above is to expose the default plugin settings. This is important because it makes it very easy for plugin users to override/customize the plugin with minimal code. And this is where we begin to take advantage of the function object.

Now users can include a line like this in their scripts:

And now we can call the plugin method like this and it will use a blue foreground color:

As you can see, we've allowed the user to write a single line of code to alter the default foreground color of the plugin. And users can still selectively override this new default value when they want:

Provide public access to secondary functions as applicable

This item goes hand-in-hand with the previous item and is an interesting way to extend your plugin (and to let others extend your plugin). For example, the implementation of our plugin may define a function called "format" which formats the hilight text. Our plugin may now look like this, with the default implementation of the format method defined below the hilight function.

We could have just as easily supported another property on the options object that allowed a callback function to be provided to override the default formatting. That's another excellent way to support customization of your plugin. The technique shown here takes this a step further by actually exposing the format function so that it can be redefined. With this technique it would be possible for others to ship their own custom overrides of your plugin נin other words, it means others can write plugins for your plugin.

Considering the trivial example plugin we're building in this article, you may be wondering when this would ever be useful. One real-world example is the Cycle Plugin. The Cycle Plugin is a slideshow plugin which supports a number of built-in transition effects נscroll, slide, fade, etc. But realistically, there is no way to define every single type of effect that one might wish to apply to a slide transition. And that's where this type of extensibility is useful. The Cycle Plugin exposes a "transitions" object to which users can add their own custom transition definitions. It's defined in the plugin like this:

This technique makes it possible for others to define and ship transition definitions that plug-in to the Cycle Plugin.

Keep private functions private

The technique of exposing part of your plugin to be overridden can be very powerful. But you need to think carefully about what parts of your implementation to expose. Once it's exposed, you need to keep in mind that any changes to the calling arguments or semantics may break backward compatibility. As a general rule, if you're not sure whether to expose a particular function, then you probably shouldn't.

So how then do we define more functions without cluttering the namespace and without exposing the implementation? This is a job for closures. To demonstrate, we'll add another function to our plugin called "debug". The debug function will log the number of selected elements to the Firebug console. To create a closure, we wrap the entire plugin definition in a function (as detailed in the jQuery Authoring Guidelines).

Our "debug" method cannot be accessed from outside of the closure and thus is private to our implementation.

Support the Metadata Plugin

Update: This bit was optimized per suggestion in the comments.

This changed line does a couple of things:

• it tests to see if the Metadata Plugin is installed
• if it is installed, it extends our options object with the extracted metadata.

This line is added as the last argument to jQuery.extend so it will override any other option settings. Now we can drive behavior from the markup if we choose:

<!--  markup  -->
<div class="hilight { background: 'red', foreground: 'white' }">
  Have a nice day!
</div>
<div class="hilight { foreground: 'orange' }">
  Have a nice day!
</div>
<div class="hilight { background: 'green' }">
  Have a nice day!
</div>

And now we can hilight each of these divs uniquely using a single line of script:

Putting it All Together

Below is the completed code for our example:

This design pattern has enabled me to create powerful, consistently crafted plugins. I hope it helps you to do the same.

Now, what if I needed to select all elements that have a mouse wheel handler on them?

In jQuery 1.1 the attribute selector has an undocumented feature that will search DOM Expandos and properties as well as actual HTML attributes. Since I know that my handler method is named _mwHandler, I can use the following selector to find all elements in the document that have a mouse wheel event attached to them.

Search by Events

Also, since the jQuery event system uses a DOM Expando to store events internally, you could find all elements that have an event attached to them using this selector:

If you are using jQuery Revision 1371 or higher, the DOM Expando name has changed from 'events' to '$events'.

If you combine the previous selector with the filter method, you can find all elements that have a click event like this:

Clean Up

Most importantly, if you are using DOM Expandos, you should clean up after yourself to avoid memory leaks. Some instances of using DOM Expandos will not leak, but others will. So you're better off cleaning up, just in case. For example in the mouse wheel plugin I remove the DOM Expandos on a particular element inside the unmousewheel method. Then during the window unload event I loop through all the elements that still have a mouse wheel handler and call unmousewheel on them. In order to make this process as fast as possible I store a "cache" (just an Array) of elements that I have added DOM Expandos too.

In this example, the ajaxed-in content contains the elements that trigger a $.load over themselves.

Make sure you're not calling the function in the callback by accidentally using prepare_links():

This would set the callback to whatever the return value of the function is, not to the function itself.