Make it easier to call a custom jQuery plugin

Question

I have written a plugin with the following "signature":

jQuery.fn.attach = function(element, settings, duration, options, callback) {

Here element is a jQuery object, settings are my custom settings for my plugin and duration, options and callback are all parameters that I use in jQuery's animate, like this:

someObject.animate({ someCSS }, duration, options, callback);

Now, my question is: Is it possible to make this function easier to call? For instance, right now, to get everything to work as I expect... I have to include all parameters and set the parameters that I don't use to null:

$(this).attach($('#e1-blue'), null, 3000, null, function() { alert('done'); });

It would be nice to also be able to call this as:

$(this).attach($('#e1-blue'), 3000, function() { alert('done'); });

and as this (ofc)...

$(this).attach($('#e1-blue'), 3000);

Any suggestions?

Answer 1

I suggest you look at method signatures to see how people handle optional arguments. For instance, look at http://gist.github.com/277432#LID5445 to see the setup behind jQuery.speed, which is what jQuery.animate uses - http://gist.github.com/277432#LID5445.

Regardless, you'd just want to look at the type of your arguments to see whether or not people passed them in.

Answer 2

The simplest thing I can think of is re-ordering the parameters such that the most commonly used ones come first. So if you change the function to:

jQuery.fn.attach = function(element, duration, callback, settings, options) {

then you can make everything (except probably the first parameter) optional by putting default values into the function body. Such as:

if(!duration)
   duration = 3000;

Then

$(this).attach($('#e1-blue'), 3000, function() { alert('done'); });

and

$(this).attach($('#e1-blue'), 3000);

would both be valid, with the other values automatically populated with null.

Strictly speaking, you could check for parameter types inside the function e.g. if the second paramter is an integer then it's the duration, if it's a function it's callback, if it's an object it's settings, but I don't think people who have to follow your code later will thank you for it. It could also make the function difficult to extend later down the line if e.g. a second integer parameter was required.

Answer 3

I setup a defaults object, and accept only one argument in the plugin function

  $.fn.myPlugin=function(opt){
    var o=$.extend({}, $.fn.myPlugin.defaults, opt||{});
  };
  $.fn.myPlugin.defaults={
    element: null,
    settings: null,
    options: null,
    callback: null,
    duration: 250
  };

Instantiate the plugin

$('#myElement').myPlugin({element: $('#el-blue'), duration: 2000})

If you're passing something every time, you could make the options object the second argument.

  $.fn.myPlugin=function(element, opt){
   return this.each(function(){
    var o=$.extend({}, $.fn.myPlugin.defaults, opt||{});
    //do some stuff
    if (o.callback) {
     o.callback.call(this, o);
    }
   });
  };

$('#myElement').myPlugin($('#el-blue'), {duration: 3000, callback: function(){}});