JQuery_ Novice to Ninja - Earle Castledine [134]
Inside this protective shell we can use the $ alias with impunity. That’s all there is in the way of preliminaries—so it’s time to start to writing a plugin. First we need to give it a name, highlightOnce, and attach it to the jQuery plugin hook, $.fn:
chapter_09/01_plugins/jquery.highlightonce.js (excerpt)
(function($) {
// Shell for your plugin code
$.fn.highlightOnce = function() {
// Plugin code
}
})(jQuery);
Internally $.fn is a shortcut to the jQuery.prototype JavaScript property—and it’s the perfect place to put our plugins. This is where jQuery puts its actions, so now that we’ve added our custom action we can call it as if it was built into jQuery.
At this point our code looks like a jQuery plugin, but it won’t act like one—there’s still one more task left to do. If we were to perform some operations inside our plugin code now, we would actually be working on the entire selection at once; for example, if we ran $('p').highlightOnce(), we’d be operating on every paragraph element as a single selection. What we need to do is work on each element, one at a time, and return the element so the jQuery chain can continue. Here’s a fairly standard construct for plugins:
chapter_09/01_plugins/jquery.highlightonce.js (excerpt)
// Plugin code
return this.each(function() {
// Do something to each item
});
So you now have a nice skeleton for creating simple plugins. Save this outline so you can quickly create new plugins on a whim!
Adding the Plugin’s Functionality
Our highlightOnce plugin is ready to roll, so let’s give it a job to do. All the structure we’ve added so far is just the scaffolding—now it’s time to create a building! The type of code we can run in the guts of our plugin is exactly the same as the code we’re used to writing; we can access the current object with the $(this) construct and execute any jQuery or JavaScript code we need to.
The first function our plugin needs to accomplish is to highlight every selected element, so we’ll just set the background to a bright yellow color. Next, we need to handle when the user mouses over the element so we can remove the highlight. We only want this to happen once, as soon as the element is faded back to the original color (don’t forget, we need the jQuery UI Effects component to do that):
chapter_09/01_plugins/jquery.highlightonce.js (excerpt)
// Do something to each item
$(this)
.data('original-color', $(this).css('background-color'))
.css('background-color', '#fff47f')
.one('mouseenter', function() {
$(this).animate({
'background-color': $(this).data('original-color')
}, 'fast');
});
There just happens to be a jQuery action that fits our needs exactly: the one action. Functionally, the one action is identical to the bind action we saw earlier, in that it lets us attach an event handler to our element. The distinction with one is that the event will only ever run once, after which the event will automatically unbind itself.
For our code, we save the current background color in the element’s data store, then bind the mouseover event to the DOM elements that are selected. When the user mouses over the element, our code runs and the background color is animated back to the original. And with that, our plugin is ready to be used:
chapter_09/01_plugins/script.js (excerpt)
$('p')
.hide()
.highlightOnce()
.slideDown();
It’s quite exciting: our functionality is captured in a chainable, reusable plugin that we’ve nestled in between the hide and slideDown actions. Seeing how 11 lines of code was all that was required (and six of those are stock-standard plugin scaffolding!), you can see it’s worth turning any functionality you intend on reusing into a plugin!
Adding Options
jQuery plugins are an excellent way to produce reusable code, but to be truly useful, our plugins need to be applicable outside the context for which we created them: they need to be customizable. We can add user-specified options to our plugins, which can then be used to modify the plugin’s behavior when it’s put to use.
We’re familiar with