Add docs for plugins and plugin framework

@redhog please elaborate on / improve 'doc/api/pluginfw.md'!

5 files changed, 123 insertions, 17 deletions

diff --git a/README.plugins b/README.plugins
deleted file mode 100644
index 72c45644..00000000
--- a/README.plugins
+++ /dev/null
@@ -1,16 +0,0 @@
-So, a plugin is an npm package whose name starts with ep_ and that contains a file ep.json
-require("ep_etherpad-lite/static/js/plugingfw/plugins").update() will use npm to list all installed modules and read their ep.json files. These will contain registrations for hooks which are loaded
-A hook registration is a pairs of a hook name and a function reference (filename for require() plus function name)
-require("ep_etherpad-lite/static/js/plugingfw/hooks").callAll("hook_name", {argname:value}) will call all hook functions registered for hook_name
-That is the basis.
-Ok, so that was a slight simplification: inside ep.json, hook registrations are grouped into groups called "parts". Parts from all plugins are ordered using a topological sort according to "pre" and "post" pointers to other plugins/parts (just like dependencies, but non-installed plugins are silently ignored).
-This ordering is honored when you do callAll(hook_name) - hook functions for that hook_name are called in that order
-Ordering between plugins is undefined, only parts are ordered.
-
-A plugin usually has one part, but it van have multiple.
-This is so that it can insert some hook registration before that of another plugin, and another one after.
-This is important for e.g. registering URL-handlers for the express webserver, if you have some very generic and some very specific url-regexps
-So, that's basically it... apart from client-side hooks
-which works the same way, but uses a separate member of the part (part.client_hooks vs part.hooks), and where the hook function must obviously reside in a file require():able from the client...
-One thing more: The main etherpad tree is actually a plugin itself, called ep_etherpad-lite, and it has it's own ep.json...
-was that clear?
\ No newline at end of file
diff --git a/doc/all.md b/doc/all.md
index c0cbf369..f1e071a6 100644
--- a/doc/all.md
+++ b/doc/all.md
@@ -1,3 +1,4 @@
 @include documentation
 @include api/api
+@include plugins
 @include database
diff --git a/doc/api/api.md b/doc/api/api.md
index b96fa0c8..8ab5b3bd 100644
--- a/doc/api/api.md
+++ b/doc/api/api.md
@@ -4,4 +4,5 @@
 @include hooks_client-side
 @include hooks_server-side
 @include editorInfo
