Creating a plugin

Don't remove this!

What is a plugin?

Etherpad-Lite allows you to extend its functionality with plugins. A plugin registers functions for certain API hooks (thus certain features of etherpad-lite) to add its own functionality to these.

Tip: If you don't want to copy and paste all these files, you can clone the ep_base repository git clone [email protected]:niklasfi/ep_base

Replace all CAPITALIZED names with whatever you want.

Folder structure

A basic plugin has the following folder structure:

ep_PLUGINNAME/
 + ep.json
 + package.json
 + YOURFILE.js

However, a more advanced plugin should follow this folder structure:

ep_PLUGINNAME/
 | static/
   | js/
   | css/
   | image/
 | templates/
 + ep.json
 + package.json

If your plugin includes client-side hooks, put them in static/js/. If you're adding in CSS or image files, you should put those files in static/css/ and static/image/, respectively.

If your plugin adds or modifies the front end HTML (e.g. adding buttons or changing their functions), you should put the necessary HTML code for such operations in templates/, in files of type ".ejs", since Etherpad-Lite uses EJS for HTML templating.

A Standard directory structure like this makes it easier to navigate through your code. That said, please note, that none of this is actually required to make your plugin run, but it might come in handy some day...

ep.json

This file registers callback functions (hooks), indicates the parts of a plugin and the order of execution. Hooks are events for certain processes in Etherpad Lite; a documentation of all available hooks can be found here.

{
  "parts": [
    {
      "name": "YOURFILE",
      "hooks": {
        "authorize" : "ep_PLUGINNAME/YOURFILE:FUNCTIONNAME1",
        "authenticate": "ep_PLUGINNAME/YOURFILE:FUNCTIONNAME2",
        "expressCreateServer": "ep_PLUGINNAME/YOURFILE:FUNCTIONNAME3"
      }
    }
  ]
}

You can omit the FUNCTIONNAME part, if the function to register has got the same name as the hook. So "authorize" : "ep_PLGUINNAME/YOURFILE" will call the function exports.authorize in ep_PLUGINRNAME/YOURFILE

package.json

This must be an ordinary npm package file, describing the name , version number, author, dependencies, etc. of your plugin. Additionally, it allows you to publish your plugin in the npm registry.

{
  "name": "ep_PLUGINNAME",
  "version": "0.0.1",
  "description": "DESCRIPTION",
  "author": "USERNAME (REAL NAME) <[email protected]>",
  "contributors": [],
  "dependencies": {"MODULE": "0.3.20"},
  "engines": { "node": ">= 0.6.0"}
}

YOURFILE.js

A normal javascript file exporting the functions, that you want to register for their corresponding API hooks.

exports.FUNCTIONNAME1 = function(req, res, next, ressource){
  // ...
}

exports.FUNCTIONNAME2 = function(req, res, next, username, password){
 // ...
}

exports.FUNCTIONNAME3 = function(hook_name, args,cb){
 // ...
}

Creating your first plugin

Creating your own plugin in Etherpad Lite is really simple. You will need some basic Javascript understanding.

Step 1.

cd <path/to/etherpad-lite>/plugins-available
mkdir ep_my_example
cd ep_my_example
npm init

You can safely accept all the default settings suggested by npm init.

Step 2.

Edit your plugin config file package.json

{
  "name": "ep_my_example",  // Your plugin name must begin with ep_  
  "description": "Adds an Apple response on /apples",
  "version": "0.0.1",
  "author": "RedHog (Egil Moeller) <[email protected]>",
  "contributors": ["johnyma22 (John McLear) <[email protected]>"],
  "dependencies": {},
  "engines": { "node": ">= 0.4.1 < 0.7.0" }
}

Step 3.

Edit your plugin config file ep.json

{
  "parts": [
    {
      "name": "apples",
      "hooks": {
        "expressCreateServer": "ep_my_example/apples:expressCreateServer"
      }
    }
  ]
}

Step 4.

Create your actual plugin Javascript code.

exports.expressCreateServer = function (hook_name, args, cb) {
  args.app.get('/apples', function(req, res) {
    res.send("<em>Abra cadabra</em>");
  });
}

Step 5.

Install your plugin:

npm install ep_my_example

Step 6.

Start your server and test:

On linux, run:

$ ../../bin/run.sh

On windows:

..\..\start.bat

Now open http://localhost:9001/apples in your browser.