JQuery_ Novice to Ninja - Earle Castledine [135]
There are two types of plugin options: simple values and object literals. Let’s start with the simpler one to see how this works. For our highlightOnce plugin, it seems quite limiting to have the color hard-coded. We’d like to give developers the choice to highlight their elements in any color they’d like. Let’s make that an option:
chapter_09/02_plugin_options/jquery.highlightonce.js (excerpt)
$.fn.highlightOnce = function(color) {
…
$(this).css('background-color', color || '#fff47f')
…
};
The plugin can be called with a color, but can also be called without parameters—in which case a default value will be used (thanks to the JavaScript || operator). Let’s highlight our paragraphs in green:
chapter_09/02_plugin_options/script.js (excerpt)
$('p')
.hide()
.highlightOnce('green')
.slideDown();
If you have one or two simple options that are always required, this approach is fine. But when your plugins start to become more complicated, you’ll end up with numerous settings, and your users will want to override some and keep the default values for others. This is where we turn to the more complex object literal notation.
It’s not scary—you already know how to define this type of settings object. We’ve used them for animate, css, and most jQuery UI components. The key/value object has the benefit of only one parameter needing to be defined, in which users will be able to specify multiple settings. Our first step is to set up default values for each option:
chapter_09/03_plugin_options_with_defaults/jquery.highlightonce.js (excerpt)
$.fn.highlightOnce.defaults = {
color : '#fff47f',
duration : 'fast'
};
We now have the defaults as an object, so we need to make use of the jQuery $.extend function. This handy function has several uses, but for our purposes, we’ll use it to extend an object by adding all of the properties from another object. This way, we can extend the options the user passes in with our default settings: the plugin will have values specified for every option already, and if the user specifies one of them, the default will be overridden. Perfect! Let’s look at the code:
chapter_09/03_plugin_options_with_defaults/jquery.highlightonce.js (excerpt)
$.fn.highlightOnce = function(options) {
options = $.extend($.fn.highlightOnce.defaults, options);
return this.each( … );
};
Our options variable contains the correct settings inside it—whether they’ve been defined by the user, or by the default object. Now we can use the settings in our code:
chapter_09/03_plugin_options_with_defaults/jquery.highlightonce.js (excerpt)
$(this)
.data('original-color', $(this).css('background-color'))
.css('background-color', options.color)
.one('mouseenter', function() {
$(this).animate({
'background-color': $(this).data('original-color')
}, options.duration);
});
As the plugin user, we can specify the color or duration of the highlight—or accept the defaults. In the following example we’ll accept the default color, but override the duration to be 2,000 milliseconds rather than “fast”:
chapter_09/03_plugin_options_with_defaults/script.js (excerpt)
$('p')
.hide()
.highlightOnce({color: '#C0FFEE', duration: 2000})
.slideDown();
Adding Callbacks
You have seen how callback functions and events can be very useful. Many of the effects and controls throughout the book have relied on them—and many of the plugins we’ve used have given us access to callbacks to customize their functionality. Callbacks are a mechanism for giving your plugin’s users a place to run their own code, based on events occurring inside your plugin. Generally you’ll have a fairly good idea of what events you’d like to expose to your users. For our highlightOnce plugin, for example, we might want to run additional code when the effect