How to Write a jQuery Plugin – Part 2: Options and Collections

In part one of my series on creating a jQuery plugin, I showed an example on how to structure a new custom plugin.  In this post, I’ll show you how to provide options for developers using your plugin and how to allow your plugin to handle multiple elements in the DOM.

User Options

You will remember in part one that we added an options parameter to our plugin’s main function.  It looked like this:

$.fn.highlight = function (options) {

This parameter is an object that will contain values for all of the options that the user will specify.  There is nothing special about this object.  It can hold any kind of data that you need to use as a setting for your plugin.  The problem with using this object directly is that we don’t want to require the user to set any options at all, if we don’t need them to.  However, we also don’t want to have to check to see if each value exists to specify a default.

jQuery’s built in extend function simplifies this down to a small piece of code.  See the example below:

var settings = $.extend({
     cssClass: 'highlight-yellow'
}, options);

In this snippet we are creating a variable in our plugin to hold our user settings.  To do this, we pass two things into jQuery’s extend function.  The first is an object that contains all of the default values that we wish for our plugin to use if the user does not specify their own value.  The second parameter is, you guessed it, the options variable containing the user’s specified values.  jQuery extend takes those two objects and merges them together, replacing our default values with the values in the options variable, if they exist.

In this case, I’ve added a very simple setting that will control the class that gets added to the content to highlight it in a specific color.  I will demonstrate how to use that in the next section.

Handling Loops and Collections

You may not realize it, but any time you are using a jQuery selector you are being returned a collection of elements.  This is the case whether or not there is or an only be one matching element on the page or not.  Selecting an element by class?  You get a collection of the elements that match that class.  Selecting an element by ID?  You still get a collection, but it contains only a single element.

This is important to understand because you will need to code your plugin to handle a collection of elements, rather than just one.  You can do this easily using jQuery’s each function.

return this.each(function () {
     // Adds the highlighter class to the element
     // Note the use of our settings object.
     $(this).addClass(settings.cssClass)
});

Inside of the each function is where we write the code for the core functionality of our plugin.  In this case, we want to add a class to every element that has been selected by the user. This will be how we add the highlight to each block of content.

Notice the use of the settings variable.  That object will contain either the default value or the user specified option value.  No extra work is required.

At this point, if we combine all of our code into a single file, we have a very simplified, but working plugin.  In the final part of the series, I will show you how to create your plugin file and complete all of the necessary steps to use it in an HTML page.

Until then, thanks for reading!

Advertisements

One thought on “How to Write a jQuery Plugin – Part 2: Options and Collections

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s