Plugin API Draft

This is extremely early work - one might even say speculation - on a proposed plugin API. Please add, delete, +1, or -1.

The Plugin API should be...

• The API should be unified (no distinction between server-side and UI plugins)
• custom js and css will remain, but should not be confused with plugins
• It should allow easy use of templates, as should some parts of core
• Plugins should (generally) be npm modules, but we must allow for "proprietary" plugins that aren't published
• Some existing features (e.g. timeslider, chat, import/export) should be pulled out into plugins, but would still be shipped with core
• This helps ensure a quality API and gives plugin authors some great examples
• This implies that plugins should be on the same "level" as core components; they will have deep access to the system

Examples of functionality/plugins

• Monospace button (could also be custom JS)
• Syntax highlighting (could also be custom JS)
• A complete Admin UI
• Integrated OpenID/BrowserID auth
• Core features (chat, timeslider, import/export)

A contrived example

Code layout

npm_modules/
 epl-example/
  index.js
  lib/
   example.js
   socketio_thing.js
  templates/
   huzzah.ejs
  static/
   js/
    a.js
    b.js
   css/
    c.css
  package.json

index.js

module.exports = require('./lib/example.js');

lib/example.js

var plugin = module.exports;

// Required settings
plugin.name = 'example';
plugin.version = '1.0';

// Optional settings with sensible defaults. These are the defaults.
plugin.templates = 'templates'; // Name of plugin's template dir
plugin.static = 'static'; // Name of plugin's static assets dir

// Right before this hook, the plugin is assigned a new prototype, which contains the API
plugin.init = function() {
  plugin.serveJS(); // Everything in static/js will be available under "/plugins/example/js/"
  this.serveCSS(); // Same as above. Yes, plugin == this.
  plugin.addMinifiedJS('pad.js', 'b.js'); // Appends "c.js" to the virtual pad.js minified file

  var root = this.rootPath; // The full filesystem path to the plugin's root dir
  // plugin.env holds useful info and objects from core, such as the express app, socketio handler, etc.
  var eplRoot = this.env.rootPath; // The full filesystem path to the EPL installation
  plugin.env.console.log("Logging!");

  // Direct access to the Express app - it's a great framework, why not?
  plugin.env.app.get('/some/path, function(req, res) {
    // A helper which gives "res.render" the full path to this plugin's templates
    plugin.render(res, 'huzzah');
  });

  // Add a component to the socketio handler
  var iothing = require('./socketio_thing');
  plugin.env.socketIO.addComponent('example, iothing);
}