Question

I am currently developing a rather complex jQuery plugin. One that I am designing to be extensible. The quandary I have is how to exactly provide my users with the APIs available to them.

There are two methods that I can come up with:

1. Provide the API via an object in the global scope

   This is the method I am currently using. I do it similar to this:

   (function ($, win, undefined) {
       //main plugin functionality
       function pluginStuff() { /*...including method calling logic...*/ }
   
       //register function with jQuery
       $.fn.extend({ Plugin: pluginStuff });
   
       //register global API variable
       win.PluginAPI = { extendMe: {}, getVar: function() {} };
   })(jQuery, window);
   

   Unfortunately since I impliment the standard $().plugin('method') architecture its a little strange to have to use the jQuery method for some things and the API variable for others.

2. Provide the API via an object placed in jQuery

   I toyed with this method as well but its best practice to take up only a single slot in jQueries fn scope, as not to crowd the jQuery variable. In this method I would put my api variable in $.fn instead of the window:

   //register function with jQuery
   $.fn.extend({ Plugin: pluginStuff });
   
   //register global API variable
   $.fn.PluginAPI = { extendMe: {}, getVar: function() {} };
   

   I would rather not break this convention and take up two places.

---

Now that I write this I can see a third option where I assign my plugins slot in jQuery’s fn scope to be an object:

$.fn.Plugin = { plugin: pluginStuff, api: { extendMe: {}, getVar: function() {} } };

but how well received would this be if users had to do $('#elm').Plugin.plugin({ setting: 'value' }) to create a new instance of the plugin?

Any help or pointers would be greatly appreciated.

Please Note: I’m am not looking for a way to incorporate the API object into my plugin functionality. I am looking for a way to keep it separately modularized, but intuitively available for use/extension.

Answer 1

The method I eventually decided to use was registering the plugin under the fn namespace and the api variable under the jQuery $ namespace. Since methods and options set operate on an instance of the plugin $.fn is the best choice.

However, the API is global and does not link to a single instance. In this case $.fn doesn’t quite fit. What I ended up using was something similar to this:

(function ($, win, undefined) {
    //main plugin functionality
    function pluginStuff() { /*...including method calling logic...*/ }

    //register function with jQuery
    $.fn.Plugin = pluginStuff;

    //register global API variable
    $.Plugin = { extendMe: {}, getVar: function() {} };
})(jQuery, window);

now you can create an use a plugin object as expected:

$('#elm').Plugin();
$('#elm').Plugin('option', 'something', 'value');
$('#elm').Plugin('method');

and you can easily extend and access the API:

$.extend($.Plugin.extendMe, {
    moreStuff: {}
});
$.Plugin.getVar('var');

Thanks for the help everyone!