1. Code
  2. Web Development

jQuery Succinctly: jQuery Plugins

This post is part of a series called jQuery Succinctly.
jQuery Succinctly: jQuery and the Web Browser
jQuery Succinctly: jQuery Effects

Use the $ Alias When Constructing a Plugin

When writing a jQuery plugin, the same conflict prevention routine used with regular, old jQuery code should be implemented. With this in mind, all plugins should be contained inside a private scope where the $ alias can be used without fear of conflicts or surprising results.

The coding structure below should look familiar as it is used in almost every code example in this session.

New Plugins Attach to jQuery.fn Object to Become jQuery Methods

New plugins are attached to the jQuery.fn object, as this is a shortcut or alias for jQuery.prototype. In our coding example below, we are adding the count plugin to the jQuery.fn object. By doing this, we are creating our own custom jQuery method that can be used on a wrapped set of DOM elements.

Basically, a plugin attached to jQuery.fn allows us to create our own custom methods similar to any found in the API. This is because when we attach our plugin function to jQuery.fn, our function is included in the prototype chain-$.fn.count = function(){}-for jQuery objects created using the jQuery function. If that blows your mind, just remember that adding a function to jQuery.fn  means that the keyword this inside of the plugin function will refer to the jQuery object itself.

Notes: By adding a plugin to the jQuery.fn object, we are essentially saying that our plugin would like to use the jQuery function to select a context (DOM elements). If your plugin does not require a specific context (in other words a set of DOM elements) in which it needs to operate, you might not need to attach this plugin to the $.fn. It might make more sense to add it as a utility function in the jQuery namespace.

Inside a Plugin, this Is a Reference to the Current jQuery Object

When you attach a plugin to the jQuery.fn object, the keyword this used inside of the attached plugin function will refer to the current jQuery object.

It is critical that you grok exactly what the keyword this is referring to in the plugin function.

Using each() to Iterate Over the jQuery Object and Provide a Reference to Each Element In the Object Using the this Keyword

Using each(), we can create an implicit iteration for our plugin. This means that if the wrapper set contains more than one element, our plugin method will be applied to each element in the wrapper set.

To do this, we use the jQuery utility each() function, which is a generic iterator for both objects and arrays, basically simplifying looping. In the code example below, we use the function to iterate over the jQuery object itself. Inside of the function that is passed to each(), the keyword this will refer to the elements in the jQuery wrapper set.

Using the each() function is critical if you would like a plugin to employ implicit iteration.

Plugin Returning jQuery Object So jQuery Methods or Other Plugins Can Be Chained After Using Plugin

Typically, most plugins return the jQuery object itself so that the plugin does not break the chain. In other words, if a plugin does not specifically need to return a value, it should continue the chain so that additional methods can be applied to the wrapper set. In the code below, we are returning the jQuery object with the return this; statement so that chaining will not be broken. Notice that I am chaining on the parent() and append() methods after I call the count() plugin.

Notes: It is possible to make the plugin a destructive method by simply not returning the jQuery object.

Default Plugin Options

Plugins typically contain default options that will act as the baseline default configuration for the plugins' logic. These options are used when the plugin is invoked. In the code below I am creating a defaultOptions object containing a single property (startCount) and value (0). This object is stored on the count function $.fn.count.defaultOptions. We do this so the options are configurable from outside the plugin.

Custom Plugin Options

Typically, the default plugin options can be overwritten with custom options. In the code below, I pass in a customOptions object as a parameter to the plugin function. This object is combined with the defaultOptions object to create a single options object. We use the jQuery utility method extend() to combine multiple objects into a single object. The extend() method provides the perfect utility for overwriting an object with new properties. With this code in place, the plugin can now be customized when invoked. In the example, we pass the count plugin a custom number (500) to be used as the starting point for the count. This custom option overrides the default option (0).

Overwriting Default Options Without Altering Original Plugin Code

Since default options are accessible from outside a plugin, it is possible to reset the default options before invoking the plugin. This can be handy when you want to define your own options without altering the plugin code itself. Doing so can simplify plugin invocations because you can, in a sense, globally set up the plugin to your liking without forking the original plugin code itself.

Create Elements on the Fly, Invoke Plugins Programmatically

Depending on the nature of the plugin, it can be critical that a plugin be called both normally (via DOM elements and events) as well as programmatically. Consider a dialog plugin. There will be times that the modal/dialog will open based on user events. Other times, a dialog will need to open based on environmental or system events. In these situations, you can still invoke your plugin without any elements in the DOM by creating an element on the fly in order to invoke the plugin. In the code below, I invoke the dialog() plugin on page load by first creating an element to invoke my plugin.

Obviously, there could be a lot of variation of this pattern depending on the options, complexity, and functionality of the plugin. The point here is that plugins can be called via existing DOM elements, as well as those created on the fly.

Providing Callbacks and Passing Context

When authoring jQuery plugins, it is a good idea to provide callback functions as an option, and to pass these functions the context of this when the callback is invoked. This provides a vehicle for additional treatment to elements in a wrapper set. In the code below, we are passing a custom option to the outAndInFade() plugin method that is a function and should be called once the animation is complete. The callback function is being passed the value of this when it's being invoked. This allows us to then use the this value inside the function we defined. When the callback function is invoked, the keyword this will refer to one of the DOM elements contained within the wrapper set.

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.