modplug

writing modular jQuery plugins made easy

Advertisement
1.1.0

When writing jQuery plugins some recurring steps need to be taken to fullfill the best practices for jQuery plugins. modplug encapsulates some steps so you can focus on the real logic of your plugin.

It's less than 1kB of code!

The sources and a changlog are available on GitHub.

Usage

It's really simple, the code exposes a local function modplug to register new plugins

// ... copy modplug here ...
 
var plugin = {
    methods: {
        back: function (col) {
 
            return this.each(function () {
 
                $(this).css('background-color', col);
            });
        }
    }
};
 
modplug('color', plugin);

After these lines you can access your plugin as follows to turn the background color of an element into red

$(selector).color('back', '#f00');

Detailed example

All you have to do is to specify a namespace and configure the plugin.

modplug(namespace: String, options: PluginOptions);

Possible options are

PluginOptions {
 
    // static methods will be accessible via $.<namespace>.methodname([args])
    statics: {}
 
    // methods will be accessible via $(selector).<namespace>('methodname', [args])
    methods: {}
 
    // a function that returns a static method name
    defaultStatic: undefined
 
    // a function that returns a method name
    defaultMethod: undefined
}

Example

To add functionality to your plugin add some functions to statics and/or methods.

var plugin = {
    statics: {
        random: function () {
 
            return 'hsl(' + Math.floor(Math.random() * 360) + ',95%,75%)';
        }
    },
    methods: {
        front: function (col) {
 
            return this.each(function () {
 
                $(this).css('color', col || plugin.statics.random());
            });
        },
        back: function (col) {
 
            return this.each(function () {
 
                $(this).css('background-color', col || plugin.statics.random());
            });
        }
    }
};
 
modplug('color', plugin);

Usage

Now we can access the plugin in the following ways:

// get a hsl formatted color string
var col = $.color.random();
 
// set the background color of all divs to red
$('div').color('back', '#f00');
 
// set the font color of all paragraphs to a random color
$('p').color('front');

More configuration

It's also possible to specify default functionality.

var plugin = {
 
    // ... same as above here ...
 
    defaultStatic: function () {
 
        return 'random';
    },
    defaultMethod: function () {
 
        return 'back';
    }
};

After that we are able to access those methods easier

var col = $.color();
// same as
var col = $.color.random();
 
$('div').color('#f00');
// same as
$('div').color('back', '#f00');

The above specified default methods will receive all arguments that were given, so it's possible to choose a default method based on these arguments

defaultMethod: function () {
 
    if (arguments.length) {
        return 'front';
    } else {
        return 'back';
    };
}

Complete code

jquery.color.js

(function($) {
    // ... copy modplug here ...
 
    var plugin = {
        statics: {
            front: function (col) {
 
                $('html').css('color', col || plugin.statics.random());
            },
            back: function (col) {
 
                $('html').css('background-color', col || plugin.statics.random());
            },
            random: function () {
 
                return 'hsl(' + Math.floor(Math.random() * 360) + ',95%,75%)';
            }
        },
 
        methods: {
            front: function (col) {
 
                return this.each(function () {
 
                    $(this).css('color', col || plugin.statics.random());
                });
            },
            back: function (col) {
 
                return this.each(function () {
 
                    $(this).css('background-color', col || plugin.statics.random());
                });
            }
        },
 
        defaultStatic: function () {
 
            return 'random';
        },
 
        defaultMethod: function () {
 
            return 'back';
        }
    };
 
    modplug('color', plugin);
 
}(jQuery));

Modules

If you've already used modplug to register a plugin it is possible to extend it...

$[namespace].modplug(options: ModuleOptions);

Possible options are

ModuleOptions {
 
    // static methods will be accessible via $.<namespace>.methodname([args])
    statics: {}
 
    // methods will be accessible via $(selector).<namespace>('methodname', [args])
    methods: {}
}

Example

var module = {
    methods: {
        border: function (col) {
 
            return this.each(function () {
 
                $(this).css('border-color', col || $.color.random());
            });
        }
    }
};
 
$.color.modplug(module);

you can use it like this

// set border color of all divs to red
$('div').color('border', '#f00');

License

modplug is provided under the terms of the MIT License.