plugin

Plugin library

npm install plugin
3 downloads in the last day
66 downloads in the last week
538 downloads in the last month

Plugin Library for node.js

Motivation

  • Modularity - encourages code-reuse, abstraction, and encapsulation
  • Easily drop plugins in and out without breaking your program
  • Maintainability
  • Flexibility over dependencies
  • Asyncronously load remote plugins via dnode (soon - now.js, beanpoll).
  • soon double as online async module loader (similar to head).

Basic Usage

A simple use case with express:


var plugin = require('plugin').loader(),
server = require('express').createServer();

plugin.options(server, true).
require("path/to/plugins/dir");

server.listen(8080);

In your hello world plugin:


exports.plugin = function(server) {

    server.get('/', function(req, res) {

        res.send("Hello World!");
    });
}

Plugins

Plugin API

plugin.require(path)

includes target dependencies

plugins.require('path/to/plugin.js').      // require one plugin
require('path/to/plugins/dir').          // require all plugins in directory
require('path/to/plugins/**/*.plugin.js'). // find plugins, and load them
require('plugin1.js','plugin2.js','plugin3.js'). //multiple plugin args
require('./config.json').load(); //load plugins in configuration file { plugins: ['my/plugin.js','...'] }

plugin.paths(path)

adds a path to scan when requiring plugins. Similar to the old require.paths.unshift

plugin.paths('/path/to/plugins').require('my-plugin');

console.log(plugin.paths());// ['/path/to/plugins','/path/to/node_modules','...'];

plugin.params(params)

params specific to plugin - like constructor parameters

bootstrap.js:

plugin.params({
    'server': {
        'port': 8080
    }
}).

//or
params('server', { port: 8080 }).
require('server');

api.server/index.js:

exports.plugin = function(ops, params) {
    console.log(params.port); //8080    
}

plugin.options(ops)

Adds / returns options which are passed in the first parameter for each plugin.

bootstrap.js:

plugin.options({ message: 'hello world!' }).require('hello.plugin.js');

hello.plugin.js:

exports.plugin = function(ops) {
    console.log(ops.message); //hello world!
}

plugin.onLoad(pluginSearch, ret, callback)

Listens for when a plugin is ready - useful especially if a dnode server resets


plugin.onLoad('my.plugin', function() {

    console.log("ready!");
}).require('my.plugin');

plugin.local plugin.remote

remote/local collections. Same api as plugin (emit, plugin, plugins)

plugin.emit(type, data)

emits a method against all loaded plugins. If the method doesn't exist, it'll be ignored.

bootstrap.js:

plugin.loader().require('api.server').load().emit('doStuff');

api.server/index.js:

exports.plugin = function() {

    return {
        doStuff: function() {
            console.log("PREPARE");    
        },
        init: function() {
            console.log("INIT");
        }
    };
}

plugin.load()

Loads the plugins, and initializes them.

plugin.next(callback)

Queue function called after loading in all modules

plugin.exports

All the invokable methods against modules

plugin.plugins(search)

Returns multiple plugins based on the search criteria.


var loader = plugin.loader();

loader.require('oauth.part.twitter','oauth.part.facebook','oauth.core').
load(function() {
    loader.plugins(/^oauth.part.\w+$/).forEach(function(service) {

        //do stuff with the oauth plugins

    });
});

plugin.plugin(search)

Returns a single based on the search criteria given.

plugin.loaders

Loads plugins passed into plugin.require().

//dnode plugin
plugin.loaders.push({
    test: function(path) {
        return !!path.match(/dnode+\w+:\/\//); //dnode+https://my-dnode-server.com
    },
    load: function(path, callback) {
        //load dnode module here
    }
});

plugin.factory(fn)

Plugin factory function

plugin.factory(function(module, options, params) { return module(options, params); //instead of exports.plugin = function(){}, it would be module.exports = function(options, params) });

plugin.newPlugin

Plugin factory for plugin. Setting this method will change the way modules are loaded in.



plugin.newPlugin = function(module, options, params) {    
    return module(options, params); //instead of exports.plugin = function(){}, it would be module.exports = function(options, params)
};

Plugins API

exports.require

Dependencies for the given plugin. This is checked once plugin.call, or plugin.load is invoked. An exception is thrown if there are any missing dependencies.


exports.require = ['api.services.photos.*','another-plugin']; //requires any photo services. E.g: api.services.photos.facebook, api.services.photos.flickr

exports.require = [/api\.\w+/]; //regexp test

exports.require = function(name) { //function test
    return name.indexOf('api.services.photos') > -1
};

You can also load in any given plugin via exports.require:


exports.require = 'my-plugin';


exports.plugin = function() {

    var plugin = this;

    return {
        init: function() {

            plugin.plugin('my-plugin').doStuff();//return a single instance
            plugin.plugins('my-plugin').forEach(funtion(plugin) {//return multiple instances
                plugin.doStuff();
            });
        }
    }
}

exports.name

Optional name for the plugin. The default value is name provided when requiring the plugin.

Plugin exports.plugin(options, params, plugin)

Called when the plugin is loaded.

  • options - options which are passed to the plugin, along with every other plugin.
  • params - parameters which are specific to the loaded plugin.
  • plugin - the plugin loader. Also accessible via this.
  • return type can be void, or an object.
npm loves you