### 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](/substack/dnode) (*soon* - [now.js](/flotype/now), [beanpoll](beanpole)). - *soon* double as online async module loader (similar to [head](https://github.com/headjs/headjs)). ## Basic Usage A simple use case with express: ```javascript 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: ```javascript exports.plugin = function(server) { server.get('/', function(req, res) { res.send("Hello World!"); }); } ``` ## Plugins - [plugin.dnode](/crcn/plugin.dnode) - dnode plugin ## Plugin API ### plugin.require(path) includes target dependencies ```javascript 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` ```javascript 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: ```javascript plugin.params({ 'server': { 'port': 8080 } }). //or params('server', { port: 8080 }). require('server'); ``` api.server/index.js: ```javascript 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: ```javascript plugin.options({ message: 'hello world!' }).require('hello.plugin.js'); ``` hello.plugin.js: ```javascript 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 ```javascript 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: ```javascript plugin.loader().require('api.server').load().emit('doStuff'); ``` api.server/index.js: ```javascript 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()`. ```javascript //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. ```javascript 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. ```javascript 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`: ```javascript 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`.