You are free to browse all of the content on this site, however if you want to post comments or replies you will need to register for a free account. Becoming a registered member also disables some of the more annoying ads whilst you are logged in.

jQuery: Creating a Plugin

In the last article, we learned about the difference between live() and bind() - and when to use them. In this article we're going to put bind() to use and create our first jQuery plug-in.

If you use jQuery, you've heard of its plug-ins - easily reusable bits of code that you can call on selectors like any other jQuery method. What you may not realize is how easy it is to write your own plug-ins, making code reuse in your projects easier then ever.

01: The Set-Up

In order to create a plug-in, you need an environment that supports one. Create a new folder and inside that folder create two documents:

colorize-test.html

colorize.jquery.js

The first file is the file we'll use to test our plug-in, and the second file is the plug-in itself. In the test file, enter the following HTML:

Fill the paragraph tags with placeholder text; you can copy a sentence from somewhere and repeat it five times. Notice we've included the jQuery library in the head of our document from the freely provided jQuery CDN. We've also linked our jQuery plug-in to the document, and put a document.ready block below that for when we're ready to use the plug-in.

The purpose of our plug-in is going to be to change the color of text when clicked. Not very exciting, but the idea is to learn how to create a plug-in, not to create anything special.

02: Writing the plug-in: Deciding the Interface

When writing a plug-in, it's often best to first decide on how it will be used. In the majority of cases, this means determining the options since almost all plug-ins are used by calling them in a chainable fashion on a selector. Here's how using our plug-in will look:

The first thing your plug-in code has to do is handle the passed in options. To do this, you have to set defaults and merge any values the user has set when calling the plug-in. Sounds potentially complex, but it's not.

The preceding code would be dropped in at the start of the colorize function. It sets an array of defaults, then takes it and the options the user has passed in, combining them into the opts array using jQuery $.extend. Any values in the user-given array will <b>over write</b> any values in the defaults array.

05: Working on Each Element

It's important to remember that jQuery plug-ins are called on a selector which may return between zero and a LOT of items that match the selector. Within the scope of your colorize function, the special variable 'this' will refer to this jQuery collection. So after we've set up our default, we are going to loop over this collection with the 'each' method.

Code:

this.each(function() {
// This code is applied to every element defined by the selector
// the special variable 'this' is redefined here
});

Within the 'each' loop, the special variable 'this' is redefined automatically as the current DOM element of the jQuery collection. In order to access it as a single jQuery object, we'll define the variable self as the first line of the each loop:

Code:

var self = $(this);

You've now essentially written a plug-in. The code from here on is simply specific to the plug-in we're writing for this example. You can use the code so far as a basis of your own jQuery plug-ins. In the final version (you'll see it in a bit) you can just remove the code inside the 'this.each' and replace it with your own.

06: Store the Original Color

In our plug-in, we have to know what color the item was before we started messing with it. To keep track of this, we're going to create an array with the original color as the 0 index value, combined with the colors set in the options. We're also going to set a value called 'color-index' which indicates which color of the array should be displayed at any time.

You may be unfamiliar with the $(obj).data construct. It's a jQuery method that allows you to associate arbitrary data with an DOM element. In this case, we're associating both an array of colors, and a current color index.

07: Add a Click Handler

Since we want the DOM elements to color when clicked, we need to add a click handler. Here's how we do that:

This code will execute every time one of the DOM elements passed to our plug-in is clicked. It checks the current value of color-index, and if it's less then the last index value, increments it. If it's the last index value (arrays are 0 based, so index minus one is the last value) then it resets the index to zero. Finally it changes to color of the DOM element to the color indicated by the index.

In our next jQuery article, we're going to learn how to create a plug-in to enable dependant selects in HTML forms. When you choose an element in the first select, the choices in the second select are populated based on that choice.