Developing an API Pattern for a jQuery Plugin

There’s are lots of tutorials out there on how to write jQuery plugins. However, I think most struggle to get a balance between easy-to-maintain private code; and openly accessible code, but without variables passed around as arguments a thousand times.

Then I started to read how the jQuery Tools plugins were made. I’ve always liked how they expose an API to access ready-only properties, invoke public methods, and use available the callbacks. I also like how the plugin is kept extremely easy-to-read; and super simple for designers and developers to use.

So, here’s an attempt to break down how the plugins are developed, so that hopefully you can start implying this API-centric pattern for your own plugins.

Note: I will be creating a very simple jQuery plugin for an infinite carousel-like scroll on images. This is nothing special, but it’s a good enough example to show you the structure of the plugin.

1. Closure

Like any jQuery plugin, it’s a good idea to create a ‘closure’. This is something that wraps your code, and means that any variables instantiated inside of the closure are not directly accessible outside of it (the actual variable; not its value).

When it comes to jQuery, people tend to use what’s known as self-invocation to close off their plugins.

2. Options

Ok, it’s time to get your Moleskine out! Write down all the options that you think could be passed in to your plugin. On my example, I give the option to automatically run the carousel, and also whether it should pause on hover; and how long the delay on the automatic slide is. But, more importantly, is how we are passing these options into the plugin.

The “motionlab” bit is a namespace for your default config options. This comes in handy when developing multiple plugins under the same collection. Also very useful for when you want to extend a plugin – but that’s another story! All you need to know is that this means the defaults are well encapsulated this way. Just replace “motionlab” for something more meaningful (perhaps your own digital agency?)

3. Blueprint

This is the heart of the plugin: We’re going to create a class: a blueprint that the plugin, and its accompanying API, will use.

You might have already created some code that does roughly what you need. Well, this is where it’ll need to go. Just like any blueprint, you need think about it before you start writing. It’ll consist of the following things for now:

  • Any functions to change a state, or create some kind of movement. So, for my carousel example, I need to make it slide somehow, so i’ll need a “slide” function.
  • Any states that are changed will probably need to be tracked, so we’ll need some global variables towards the top of the class.
  • Any procedural code that’s needed to get the plugin going. This is often related to the options that are passed into it. (If it was going to be more advanced, this could probably be abstracted somehow; but to be honest, I’ve never tried!)
  • Let’s run through those requirements in another code example:

4. Wrapper

Believe it or not, we haven’t actually made the plugin yet. But we do have is a very well structured class, and a set of default options. We just need to mix it all together.

Then you can call it with the following code:

You’re probably thinking that you’ve seen all this before now. And you’re right. But the problem with the code so far is that it’s not very easy to customise the behaviour of the plugin after you’ve called it. (In fact, I think it’s impossible!) Let me show you how to change that

5. API

The API is like a little weavel, spawned by its best friend, jQuery’s data object. The first two things the API will allow you to do is to access any read-only properties from your plugin, and also invoke any public methods. And it’s actually really simple. By slightly amending the previous code example, we can pass back the plugin class to where it was called from.

So, what can we do with this then? Here’s an example of a souped-up plugin call…

5. Callbacks

Hopefully you’re already starting to see how this pattern can benefit the cleanliness of your jQuery code. But there’s more: callbacks. This allows the user’s code to ‘listen’ to your plugin code at certain points.

Note: I’m not sure why jQuery Tools binds the callbacks to both the current instance AND the root element. Any help with this would be appreciated!

You then create your callbacks in a similar way to using the API before…

6. Final points

(Here’s the all of the plugin put together)

What we have now is a gorgeous way to work. An ‘optional’ API offers a 2-tier difficulty. Users aren’t overwhelmed by it.

Private / helper methods

If you want to prevent functions from being used by the API, just don’t include them in the extend call. If they are global helper methods that don’t rely on the instance’s state, you can even create them outside of the plugin class altogether.

A massive thanks to the team at jQuery tools for coming up with this framework. This is merely a walkthrough of how to code just like those guys. And I hope I’ve got the right end of the stick


Leave a Reply

Your email address will not be published. Required fields are marked *