Commit 3944517a authored by Marcel Klehr's avatar Marcel Klehr
Browse files

Merge pull request #1104 from Pita/release/releases-1.1.5

Version 1.1.5 release
parents e19c05d1 9cec0391
# v1.1.5
* We updated to express v3 (please [make sure](https://github.com/visionmedia/express/wiki/Migrating-from-2.x-to-3.x) your plugin works under express v3)
* `userColor` URL parameter which sets the initial author color
* Hooks for "padCreate", "padRemove", "padUpdate" and "padLoad" events
* Security patches concerning the handling of messages originating from clients
* Our database abstraction layer now natively supports couchDB, levelDB, mongoDB, postgres, and redis!
* We now provide a script helping you to migrate from dirtyDB to MySQL
* Support running Etherpad Lite behind IIS, using [iisnode](https://github.com/tjanczuk/iisnode/wiki)
* LibreJS Licensing information in headers of HTML templates
* Default port number to PORT env var, if port isn't specified in settings
* Fix for `convert.js`
* Raise upper char limit in chat to 999 characters
* Fixes for mobile layout
* Fixes for usage behind reverse proxy
* Improved documentation
* Fixed some opera style bugs
* Update npm and fix some bugs, this introduces
# v1.1
* Introduced Plugin framework
* Many bugfixes
......
doc_dirs = doc $(wildcard doc/*/)
outdoc_dirs = out $(addprefix out/,$(doc_dirs))
doc_sources = $(wildcard doc/*/*.md) $(wildcard doc/*.md)
outdoc_files = $(addprefix out/,$(doc_sources:.md=.html))
docs: $(outdoc_files)
docassets = $(addprefix out/,$(wildcard doc/_assets/*))
VERSION = $(shell node -e "console.log( require('./src/package.json').version )")
docs: $(outdoc_files) $(docassets)
out/doc/_assets/%: doc/_assets/%
mkdir -p $(@D)
cp $< $@
out/doc/%.html: doc/%.md
mkdir -p $(@D)
node tools/doc/generate.js --format=html --template=doc/template.html $< > $@
cat $@ | sed 's/__VERSION__/${VERSION}/' > $@
clean:
rm -rf out/
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
var startTime = new Date().getTime();
var fs = require("fs");
var ueberDB = require("ueberDB");
var mysql = require("mysql");
var async = require("async");
var ueberDB = require("../src/node_modules/ueberDB");
var mysql = require("../src/node_modules/ueberDB/node_modules/mysql");
var async = require("../src/node_modules/async");
var Changeset = require("ep_etherpad-lite/static/js/Changeset");
var randomString = require('ep_etherpad-lite/static/js/pad_utils').randomString;
var AttributePool = require("ep_etherpad-lite/static/js/AttributePool");
......
var dirty = require("../src/node_modules/ueberDB/node_modules/dirty")('var/dirty.db');
var db = require("../src/node/db/DB");
db.init(function() {
db = db.db;
dirty.on("load", function() {
dirty.forEach(function(key, value) {
db.set(key, value);
});
});
});
body.apidoc {
width: 60%;
min-width: 10cm;
margin: 0 auto;
}
#header {
background-color: #5a5;
padding: 10px;
color: #111;
}
a,
a:active {
color: #272;
}
a:focus,
a:hover {
color: #050;
}
#apicontent a.mark,
#apicontent a.mark:active {
float: right;
color: #BBB;
font-size: 0.7cm;
text-decoration: none;
}
#apicontent a.mark:focus,
#apicontent a.mark:hover {
color: #AAA;
}
#apicontent code {
padding: 1px;
background-color: #EEE;
border-radius: 4px;
border: 1px solid #DDD;
}
#apicontent pre>code {
display: block;
overflow: auto;
padding: 5px;
}
\ No newline at end of file
@include documentation
@include api/api
@include plugins
@include database
@include embed_parameters
@include http_api
@include hooks
@include hooks_overview
@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
......@@ -49,7 +49,8 @@ Called from: src/node/server.js
Things in context:
1. app - the main application object (helpful for adding new paths and such)
1. app - the main express application object (helpful for adding new paths and such)
2. server - the http server object
This hook gets called after the application object has been created, but before it starts listening. This is similar to the expressConfigure hook, but it's not guaranteed that the application object will have all relevant configuration variables.
......@@ -64,6 +65,42 @@ This hook gets called upon the rendering of an ejs template block. For any speci
Have a look at `src/templates/pad.html` and `src/templates/timeslider.html` to see which blocks are available.
## padCreate
Called from: src/node/db/Pad.js
Things in context:
1. pad - the pad instance
This hook gets called when a new pad was created.
## padLoad
Called from: src/node/db/Pad.js
Things in context:
1. pad - the pad instance
This hook gets called when an pad was loaded. If a new pad was created and loaded this event will be emitted too.
## padUpdate
Called from: src/node/db/Pad.js
Things in context:
1. pad - the pad instance
This hook gets called when an existing pad was updated.
## padRemove
Called from: src/node/db/Pad.js
Things in context:
1. padID
This hook gets called when an existing pad was removed/deleted.
## socketio
Called from: src/node/hooks/express/socketio.js
......@@ -71,6 +108,7 @@ Things in context:
1. app - the application object
2. io - the socketio object
3. server - the http server object
I have no idea what this is useful for, someone else will have to add this description.
......
......@@ -62,7 +62,7 @@ Portal submits content into new blog post
### Request Format
The API is accessible via HTTP. HTTP Requests are in the format /api/$APIVERSION/$FUNCTIONNAME. Parameters are transmitted via HTTP GET. $APIVERSION is 1
The API is accessible via HTTP. HTTP Requests are in the format /api/$APIVERSION/$FUNCTIONNAME. Parameters are transmitted via HTTP GET. $APIVERSION depends on the endpoints you want to use. The latest version is `1.1`
### Response Format
Responses are valid JSON in the following format:
......@@ -116,43 +116,93 @@ Example usage: http://api.jquery.com/jQuery.getJSON/
### Groups
Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test
* **createGroup()** creates a new group <br><br>*Example returns:*
#### createGroup()
* API >= 1
creates a new group
*Example returns:*
* `{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}`
* **createGroupIfNotExistsFor(groupMapper)** this functions helps you to map your application group ids to etherpad lite group ids <br><br>*Example returns:*
#### createGroupIfNotExistsFor(groupMapper)
* API >= 1
this functions helps you to map your application group ids to etherpad lite group ids
*Example returns:*
* `{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}`
* **deleteGroup(groupID)** deletes a group <br><br>*Example returns:*
#### deleteGroup(groupID)
* API >= 1
deletes a group
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"groupID does not exist", data: null}`
* **listPads(groupID)** returns all pads of this group<br><br>*Example returns:*
#### listPads(groupID)
* API >= 1
returns all pads of this group
*Example returns:*
* `{code: 0, message:"ok", data: {padIDs : ["g.s8oes9dhwrvt0zif$test", "g.s8oes9dhwrvt0zif$test2"]}`
* `{code: 1, message:"groupID does not exist", data: null}`
* **createGroupPad(groupID, padName [, text])** creates a new pad in this group <br><br>*Example returns:*
#### createGroupPad(groupID, padName [, text])
* API >= 1
creates a new pad in this group
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"pad does already exist", data: null}`
* `{code: 1, message:"groupID does not exist", data: null}`
* **listAllGroups()** lists all existing groups<br><br>*Example returns:*
#### listAllGroups()
* API >= 1
lists all existing groups
*Example returns:*
* `{code: 0, message:"ok", data: {groupIDs: ["g.mKjkmnAbSMtCt8eL", "g.3ADWx6sbGuAiUmCy"]}}`
* `{code: 0, message:"ok", data: {groupIDs: []}}`
### Author
These authors are bound to the attributes the users choose (color and name).
* **createAuthor([name])** creates a new author <br><br>*Example returns:*
#### createAuthor([name])
* API >= 1
creates a new author
*Example returns:*
* `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}`
* **createAuthorIfNotExistsFor(authorMapper [, name])** this functions helps you to map your application author ids to etherpad lite author ids <br><br>*Example returns:*
#### createAuthorIfNotExistsFor(authorMapper [, name])
* API >= 1
this functions helps you to map your application author ids to etherpad lite author ids
*Example returns:*
* `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}`
* **listPadsOfAuthor(authorID)** returns an array of all pads this author contributed to<br><br>*Example returns:*
#### listPadsOfAuthor(authorID)
* API >= 1
returns an array of all pads this author contributed to
*Example returns:*
* `{code: 0, message:"ok", data: {padIDs: ["g.s8oes9dhwrvt0zif$test", "g.s8oejklhwrvt0zif$foo"]}}`
* `{code: 1, message:"authorID does not exist", data: null}`
* **getAuthorName(authorID)** Returns the Author Name of the author <br><br>*Example returns:*
#### getAuthorName(authorID)
* API >= 1.1
Returns the Author Name of the author
*Example returns:*
* `{code: 0, message:"ok", data: {authorName: "John McLear"}}`
-> can't be deleted cause this would involve scanning all the pads where this author was
......@@ -160,25 +210,50 @@ These authors are bound to the attributes the users choose (color and name).
### Session
Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-seperated sessionIDs, allowing a user to edit pads in different groups at the same time. Only users with a valid session for this group, can access group pads. You can create a session after you authenticated the user at your web application, to give them access to the pads. You should save the sessionID of this session and delete it after the user logged out.
* **createSession(groupID, authorID, validUntil)** creates a new session. validUntil is an unix timestamp in seconds <br><br>*Example returns:*
#### createSession(groupID, authorID, validUntil)
* API >= 1
creates a new session. validUntil is an unix timestamp in seconds
*Example returns:*
* `{code: 0, message:"ok", data: {sessionID: "s.s8oes9dhwrvt0zif"}}`
* `{code: 1, message:"groupID doesn't exist", data: null}`
* `{code: 1, message:"authorID doesn't exist", data: null}`
* `{code: 1, message:"validUntil is in the past", data: null}`
* **deleteSession(sessionID)** deletes a session <br><br>*Example returns:*
#### deleteSession(sessionID)
* API >= 1
deletes a session
*Example returns:*
* `{code: 1, message:"ok", data: null}`
* `{code: 1, message:"sessionID does not exist", data: null}`
* **getSessionInfo(sessionID)** returns informations about a session <br><br>*Example returns:*
#### getSessionInfo(sessionID)
* API >= 1
returns informations about a session
*Example returns:*
* `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif", groupID: g.s8oes9dhwrvt0zif, validUntil: 1312201246}}`
* `{code: 1, message:"sessionID does not exist", data: null}`
* **listSessionsOfGroup(groupID)** returns all sessions of a group <br><br>*Example returns:*
#### listSessionsOfGroup(groupID)
* API >= 1
returns all sessions of a group
*Example returns:*
* `{"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}`
* `{code: 1, message:"groupID does not exist", data: null}`
* **listSessionsOfAuthor(authorID)** returns all sessions of an author <br><br>*Example returns:*
#### listSessionsOfAuthor(authorID)
* API >= 1
returns all sessions of an author
*Example returns:*
* `{"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}`
* `{code: 1, message:"authorID does not exist", data: null}`
......@@ -186,69 +261,149 @@ Sessions can be created between a group and an author. This allows an author to
Pad content can be updated and retrieved through the API
* **getText(padID, [rev])** returns the text of a pad <br><br>*Example returns:*
#### getText(padID, [rev])
* API >= 1
returns the text of a pad
*Example returns:*
* `{code: 0, message:"ok", data: {text:"Welcome Text"}}`
* `{code: 1, message:"padID does not exist", data: null}`
* **setText(padID, text)** sets the text of a pad <br><br>*Example returns:*
#### setText(padID, text)
* API >= 1
sets the text of a pad
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
* `{code: 1, message:"text too long", data: null}`
* **getHTML(padID, [rev])** returns the text of a pad formatted as HTML<br><br>*Example returns:*
#### getHTML(padID, [rev])
* API >= 1
returns the text of a pad formatted as HTML
*Example returns:*
* `{code: 0, message:"ok", data: {html:"Welcome Text<br>More Text"}}`
* `{code: 1, message:"padID does not exist", data: null}`
### Pad
Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security manager controls access of them and its forbidden for normal pads to include a $ in the name.
* **createPad(padID [, text])** creates a new (non-group) pad. Note that if you need to create a group Pad, you should call **createGroupPad**.<br><br>*Example returns:*
#### createPad(padID [, text])
* API >= 1
creates a new (non-group) pad. Note that if you need to create a group Pad, you should call **createGroupPad**.
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"pad does already exist", data: null}`
* **getRevisionsCount(padID)** returns the number of revisions of this pad <br><br>*Example returns:*
#### getRevisionsCount(padID)
* API >= 1
returns the number of revisions of this pad
*Example returns:*
* `{code: 0, message:"ok", data: {revisions: 56}}`
* `{code: 1, message:"padID does not exist", data: null}`
* **padUsersCount(padID)** returns the number of user that are currently editing this pad <br><br>*Example returns:*
#### padUsersCount(padID)
* API >= 1
returns the number of user that are currently editing this pad
*Example returns:*
* `{code: 0, message:"ok", data: {padUsersCount: 5}}`
* **padUsers(padID)** returns the list of users that are currently editing this pad <br><br>*Example returns:*
#### padUsers(padID)
* API >= 1.1
returns the list of users that are currently editing this pad
*Example returns:*
* `{code: 0, message:"ok", data: {padUsers: [{colorId:"#c1a9d9","name":"username1","timestamp":1345228793126},{"colorId":"#d9a9cd","name":"Hmmm","timestamp":1345228796042}]}}`
* `{code: 0, message:"ok", data: {padUsers: []}}`
* **deletePad(padID)** deletes a pad <br><br>*Example returns:*
#### deletePad(padID)
* API >= 1
deletes a pad
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
* **getReadOnlyID(padID)** returns the read only link of a pad <br><br>*Example returns:*
#### getReadOnlyID(padID)
* API >= 1
returns the read only link of a pad
*Example returns:*
* `{code: 0, message:"ok", data: {readOnlyID: "r.s8oes9dhwrvt0zif"}}`
* `{code: 1, message:"padID does not exist", data: null}`
* **setPublicStatus(padID, publicStatus)** sets a boolean for the public status of a pad <br><br>*Example returns:*
#### setPublicStatus(padID, publicStatus)
* API >= 1
sets a boolean for the public status of a pad
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
* **getPublicStatus(padID)** return true of false <br><br>*Example returns:*
#### getPublicStatus(padID)
* API >= 1
return true of false
*Example returns:*
* `{code: 0, message:"ok", data: {publicStatus: true}}`
* `{code: 1, message:"padID does not exist", data: null}`
* **setPassword(padID, password)** returns ok or a error message <br><br>*Example returns:*
#### setPassword(padID, password)
* API >= 1
returns ok or a error message
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
* **isPasswordProtected(padID)** returns true or false <br><br>*Example returns:*
#### isPasswordProtected(padID)
* API >= 1
returns true or false
*Example returns:*
* `{code: 0, message:"ok", data: {passwordProtection: true}}`
* `{code: 1, message:"padID does not exist", data: null}`
* **listAuthorsOfPad(padID)** returns an array of authors who contributed to this pad <br><br>*Example returns:*
#### listAuthorsOfPad(padID)
* API >= 1
returns an array of authors who contributed to this pad
*Example returns:*
* `{code: 0, message:"ok", data: {authorIDs : ["a.s8oes9dhwrvt0zif", "a.akf8finncvomlqva"]}`
* `{code: 1, message:"padID does not exist", data: null}`
* **getLastEdited(padID)** returns the timestamp of the last revision of the pad <br><br>*Example returns:*
#### getLastEdited(padID)
* API >= 1
returns the timestamp of the last revision of the pad
*Example returns:*
* `{code: 0, message:"ok", data: {lastEdited: 1340815946602}}`
* `{code: 1, message:"padID does not exist", data: null}`
* **sendClientsMessage(padID, msg)** sends a custom message of type `msg` to the pad <br><br>*Example returns:*
#### sendClientsMessage(padID, msg)
* API >= 1.1
sends a custom message of type `msg` to the pad
*Example returns:*
* `{code: 0, message:"ok", data: {}}`
* `{code: 1, message:"padID does not exist", data: null}`
# 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
?
## ...
# 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",
}
},