es-microplugin

microplugin.js

Keep code modularized & extensible. MicroPlugin is a lightweight drop-in plugin architecture for your JavaScript library. Plugins can declare dependencies to other plugins and can be initialized with options (in a variety of formats). It AMD-compatible and it works identically in Node.js and in a browser.

$ npm install microplugin
$ bower install microplugin

Integration

Using the provided mixin, extend your function with the API for declaring and loading plugins:

var TextEditor = function(options) {
    this.initializePlugins(options.plugins);
};
 
MicroPlugin.mixin(TextEditor);

That's it for integration! Now you can selectively load the plugins on an instance-by-instance basis.

var editor = new TextEditor({
    plugins: ['links','images']
});

Loading Plugins

The initializePlugins() method sets up the plugin system and loads a list of plugins (with options). It accepts the list in three styles, depending on your preference.

List (no options)

["plugin_a","plugin_b","plugin_c"]

List (with options)

[
    {name: "plugin_a", options: { /* ... */ }},
    {name: "plugin_b", options: { /* ... */ }},
    {name: "plugin_c", options: { /* ... */ }}
]

Hash (with options)

{
    "plugin_a": { /* ... */ },
    "plugin_b": { /* ... */ },
    "plugin_c": { /* ... */ }
}

Plugin Design

Plugins aren't extravagant—they are barebones by design. A plugin is simply a function that gets called when an instance of your object is being constructed. Within that function, you can manually override methods, set up event listeners, etc. The this context will be the instance of your object.

Defining Plugins

MyLibrary.define("math", function(options) {
    // You can return values which will be available to other plugins
    // when they load the plugin via "require()". Explained more in
    // the next section.
    return {
        random : Math.random,
        sqrt   : Math.sqrt,
        sin2   : function(t) { return Math.pow(Math.sin(t), 2); },
        cos2   : function(t) { return Math.pow(Math.sin(t), 2); }
    };
});

Dependencies

Plugins can declare dependencies to other plugins (and use any exports they provide) through the require function.

MyLibrary.define("calculations", function(options) {
    var math    = this.require("math");
    var theta   = math.random();
    var success = math.sqrt(math.sin2(theta) + math.cos2(theta)) === 1;
 
    alert("Does the law of sines work? " + success);
});

API Reference

MicroPlugin.mixin(fn)

Sets up all methods on the function and its prototype for defining and loading plugins.

Mixin Methods

define(name, fn)

Declares a new plugin with the specified name.

[prototype].require(name)

Loads a plugin as a dependency and returns whatever it exports (if anything).

[prototype].initializePlugins(plugins)

Initializes the plugin system and loads a list of plugins with the provided options. The "plugins" argument can be in a variety of formats.

License

Copyright © 2013 Brian Reavis & Contributors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.