The plugin code

The basic principle of writing a jQuery plug-in is very simple: You write a function and attach that function to the jQuery object. We are going to add a new method to the jQuery object.

The most basic pattern for writing such a plug-in is similar to this:

jQuery.fn.myNewPlug-in = function () { // Do something.

The new plug-in could then be called like this:

What are we doing here? The jQuery.fn object is where jQuery functions are attached to the jQuery prototype object. In other words, all of the functions that are attached to jQuery.fn will be available to jQuery objects, and can be called (as in the previous example) by $().someFunction().

As a de facto rule, a plug-in should use only one namespace inside of the jQuery.fn namespace. When adding multiple functions to jQuery, these functions should be grouped into another namespace. Instead of jQuery.fn.myPlug-inFirst() and jQuery.fn.myPlug-inSecond(), it should be jQuery.fn.myPlug-in.first() and jQuery.fn.myPlug-in.second() .

We now have a basic idea about how to write a plug-in. Following this prescribed pattern for plug-in development, we are going to create our own simple plug-in.

Plug-ins for jQuery should be stored in files named jquery.<plug-in>.js, where <plug-in> is replaced with the name of the plug-in (all in lowercase). Our plug-in is going to wrap matched elements in a <div></div> tag. For example, we might create a jQuery object that finds all anchors:

Our little tool could then be applied in order to enclose each of those anchor elements inside of a div:

This would transform something like <a href = "http://example.com"> into <div><a href="http://example.com"></div>. Though our plug-in may never win any awards for innovativeness, it is a good starting point for investigating jQuery plug-ins.

We are going to call this plug-in divWrap, so it should be stored in a file called jquery.divwrap.js.

This library will work just like any JavaScript library in Drupal. You can add it to a theme using the theme's .info file, or you can include it in a module with the drupal_add_js() function. While developing, you might find it handy to simply start with a static HTML file and include only jQuery and your plug-in.

Here's the code that we will put in jquery.divwrap.js:

* Wrap the selected element or elements in <div></div>

* @param attributes

* An object containing name/value pairs for attributes. */

jQuery.fn.divWrap = function () { var attrs = (arguments.length > 0) ? arguments[0] : {};

this.each(function (index, item) {

var div = $(item).wrap('<div></div>').parent();

div.attr(attrs);

return this;

The first thing to note about this plug-in is the outermost wrapper, which looks like this:

What is this? In JavaScript, you can both define and call a function in one step, and this is how it is done. The previous code performs a task similar to what this code does:

myFunc(jQuery);

There are two important reasons why we begin a jQuery plug-in with code such as this:

1. We can conveniently work with jQuery using the $() function alias.

2. We also create a closure that protects our plug-in's context.

Neither of these may be obvious, so let me explain.

Although we have used the $() function many times in this book. However, the name $ is sometimes overridden, or turned off, by other JavaScript libraries. In short, there is no guarantee that $ refers to jQuery. The convention that we saw overcomes this uncertainty by wrapping the entire plug-in in a function that takes an argument named $. The function is then called with the globally scoped jQuery object. In effect, it re-maps $ to jQuery so that we can confidently use the $() function in our code.

Second, this convention creates a closure around our plug-in. Closures are often treated as an advanced aspect of JavaScript development. In fact, they are used frequently in a variety of contexts. (We have used them a few times already, but without the fancy name and in a subtler fashion.) We will take a brief look at this topic, and you will find that they are not as mysterious as they may seem at first.

Was this article helpful?

0 0

Post a comment