-@include changeset_library
\ No newline at end of file
+@include changeset_library
+@include pluginfw
\ No newline at end of file
diff --git a/doc/api/pluginfw.md b/doc/api/pluginfw.md
new file mode 100644
index 00000000..2189c74c
--- /dev/null
+++ b/doc/api/pluginfw.md
@@ -0,0 +1,14 @@
+# Plugin Framework
+`require("ep_etherpad-lite/static/js/plugingfw/plugins")`
+
+## plugins.update
+`require("ep_etherpad-lite/static/js/plugingfw/plugins").update()` will use npm to list all installed modules and read their ep.json files, registering the contained hooks.
+A hook registration is a pairs of a hook name and a function reference (filename for require() plus function name)
+
+## hooks.callAll
+`require("ep_etherpad-lite/static/js/plugingfw/hooks").callAll("hook_name", {argname:value})` will call all hook functions registered for `hook_name` with `{argname:value}`.
+
+## hooks.aCallAll
+?
+
+## ...
diff --git a/doc/plugins.md b/doc/plugins.md
new file mode 100644
index 00000000..3717c111
--- /dev/null
+++ b/doc/plugins.md
@@ -0,0 +1,106 @@
+# Plugins
+Etherpad-Lite allows you to extend its functionality with plugins. A plugin registers hooks (functions) for certain events (thus certain features) in Etherpad-lite to execute its own functionality based on these events.
+
+Publicly available plugins can be found in the npm registry (see <http://npmjs.org>). Etherpad-lite's naming convention for plugins is to prefix your plugins with `ep_`. So, e.g. it's `ep_flubberworms`. Thus you can install plugins from npm, using `npm install ep_flubberworm` in etherpad-lite's root directory.
+
+You can also browse to `http://yourEtherpadInstan.ce/admin/plugins`, which will list all installed plugins  and those available on npm. It even provides functionality to search through all available plugins.
+
+## Folder structure
+A basic plugin usually has the following folder structure:
+```
+ep_<plugin>/
+ | static/
+ | 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, and templates go into `templates/`.
+
+A Standard directory structure like this makes it easier to navigate through your code. That said, do note, that this is not actually *required* to make your plugin run.
+
+## Plugin definition
+Your plugin definition goes into `ep.json`. In this file you register your hooks, indicate the parts of your plugin and the order of execution. (A documentation of all available events to hook into can be found in chapter [hooks](#all_hooks).)
+
+A hook registration is a pairs of a hook name and a function reference (filename to require() + exported function name)
+
+```json
+{
+  "parts": [
+    {
+      "name": "nameThisPartHoweverYouWant",
+      "hooks": {
+        "authenticate" : "ep_<plugin>/<file>:FUNCTIONNAME1",
+        "expressCreateServer": "ep_<plugin>/<file>:FUNCTIONNAME2"
+      },
+      "client_hooks": {
+        "acePopulateDOMLine": "ep_plugin/<file>:FUNCTIONNAME3"
+      }
+    }
+  ]
+}
+```
+
+Etherpad-lite will expect the part of the hook definition before the colon to be a javascript file and will try to require it. The part after the colon is expected to be a valid function identifier of that module. So, you have to export your hooks, using [`module.exports`](http://nodejs.org/docs/latest/api/modules.html#modules_modules) and register it in `ep.json` as `ep_<plugin>/path/to/<file>:FUNCTIONNAME`.
+You can omit the `FUNCTIONNAME` part, if the exported function has got the same name as the hook. So `"authorize" : "ep_flubberworm/foo"` will call the function `exports.authorize` in `ep_flubberworm/foo.js`
+
+### Client hooks and server hooks
+There are server hooks, which will be executed on the server (e.g. `expressCreateServer`), and there are client hooks, which are executed on the client (e.g. `acePopulateDomLine`). Be sure to not make assumptions about the environment your code is running in, e.g. don't try to access `process`, if you know your code will be run on the client, and likewise, don't try to access `window` on the server...
+
+### Parts
+As your plugins become more and more complex, you will find yourself in the need to manage dependencies between plugins. E.g. you want the hooks of a certain plugin to be executed before (or after) yours. You can also manage these dependencies in your plugin definition file `ep.json`:
+
+```javascript
+{
+  "parts": [
+    {
+      "name": "onepart",
+      "pre": [],
+      "post": ["ep_onemoreplugin/partone"]
+      "hooks": {
+        "storeBar": "ep_monospace/plugin:storeBar",
+        "getFoo": "ep_monospace/plugin:getFoo",
+      }
+    },
+    {
+      "name": "otherpart",
+      "pre": ["ep_my_example/somepart", "ep_otherplugin/main"],
+      "post": [],
+      "hooks": {
+        "someEvent": "ep_my_example/otherpart:someEvent",
+        "another": "ep_my_example/otherpart:another"
+      }
+    }
+  ]
+}
+```
+
+Usually a plugin will add only one functionality at a time, so it will probably only use one `part` definition to register its hooks. However, sometimes you have to put different (unrelated) functionalities into one plugin. For this you will want use parts, so other plugins can depend on them.
+
+#### pre/post
+The `"pre"` and `"post"` definitions, affect the order in which parts of a plugin are executed. This ensures that plugins and their hooks are executed in the correct order.
+
+`"pre"` lists parts that must be executed *before* the defining part. `"post"` lists parts that must be executed *after* the defining part.
+
+You can, on a basic level, think of this as double-ended dependency listing. If you have a dependency on another plugin, you can make sure it loads before yours by putting it in `"pre"`. If you are setting up things that might need to be used by a plugin later, you can ensure proper order by putting it in `"post"`.
+
+Note that it would be far more sane to use `"pre"` in almost any case, but if you want to change config variables for another plugin, or maybe modify its environment, `"post"` could definitely be useful.
+
+Also, note that dependencies should *also* be listed in your package.json, so they can be `npm install`'d automagically when your plugin gets installed.
+
+## Package definition
+Your plugin must also contain a [package definition file](http://npmjs.org/doc/json.html), called package.json, in the project root - this file contains various metadata relevant to your plugin, such as the name and version number, author, project hompage, contributors, a short description, etc. If you publish your plugin on npm, these metadata are used for package search etc., but it's necessary for Etherpad-lite plugins, even if you don't publish your plugin.
+
+```json
+{
+  "name": "ep_PLUGINNAME",
+  "version": "0.0.1",
+  "description": "DESCRIPTION",
+  "author": "USERNAME (REAL NAME) <MAIL@EXAMPLE.COM>",
+  "contributors": [],
+  "dependencies": {"MODULE": "0.3.20"},
+  "engines": { "node": ">= 0.6.0"}
+}
+```
+
+## Templates
+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. See the following link for more information about EJS: <https://github.com/visionmedia/ejs>.
\ No newline at end of file