Table of Contents

About this Documentation#

The goal of this documentation is to comprehensively explain Etherpad, both from a reference as well as a conceptual point of view.

Where appropriate, property types, method arguments, and the arguments provided to event handlers are detailed in a list underneath the topic heading.

Every .html file is generated based on the corresponding .md file in the doc/api/ folder in the source tree. The documentation is generated using the bin/doc/generate.js program. The HTML template is located at doc/template.html.

Statistics#

Etherpad keeps track of the goings-on inside the edit machinery. If you'd like to have a look at this, just point your browser to /stats.

We currently measure:

Under the hood, we are happy to rely on measured for all our metrics needs.

To modify or simply access our stats in your plugin, simply require('ep_etherpad-lite/stats') which is a measured.Collection.

Localization#

Etherpad provides a multi-language user interface, that's apart from your users' content, so users from different countries can collaborate on a single document, while still having the user interface displayed in their mother tongue.

Translating#

We rely on https://translatewiki.net to handle the translation process for us, so if you'd like to help...

  1. Sign up at https://translatewiki.net
  2. Visit our TWN project page
  3. Click on Translate Etherpad lite interface
  4. Choose a target language, you'd like to translate our interface to, and hit Fetch
  5. Start translating!

Translations will be send back to us regularly and will eventually appear in the next release.

Implementation#

Server-side#

/src/locales contains files for all supported languages which contain the translated strings. Translation files are simple *.json files and look like this: 

{ "pad.modals.connected": "Connecté."
, "pad.modals.uderdup": "Ouvrir dans une nouvelle fenêtre."
, "pad.toolbar.unindent.title": "Dèsindenter"
, "pad.toolbar.undo.title": "Annuler (Ctrl-Z)"
, "timeslider.pageTitle": "{{appTitle}} Curseur temporel"
, ...
}

Each translation consists of a key (the id of the string that is to be translated) and the translated string. Terms in curly braces must not be touched but left as they are, since they represent a dynamically changing part of the string like a variable. Imagine a message welcoming a user: Welcome, {{userName}}! would be translated as Ahoy, {{userName}}! in pirate.

Client-side#

We use a language cookie to save your language settings if you change them. If you don't, we autodetect your locale using information from your browser. Then, the preferred language is fed into a library called html10n.js, which loads the appropriate translations and applies them to our templates. Its features include translation params, pluralization, include rules and a nice javascript API.

Localizing plugins#

1. Mark the strings to translate#

In the template files of your plugin, change all hardcoded messages/strings...

from: 

<option value="0">Heading 1</option>

to: 

<option data-l10n-id="ep_heading.h1" value="0"></option>

In the javascript files of your plugin, change all hardcoded messages/strings...

from: 

alert ('Chat');

to: 

alert(window._('pad.chat'));

2. Create translate files in the locales directory of your plugin#

Every time the http server is started, it will auto-detect your messages and merge them automatically with the core messages.

Overwrite core messages#

You can overwrite Etherpad's core messages in your plugin's locale files. For example, if you want to replace Chat with Notes, simply add...

ep_your-plugin/locales/en.json 

{ "ep_your-plugin.h1": "Heading 1"
, "pad.chat": "Notes"
}

Skins#

You can customize Etherpad appearance using skins. A skin is a directory located under static/skins/<skin_name>, with the following contents:

You can choose a skin changing the parameter skinName in settings.json.

Since Etherpad 1.7.5, two skins are included:

Embed parameters#

You can easily embed your etherpad-lite into any webpage by using iframes. You can configure the embedded pad using embed parameters.

Example:

Cut and paste the following code into any webpage to embed a pad. The parameters below will hide the chat and the line numbers. 

<iframe src='http://pad.test.de/p/PAD_NAME?showChat=false&showLineNumbers=false' width=600 height=400></iframe>

showLineNumbers#

Default: true

showControls#

Default: true

showChat#

Default: true

useMonospaceFont#

Default: false

userName#

Default: "unnamed"

Example: userName=Etherpad%20User

userColor#

Default: randomly chosen by pad server

Example: userColor=%23ff9900

noColors#

Default: false

alwaysShowChat#

Default: false

lang#

Default: en

Example: lang=ar (translates the interface into Arabic)

rtl#

Default: true Displays pad text from right to left.

HTTP API#

What can I do with this API?#

The API gives another web application control of the pads. The basic functions are

The API is designed in a way, so you can reuse your existing user system with their permissions, and map it to Etherpad. Means: Your web application still has to do authentication, but you can tell Etherpad via the api, which visitors should get which permissions. This allows Etherpad to fit into any web application and extend it with real-time functionality. You can embed the pads via an iframe into your website.

Take a look at HTTP API client libraries to check if a library in your favorite programming language is available.

Examples#

Example 1#

A portal (such as WordPress) wants to give a user access to a new pad. Let's assume the user have the internal id 7 and his name is michael.

Portal maps the internal userid to an etherpad author.

Request: http://pad.domain/api/1/createAuthorIfNotExistsFor?apikey=secret&name=Michael&authorMapper=7

Response: {code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}

Portal maps the internal userid to an etherpad group:

Request: http://pad.domain/api/1/createGroupIfNotExistsFor?apikey=secret&groupMapper=7

Response: {code: 0, message:"ok", data: {groupID: "g.s8oes9dhwrvt0zif"}}

Portal creates a pad in the userGroup

Request: http://pad.domain/api/1/createGroupPad?apikey=secret&groupID=g.s8oes9dhwrvt0zif&padName=samplePad&text=This is the first sentence in the pad

Response: {code: 0, message:"ok", data: null}

Portal starts the session for the user on the group:

Request: http://pad.domain/api/1/createSession?apikey=secret&groupID=g.s8oes9dhwrvt0zif&authorID=a.s8oes9dhwrvt0zif&validUntil=1312201246

Response: {"data":{"sessionID": "s.s8oes9dhwrvt0zif"}}

Portal places the cookie "sessionID" with the given value on the client and creates an iframe including the pad.

Example 2#

A portal (such as WordPress) wants to transform the contents of a pad that multiple admins edited into a blog post.

Portal retrieves the contents of the pad for entry into the db as a blog post:

Request: http://pad.domain/api/1/getText?apikey=secret&padID=g.s8oes9dhwrvt0zif$123

Response: {code: 0, message:"ok", data: {text:"Welcome Text"}}

Portal submits content into new blog post

Portal.AddNewBlog(content)

Usage#

API version#

The latest version is 1.2.13

The current version can be queried via /api.

Request Format#

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.

Response Format#

Responses are valid JSON in the following format: 

{
  "code": number,
  "message": string,
  "data": obj
}

Overview#

API Overview

Data Types#

Authentication#

Authentication works via a token that is sent with each request as a post parameter. There is a single token per Etherpad deployment. This token will be random string, generated by Etherpad at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad. Only Etherpad and the requesting application knows this key. Token management will not be exposed through this API.

Node Interoperability#

All functions will also be available through a node module accessible from other node.js applications.

JSONP#

The API provides JSONP support to allow requests from a server in a different domain. Simply add &jsonp=? to the API call.

Example usage: https://api.jquery.com/jQuery.getJSON/

API Methods#

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

Example returns: * {code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}

createGroupIfNotExistsFor(groupMapper)#

this functions helps you to map your application group ids to Etherpad group ids

Example returns: * {code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}

deleteGroup(groupID)#

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

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

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

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

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 author ids

Example returns: * {code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}

listPadsOfAuthor(authorID)#

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

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

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-separated 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

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

Example returns: {code: 0, message:"ok", data: null} {code: 1, message:"sessionID does not exist", data: null}

getSessionInfo(sessionID)#

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

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

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}

Pad Content#

Pad content can be updated and retrieved through the API

getText(padID, [rev])#

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

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}

appendText(padID, text)#

appends text to 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

Example returns: {code: 0, message:"ok", data: {html:"Welcome Text<br>More Text"}} {code: 1, message:"padID does not exist", data: null}

setHTML(padID, html)#

sets the text of a pad based on HTML, HTML must be well-formed. Malformed HTML will send a warning to the API log.

Example returns: {code: 0, message:"ok", data: null} {code: 1, message:"padID does not exist", data: null}

getAttributePool(padID)#

returns the attribute pool of a pad

Example returns: { "code":0, "message":"ok", "data": { "pool":{ "numToAttrib":{ "0":["author","a.X4m8bBWJBZJnWGSh"], "1":["author","a.TotfBPzov54ihMdH"], "2":["author","a.StiblqrzgeNTbK05"], "3":["bold","true"] }, "attribToNum":{ "author,a.X4m8bBWJBZJnWGSh":0, "author,a.TotfBPzov54ihMdH":1, "author,a.StiblqrzgeNTbK05":2, "bold,true":3 }, "nextNum":4 } } } {"code":1,"message":"padID does not exist","data":null}

getRevisionChangeset(padID, [rev])#

get the changeset at a given revision, or last revision if 'rev' is not defined.

Example returns: { "code" : 0, "message" : "ok", "data" : "Z:1>6b|5+6b$Welcome to Etherpad!\n\nThis pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!\n\nGet involved with Etherpad at http://etherpad.org\n" } {"code":1,"message":"padID does not exist","data":null} * {"code":1,"message":"rev is higher than the head revision of the pad","data":null}

createDiffHTML(padID, startRev, endRev)#

returns an object of diffs from 2 points in a pad

Example returns: {"code":0,"message":"ok","data":{"html":"<style>\n.authora_HKIv23mEbachFYfH {background-color: #a979d9}\n.authora_n4gEeMLsv1GivNeh {background-color: #a9b5d9}\n.removed {text-decoration: line-through; -ms-filter:'progid:DXImageTransform.Microsoft.Alpha(Opacity=80)'; filter: alpha(opacity=80); opacity: 0.8; }\n</style>Welcome to Etherpad!<br><br>This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!<br><br>Get involved with Etherpad at <a href=\"http&#x3a;&#x2F;&#x2F;etherpad&#x2e;org\">http:&#x2F;&#x2F;etherpad.org</a><br><span class=\"authora_HKIv23mEbachFYfH\">aw</span><br><br>","authors":["a.HKIv23mEbachFYfH",""]}} {"code":4,"message":"no or wrong API Key","data":null}

restoreRevision(padId, rev)#

Restores revision from past as new changeset

Example returns: {code:0, message:"ok", data:null} {code: 1, message:"padID does not exist", data: null}

Chat#

getChatHistory(padID, [start, end])#

returns

Example returns:

getChatHead(padID)#

returns the chatHead (last number of the last chat-message) of the pad

Example returns:

appendChatMessage(padID, text, authorID [, time])#

creates a chat message, saves it to the database and sends it to all connected clients of this pad

Example returns:

Pad#

Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security manager controls access of them and it's 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. You get an error message if you use one of the following characters in the padID: "/", "?", "&" or "#".

Example returns: {code: 0, message:"ok", data: null} {code: 1, message:"padID does already exist", data: null} * {code: 1, message:"malformed padID: Remove special characters", data: null}

getRevisionsCount(padID)#

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}

getSavedRevisionsCount(padID)#

returns the number of saved revisions of this pad

Example returns: {code: 0, message:"ok", data: {savedRevisions: 42}} {code: 1, message:"padID does not exist", data: null}

listSavedRevisions(padID)#

returns the list of saved revisions of this pad

Example returns: {code: 0, message:"ok", data: {savedRevisions: [2, 42, 1337]}} {code: 1, message:"padID does not exist", data: null}

saveRevision(padID [, rev])#

saves a revision

Example returns: {code: 0, message:"ok", data: null} {code: 1, message:"padID does not exist", data: null}

padUsersCount(padID)#

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

Example returns: {code: 0, message:"ok", data: {padUsers: [{colorId:"#c1a9d9","name":"username1","timestamp":1345228793126,"id":"a.n4gEeMLsvg12452n"},{"colorId":"#d9a9cd","name":"Hmmm","timestamp":1345228796042,"id":"a.n4gEeMLsvg12452n"}]}} {code: 0, message:"ok", data: {padUsers: []}}

deletePad(padID)#

deletes a pad

Example returns: {code: 0, message:"ok", data: null} {code: 1, message:"padID does not exist", data: null}

copyPad(sourceID, destinationID[, force=false])#

copies a pad with full history and chat. If force is true and the destination pad exists, it will be overwritten.

Example returns: {code: 0, message:"ok", data: null} {code: 1, message:"padID does not exist", data: null}

movePad(sourceID, destinationID[, force=false])#

moves a pad. If force is true and the destination pad exists, it will be overwritten.

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

Example returns: {code: 0, message:"ok", data: {readOnlyID: "r.s8oes9dhwrvt0zif"}} {code: 1, message:"padID does not exist", data: null}

getPadID(readOnlyID)#

returns the id of a pad which is assigned to the readOnlyID

Example returns: {code: 0, message:"ok", data: {padID: "p.s8oes9dhwrvt0zif"}} {code: 1, message:"padID does not exist", data: null}

setPublicStatus(padID, publicStatus)#

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

Example returns: {code: 0, message:"ok", data: {publicStatus: true}} {code: 1, message:"padID does not exist", data: null}

setPassword(padID, password)#

returns ok or an 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

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

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

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

Example returns: {code: 0, message:"ok", data: {}} {code: 1, message:"padID does not exist", data: null}

checkToken()#

returns ok when the current api token is valid

Example returns: {"code":0,"message":"ok","data":null} {"code":4,"message":"no or wrong API Key","data":null}

Pads#

listAllPads()#

lists all pads on this epl instance

Example returns: * {code: 0, message:"ok", data: {padIDs: ["testPad", "thePadsOfTheOthers"]}}

Hooks#

All hooks are called with two arguments:

  1. name - the name of the hook being called
  2. context - an object with some relevant information about the context of the call

Return values#

A hook should always return a list or undefined. Returning undefined is equivalent to returning an empty list. All the returned lists are appended to each other, so if the return values where [1, 2], undefined, [3, 4,], undefined and [5], the value returned by callHook would be [1, 2, 3, 4, 5].

This is, because it should never matter if you have one plugin or several plugins doing some work - a single plugin should be able to make callHook return the same value a set of plugins are able to return collectively. So, any plugin can return a list of values, of any length, not just one value.

Client-side hooks#

Most of these hooks are called during or in order to set up the formatting process.

documentReady#

Called from: src/templates/pad.html

Things in context:

nothing

This hook proxies the functionality of jQuery's $(document).ready event.

aceDomLinePreProcessLineAttributes#

Called from: src/static/js/domline.js

Things in context:

  1. domline - The current DOM line being processed
  2. cls - The class of the current block element (useful for styling)

This hook is called for elements in the DOM that have the "lineMarkerAttribute" set. You can add elements into this category with the aceRegisterBlockElements hook above. This hook is run BEFORE the numbered and ordered lists logic is applied.

The return value of this hook should have the following structure:

{ preHtml: String, postHtml: String, processedMarker: Boolean }

The preHtml and postHtml values will be added to the HTML display of the element, and if processedMarker is true, the engine won't try to process it any more.

aceDomLineProcessLineAttributes#

Called from: src/static/js/domline.js

Things in context:

  1. domline - The current DOM line being processed
  2. cls - The class of the current block element (useful for styling)

This hook is called for elements in the DOM that have the "lineMarkerAttribute" set. You can add elements into this category with the aceRegisterBlockElements hook above. This hook is run AFTER the ordered and numbered lists logic is applied.

The return value of this hook should have the following structure:

{ preHtml: String, postHtml: String, processedMarker: Boolean }

The preHtml and postHtml values will be added to the HTML display of the element, and if processedMarker is true, the engine won't try to process it any more.

aceCreateDomLine#

Called from: src/static/js/domline.js

Things in context:

  1. domline - the current DOM line being processed
  2. cls - The class of the current element (useful for styling)

This hook is called for any line being processed by the formatting engine, unless the aceDomLineProcessLineAttributes hook from above returned true, in which case this hook is skipped.

The return value of this hook should have the following structure:

{ extraOpenTags: String, extraCloseTags: String, cls: String }

extraOpenTags and extraCloseTags will be added before and after the element in question, and cls will be the new class of the element going forward.

acePostWriteDomLineHTML#

Called from: src/static/js/domline.js

Things in context:

  1. node - the DOM node that just got written to the page

This hook is for right after a node has been fully formatted and written to the page.

aceAttribsToClasses#

Called from: src/static/js/linestylefilter.js

Things in context:

  1. linestylefilter - the JavaScript object that's currently processing the ace attributes
  2. key - the current attribute being processed
  3. value - the value of the attribute being processed

This hook is called during the attribute processing procedure, and should be used to translate key, value pairs into valid HTML classes that can be inserted into the DOM.

The return value for this function should be a list of classes, which will then be parsed into a valid class string.

aceAttribClasses#

Called from: src/static/js/linestylefilter.js

Things in context: 1. Attributes - Object of Attributes

This hook is called when attributes are investigated on a line. It is useful if you want to add another attribute type or property type to a pad.

Example: 

exports.aceAttribClasses = function(hook_name, attr, cb){
  attr.sub = 'tag:sub';
  cb(attr);
}

aceGetFilterStack#

Called from: src/static/js/linestylefilter.js

Things in context:

  1. linestylefilter - the JavaScript object that's currently processing the ace attributes
  2. browser - an object indicating which browser is accessing the page

This hook is called to apply custom regular expression filters to a set of styles. The one example available is the ep_linkify plugin, which adds internal links. They use it to find the telltale [[ ]] syntax that signifies internal links, and finding that syntax, they add in the internalHref attribute to be later used by the aceCreateDomLine hook (documented above).

aceEditorCSS#

Called from: src/static/js/ace.js

Things in context: None

This hook is provided to allow custom CSS files to be loaded. The return value should be an array of resource urls or paths relative to the plugins directory.

aceInitInnerdocbodyHead#

Called from: src/static/js/ace.js

Things in context:

  1. iframeHTML - the HTML of the editor iframe up to this point, in array format

This hook is called during the creation of the editor HTML. The array should have lines of HTML added to it, giving the plugin author a chance to add in meta, script, link, and other tags that go into the <head> element of the editor HTML document.

aceEditEvent#

Called from: src/static/js/ace2_inner.js

Things in context:

  1. callstack - a bunch of information about the current action
  2. editorInfo - information about the user who is making the change
  3. rep - information about where the change is being made
  4. documentAttributeManager - information about attributes in the document (this is a mystery to me)

This hook is made available to edit the edit events that might occur when changes are made. Currently you can change the editor information, some of the meanings of the edit, and so on. You can also make internal changes (internal to your plugin) that use the information provided by the edit event.

aceRegisterNonScrollableEditEvents#

Called from: src/static/js/ace2_inner.js

Things in context: None

When aceEditEvent (documented above) finishes processing the event, it scrolls the viewport to make caret visible to the user, but if you don't want that behavior to happen you can use this hook to register which edit events should not scroll viewport. The return value of this hook should be a list of event names.

Example: 

exports.aceRegisterNonScrollableEditEvents = function(){
  return [ 'repaginate', 'updatePageCount' ];
}

aceRegisterBlockElements#

Called from: src/static/js/ace2_inner.js

Things in context: None

The return value of this hook will add elements into the "lineMarkerAttribute" category, making the aceDomLineProcessLineAttributes hook (documented below) call for those elements.

aceInitialized#

Called from: src/static/js/ace2_inner.js

Things in context:

  1. editorInfo - information about the user who will be making changes through the interface, and a way to insert functions into the main ace object (see ep_headings)
  2. rep - information about where the user's cursor is
  3. documentAttributeManager - some kind of magic

This hook is for inserting further information into the ace engine, for later use in formatting hooks.

postAceInit#

Called from: src/static/js/pad.js

Things in context:

  1. ace - the ace object that is applied to this editor.
  2. pad - the pad object of the current pad.

postToolbarInit#

Called from: src/static/js/pad_editbar.js

Things in context:

  1. ace - the ace object that is applied to this editor.
  2. toolbar - Editbar instance. See below for the Editbar documentation.

Can be used to register custom actions to the toolbar.

Usage examples:

postTimesliderInit#

Called from: src/static/js/timeslider.js

There doesn't appear to be any example available of this particular hook being used, but it gets fired after the timeslider is all set up.

userJoinOrUpdate#

Called from: src/static/js/pad_userlist.js

Things in context:

  1. info - the user information

This hook is called on the client side whenever a user joins or changes. This can be used to create notifications or an alternate user list.

chatNewMessage#

Called from: src/static/js/chat.js

Things in context:

  1. authorName - The user that wrote this message
  2. author - The authorID of the user that wrote the message
  3. text - the message text
  4. sticky (boolean) - if you want the gritter notification bubble to fade out on its own or just sit there
  5. timestamp - the timestamp of the chat message
  6. timeStr - the timestamp as a formatted string

This hook is called on the client side whenever a chat message is received from the server. It can be used to create different notifications for chat messages.

collectContentPre#

Called from: src/static/js/contentcollector.js

Things in context:

  1. cc - the contentcollector object
  2. state - the current state of the change being made
  3. tname - the tag name of this node currently being processed
  4. styl - the style applied to the node (probably CSS) -- Note the typo
  5. cls - the HTML class string of the node

This hook is called before the content of a node is collected by the usual methods. The cc object can be used to do a bunch of things that modify the content of the pad. See, for example, the heading1 plugin for etherpad original.

E.g. if you need to apply an attribute to newly inserted characters, call cc.doAttrib(state, "attributeName") which results in an attribute attributeName=true.

If you want to specify also a value, call cc.doAttrib(state, "attributeName::value") which results in an attribute attributeName=value.

collectContentImage#

Called from: src/static/js/contentcollector.js

Things in context:

  1. cc - the contentcollector object
  2. state - the current state of the change being made
  3. tname - the tag name of this node currently being processed
  4. style - the style applied to the node (probably CSS)
  5. cls - the HTML class string of the node
  6. node - the node being modified

This hook is called before the content of an image node is collected by the usual methods. The cc object can be used to do a bunch of things that modify the content of the pad.

Example: 

exports.collectContentImage = function(name, context){
  context.state.lineAttributes.img = context.node.outerHTML;
}

collectContentPost#

Called from: src/static/js/contentcollector.js

Things in context:

  1. cc - the contentcollector object
  2. state - the current state of the change being made
  3. tname - the tag name of this node currently being processed
  4. style - the style applied to the node (probably CSS)
  5. cls - the HTML class string of the node

This hook is called after the content of a node is collected by the usual methods. The cc object can be used to do a bunch of things that modify the content of the pad. See, for example, the heading1 plugin for etherpad original.

handleClientMessage_name#

Called from: src/static/js/collab_client.js

Things in context:

  1. payload - the data that got sent with the message (use it for custom message content)

This hook gets called every time the client receives a message of type name. This can most notably be used with the new HTTP API call, "sendClientsMessage", which sends a custom message type to all clients connected to a pad. You can also use this to handle existing types.

collab_client.js has a pretty extensive list of message types, if you want to take a look.

aceStartLineAndCharForPoint-aceEndLineAndCharForPoint#

Called from: src/static/js/ace2_inner.js

Things in context:

  1. callstack - a bunch of information about the current action
  2. editorInfo - information about the user who is making the change
  3. rep - information about where the change is being made
  4. root - the span element of the current line
  5. point - the starting/ending element where the cursor highlights
  6. documentAttributeManager - information about attributes in the document

This hook is provided to allow a plugin to turn DOM node selection into [line,char] selection. The return value should be an array of [line,char]

aceKeyEvent#

Called from: src/static/js/ace2_inner.js

Things in context:

  1. callstack - a bunch of information about the current action
  2. editorInfo - information about the user who is making the change
  3. rep - information about where the change is being made
  4. documentAttributeManager - information about attributes in the document
  5. evt - the fired event

This hook is provided to allow a plugin to handle key events. The return value should be true if you have handled the event.

collectContentLineText#

Called from: src/static/js/contentcollector.js

Things in context:

  1. cc - the contentcollector object
  2. state - the current state of the change being made
  3. tname - the tag name of this node currently being processed
  4. text - the text for that line

This hook allows you to validate/manipulate the text before it's sent to the server side. The return value should be the validated/manipulated text.

collectContentLineBreak#

Called from: src/static/js/contentcollector.js

Things in context:

  1. cc - the contentcollector object
  2. state - the current state of the change being made
  3. tname - the tag name of this node currently being processed

This hook is provided to allow whether the br tag should induce a new magic domline or not. The return value should be either true(break the line) or false.

disableAuthorColorsForThisLine#

Called from: src/static/js/linestylefilter.js

Things in context:

  1. linestylefilter - the JavaScript object that's currently processing the ace attributes
  2. text - the line text
  3. class - line class

This hook is provided to allow whether a given line should be deliniated with multiple authors. Multiple authors in one line cause the creation of magic span lines. This might not suit you and now you can disable it and handle your own deliniation. The return value should be either true(disable) or false.

aceSetAuthorStyle#

Called from: src/static/js/ace2_inner.js

Things in context:

  1. dynamicCSS - css manager for inner ace
  2. outerDynamicCSS - css manager for outer ace
  3. parentDynamicCSS - css manager for parent document
  4. info - author style info
  5. author - author info
  6. authorSelector - css selector for author span in inner ace

This hook is provided to allow author highlight style to be modified. Registered hooks should return 1 if the plugin handles highlighting. If no plugin returns 1, the core will use the default background-based highlighting.

aceSelectionChanged#

Called from: src/static/js/ace2_inner.js

Things in context:

  1. rep - information about where the user's cursor is
  2. documentAttributeManager - information about attributes in the document

This hook allows a plugin to react to a cursor or selection change, perhaps to update a UI element based on the style at the cursor location.

Server-side hooks#

These hooks are called on server-side.

loadSettings#

Called from: src/node/server.js

Things in context:

  1. settings - the settings object

Use this hook to receive the global settings in your plugin.

pluginUninstall#

Called from: src/static/js/pluginfw/installer.js

Things in context:

  1. plugin_name - self-explanatory

If this hook returns an error, the callback to the uninstall function gets an error as well. This mostly seems useful for handling additional features added in based on the installation of other plugins, which is pretty cool!

pluginInstall#

Called from: src/static/js/pluginfw/installer.js

Things in context:

  1. plugin_name - self-explanatory

If this hook returns an error, the callback to the install function gets an error, too. This seems useful for adding in features when a particular plugin is installed.

init_<plugin name>#

Called from: src/static/js/pluginfw/plugins.js

Things in context: None

This function is called after a specific plugin is initialized. This would probably be more useful than the previous two functions if you only wanted to add in features to one specific plugin.

expressConfigure#

Called from: src/node/hooks/express.js

Things in context:

  1. app - the main application object

This is a helpful hook for changing the behavior and configuration of the application. It's called right after the application gets configured.

expressCreateServer#

Called from: src/node/hooks/express.js

Things in context:

  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.

eejsBlock_<name>#

Called from: src/node/eejs/index.js

Things in context:

  1. content - the content of the block

This hook gets called upon the rendering of an ejs template block. For any specific kind of block, you can change how that block gets rendered by modifying the content object passed in.

Available blocks in pad.html are:

timeslider.html blocks:

padInitToolbar#

Called from: src/node/hooks/express/specialpages.js

Things in context:

  1. toolbar - the toolbar controller that will render the toolbar eventually

Here you can add custom toolbar items that will be available in the toolbar config in settings.json. For more about the toolbar controller see the API section.

Usage examples:

onAccessCheck#

Called from: src/node/db/SecurityManager.js

Things in context:

  1. padID - the pad the user wants to access
  2. password - the password the user has given to access the pad
  3. token - the token of the author
  4. sessionCookie - the session the use has

This hook gets called when the access to the concrete pad is being checked. Return false to deny access.

padCreate#

Called from: src/node/db/Pad.js

Things in context:

  1. pad - the pad instance
  2. author - the id of the author who created the pad

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 a 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
  2. author - the id of the author who updated the pad

This hook gets called when an existing pad was updated.

padCopy#

Called from: src/node/db/Pad.js

Things in context:

  1. originalPad - the source pad instance
  2. destinationID - the id of the pad copied from originalPad

This hook gets called when an existing pad was copied.

Usage examples:

padRemove#

Called from: src/node/db/Pad.js

Things in context:

  1. padID

This hook gets called when an existing pad was removed/deleted.

Usage examples:

socketio#

Called from: src/node/hooks/express/socketio.js

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.

authorize#

Called from: src/node/hooks/express/webaccess.js

Things in context:

  1. req - the request object
  2. res - the response object
  3. next - ?
  4. resource - the path being accessed

This is useful for modifying the way authentication is done, especially for specific paths.

authenticate#

Called from: src/node/hooks/express/webaccess.js

Things in context:

  1. req - the request object
  2. res - the response object
  3. next - ?
  4. username - the username used (optional)
  5. password - the password used (optional)

This is useful for modifying the way authentication is done.

authFailure#

Called from: src/node/hooks/express/webaccess.js

Things in context:

  1. req - the request object
  2. res - the response object
  3. next - ?

This is useful for modifying the way authentication is done.

handleMessage#

Called from: src/node/handler/PadMessageHandler.js

Things in context:

  1. message - the message being handled
  2. client - the client object from socket.io

This hook will be called once a message arrive. If a plugin calls callback(null) the message will be dropped. However, it is not possible to modify the message.

Plugins may also decide to implement custom behavior once a message arrives.

WARNING: handleMessage will be called, even if the client is not authorized to send this message. It's up to the plugin to check permissions.

Example: 

function handleMessage ( hook, context, callback ) {
  if ( context.message.type == 'USERINFO_UPDATE' ) {
    // If the message type is USERINFO_UPDATE, drop the message
    callback(null);
  }else{
    callback();
  }
};

handleMessageSecurity#

Called from: src/node/handler/PadMessageHandler.js

Things in context:

  1. message - the message being handled
  2. client - the client object from socket.io

This hook will be called once a message arrives. If a plugin calls callback(true) the message will be allowed to be processed. This is especially useful if you want read only pad visitors to update pad contents for whatever reason.

WARNING: handleMessageSecurity will be called, even if the client is not authorized to send this message. It's up to the plugin to check permissions.

Example: 

function handleMessageSecurity ( hook, context, callback ) {
  if ( context.message.boomerang == 'hipster' ) {
    // If the message boomer is hipster, allow the request
    callback(true);
  }else{
    callback();
  }
};

clientVars#

Called from: src/node/handler/PadMessageHandler.js

Things in context:

  1. clientVars - the basic clientVars built by the core
  2. pad - the pad this session is about

This hook will be called once a client connects and the clientVars are being sent. Plugins can use this hook to give the client an initial configuration, like the tracking-id of an external analytics-tool that is used on the client-side. You can also overwrite values from the original clientVars.

Example: 

exports.clientVars = function(hook, context, callback)
{
  // tell the client which year we are in
  return callback({ "currentYear": new Date().getFullYear() });
};

This can be accessed on the client-side using clientVars.currentYear.

getLineHTMLForExport#

Called from: src/node/utils/ExportHtml.js

Things in context:

  1. apool - pool object
  2. attribLine - line attributes
  3. text - line text

This hook will allow a plug-in developer to re-write each line when exporting to HTML.

Example: 

var Changeset = require("ep_etherpad-lite/static/js/Changeset");

exports.getLineHTMLForExport = function (hook, context) {
  var header = _analyzeLine(context.attribLine, context.apool);
  if (header) {
    return "<" + header + ">" + context.lineContent + "</" + header + ">";
  }
}

function _analyzeLine(alineAttrs, apool) {
  var header = null;
  if (alineAttrs) {
    var opIter = Changeset.opIterator(alineAttrs);
    if (opIter.hasNext()) {
      var op = opIter.next();
      header = Changeset.opAttributeValue(op, 'heading', apool);
    }
  }
  return header;
}

stylesForExport#

Called from: src/node/utils/ExportHtml.js

Things in context:

  1. padId - The Pad Id

This hook will allow a plug-in developer to append Styles to the Exported HTML.

Example: 

exports.stylesForExport = function(hook, padId, cb){
  cb("body{font-size:13.37em !important}");
}

aceAttribClasses#

Called from: src/static/js/linestylefilter.js

Things in context: 1. Attributes - Object of Attributes

This hook is called when attributes are investigated on a line. It is useful if you want to add another attribute type or property type to a pad.

Example: 

exports.aceAttribClasses = function(hook_name, attr, cb){
  attr.sub = 'tag:sub';
  cb(attr);
}

exportFileName#

Called from src/node/handler/ExportHandler.js

Things in context:

  1. padId

This hook will allow a plug-in developer to modify the file name of an exported pad. This is useful if you want to export a pad under another name and/or hide the padId under export. Note that the doctype or file extension cannot be modified for security reasons.

Example: 

exports.exportFileName = function(hook, padId, callback){
  callback("newFileName"+padId);
}

exportHtmlAdditionalTags#

Called from src/node/utils/ExportHtml.js

Things in context:

  1. Pad object

This hook will allow a plug-in developer to include more properties and attributes to support during HTML Export. If tags are stored as ['color', 'red'] on the attribute pool, use exportHtmlAdditionalTagsWithData instead. An Array should be returned.

Example: 

// Add the props to be supported in export
exports.exportHtmlAdditionalTags = function(hook, pad, cb){
  var padId = pad.id;
  cb(["massive","jugs"]);
};

exportHtmlAdditionalTagsWithData#

Called from src/node/utils/ExportHtml.js

Things in context:

  1. Pad object

Identical to exportHtmlAdditionalTags, but for tags that are stored with a specific value (not simply true) on the attribute pool. For example ['color', 'red'], instead of ['bold', true]. This hook will allow a plug-in developer to include more properties and attributes to support during HTML Export. An Array of arrays should be returned. The exported HTML will contain tags like <span data-color="red"> for the content where attributes are ['color', 'red'].

Example: 

// Add the props to be supported in export
exports.exportHtmlAdditionalTagsWithData = function(hook, pad, cb){
  var padId = pad.id;
  cb([["color", "red"], ["color", "blue"]]);
};

userLeave#

Called from src/node/handler/PadMessageHandler.js

This in context:

  1. session (including the pad id and author id)

This hook gets called when an author leaves a pad. This is useful if you want to perform certain actions after a pad has been edited

Example: 

exports.userLeave = function(hook, session, callback) {
  console.log('%s left pad %s', session.author, session.padId);
};

clientReady#

Called from src/node/handler/PadMessageHandler.js

This in context:

  1. message

This hook gets called when handling a CLIENT_READY which is the first message from the client to the server.

Example: 

exports.clientReady = function(hook, message) {
  console.log('Client has entered the pad' + message.padId);
};

editorInfo#

editorInfo.ace_replaceRange(start, end, text)#

This function replaces a range (from start to end) with text.

editorInfo.ace_getRep()#

Returns the rep object.

editorInfo.ace_getAuthor()#

editorInfo.ace_inCallStack()#

editorInfo.ace_inCallStackIfNecessary(?)#

editorInfo.ace_focus(?)#

editorInfo.ace_importText(?)#

editorInfo.ace_importAText(?)#

editorInfo.ace_exportText(?)#

editorInfo.ace_editorChangedSize(?)#

editorInfo.ace_setOnKeyPress(?)#

editorInfo.ace_setOnKeyDown(?)#

editorInfo.ace_setNotifyDirty(?)#

editorInfo.ace_dispose(?)#

editorInfo.ace_getFormattedCode(?)#

editorInfo.ace_setEditable(bool)#

editorInfo.ace_execCommand(?)#

editorInfo.ace_callWithAce(fn, callStack, normalize)#

editorInfo.ace_setProperty(key, value)#

editorInfo.ace_setBaseText(txt)#

editorInfo.ace_setBaseAttributedText(atxt, apoolJsonObj)#

editorInfo.ace_applyChangesToBase(c, optAuthor, apoolJsonObj)#

editorInfo.ace_prepareUserChangeset()#

editorInfo.ace_applyPreparedChangesetToBase()#

editorInfo.ace_setUserChangeNotificationCallback(f)#

editorInfo.ace_setAuthorInfo(author, info)#

editorInfo.ace_setAuthorSelectionRange(author, start, end)#

editorInfo.ace_getUnhandledErrors()#

editorInfo.ace_getDebugProperty(prop)#

editorInfo.ace_fastIncorp(?)#

editorInfo.ace_isCaret(?)#

editorInfo.ace_getLineAndCharForPoint(?)#

editorInfo.ace_performDocumentApplyAttributesToCharRange(?)#

editorInfo.ace_setAttributeOnSelection(attribute, enabled)#

Sets an attribute on current range. Example: `call.editorInfo.ace_setAttributeOnSelection("turkey::balls", true); // turkey is the attribute here, balls is the value Notes: to remove the attribute pass enabled as false

editorInfo.ace_toggleAttributeOnSelection(?)#

editorInfo.ace_getAttributeOnSelection(attribute, prevChar)#

Returns a boolean if an attribute exists on a selected range. prevChar value should be true if you want to get the previous Character attribute instead of the current selection for example if the caret is at position 0,1 (after first character) it's probable you want the attributes on the character at 0,0 The attribute should be the string name of the attribute applied to the selection IE subscript Example usage: Apply the activeButton Class to a button if an attribute is on a highlighted/selected caret position or range. Example var isItThere = documentAttributeManager.getAttributeOnSelection("turkey::balls", true);

See the ep_subscript plugin for an example of this function in action. Notes: Does not work on first or last character of a line. Suffers from a race condition if called with aceEditEvent.

editorInfo.ace_performSelectionChange(?)#

editorInfo.ace_doIndentOutdent(?)#

editorInfo.ace_doUndoRedo(?)#

editorInfo.ace_doInsertUnorderedList(?)#

editorInfo.ace_doInsertOrderedList(?)#

editorInfo.ace_performDocumentApplyAttributesToRange()#

editorInfo.ace_getAuthorInfos()#

Returns an info object about the author. Object key = author_id and info includes author's bg color value. Use to define your own authorship.

editorInfo.ace_performDocumentReplaceRange(start, end, newText)#

This function replaces a range (from [x1,y1] to [x2,y2]) with newText.

editorInfo.ace_performDocumentReplaceCharRange(startChar, endChar, newText)#

This function replaces a range (from y1 to y2) with newText.

editorInfo.ace_renumberList(lineNum)#

If you delete a line, calling this method will fix the line numbering.

editorInfo.ace_doReturnKey()#

Forces a return key at the current caret position.

editorInfo.ace_isBlockElement(element)#

Returns true if your passed element is registered as a block element

editorInfo.ace_getLineListType(lineNum)#

Returns the line's html list type.

editorInfo.ace_caretLine()#

Returns X position of the caret.

editorInfo.ace_caretColumn()#

Returns Y position of the caret.

editorInfo.ace_caretDocChar()#

Returns the Y offset starting from [x=0,y=0]

editorInfo.ace_isWordChar(?)#

Changeset Library#

"Z:z>1|2=m=b*0|1+1$\n"

This is a Changeset. It's just a string and it's very difficult to read in this form. But the Changeset Library gives us some tools to read it.

A changeset describes the diff between two revisions of the document. The Browser sends changesets to the server and the server sends them to the clients to update them. These Changesets also get saved into the history of a pad. This allows us to go back to every revision from the past.

Changeset.unpack(changeset)#

This function returns an object representation of the changeset, similar to this: 

{ oldLen: 35, newLen: 36, ops: '|2=m=b*0|1+1', charBank: '\n' }

Changeset.opIterator(ops)#

Returns an operator iterator. This iterator allows us to iterate over all operators that are in the changeset.

You can iterate with an opIterator using its next() and hasNext() methods. Next returns the next() operator object and hasNext() indicates, whether there are any operators left.

The Operator object#

There are 3 types of operators: +,- and =. These operators describe different changes to the document, beginning with the first character of the document. A = operator doesn't change the text, but it may add or remove text attributes. A - operator removes text. And a + Operator adds text and optionally adds some attributes to it.

Example#

{ opcode: '+',
  chars: 1,
  lines: 1,
  attribs: '*0' }

APool#

> var AttributePoolFactory = require("./utils/AttributePoolFactory");
> var apool = AttributePoolFactory.createAttributePool();
> console.log(apool)
{ numToAttrib: {},
  attribToNum: {},
  nextNum: 0,
  putAttrib: [Function],
  getAttrib: [Function],
  getAttribKey: [Function],
  getAttribValue: [Function],
  eachAttrib: [Function],
  toJsonable: [Function],
  fromJsonable: [Function] }

This creates an empty apool. An apool saves which attributes were used during the history of a pad. There is one apool for each pad. It only saves the attributes that were really used, it doesn't save unused attributes. Let's fill this apool with some values 

> apool.fromJsonable({"numToAttrib":{"0":["author","a.kVnWeomPADAT2pn9"],"1":["bold","true"],"2":["italic","true"]},"nextNum":3});
> console.log(apool)
{ numToAttrib: 
   { '0': [ 'author', 'a.kVnWeomPADAT2pn9' ],
     '1': [ 'bold', 'true' ],
     '2': [ 'italic', 'true' ] },
  attribToNum: 
   { 'author,a.kVnWeomPADAT2pn9': 0,
     'bold,true': 1,
     'italic,true': 2 },
  nextNum: 3,
  putAttrib: [Function],
  getAttrib: [Function],
  getAttribKey: [Function],
  getAttribValue: [Function],
  eachAttrib: [Function],
  toJsonable: [Function],
  fromJsonable: [Function] }

We used the fromJsonable function to fill the empty apool with values. the fromJsonable and toJsonable functions are used to serialize and deserialize an apool. You can see that it stores the relation between numbers and attributes. So for example the attribute 1 is the attribute bold and vise versa. An attribute is always a key value pair. For stuff like bold and italic it's just 'italic':'true'. For authors it's author:$AUTHORID. So a character can be bold and italic. But it can't belong to multiple authors 

> apool.getAttrib(1)
[ 'bold', 'true' ]

Simple example of how to get the key value pair for the attribute 1

AText#

> var atext = {"text":"bold text\nitalic text\nnormal text\n\n","attribs":"*0*1+9*0|1+1*0*1*2+b|1+1*0+b|2+2"};
> console.log(atext)
{ text: 'bold text\nitalic text\nnormal text\n\n',
  attribs: '*0*1+9*0|1+1*0*1*2+b|1+1*0+b|2+2' }

This is an atext. An atext has two parts: text and attribs. The text is just the text of the pad as a string. We will look closer at the attribs at the next steps 

> var opiterator = Changeset.opIterator(atext.attribs)
> console.log(opiterator)
{ next: [Function: next],
  hasNext: [Function: hasNext],
  lastIndex: [Function: lastIndex] }
> opiterator.next()
{ opcode: '+',
  chars: 9,
  lines: 0,
  attribs: '*0*1' }
> opiterator.next()
{ opcode: '+',
  chars: 1,
  lines: 1,
  attribs: '*0' }
> opiterator.next()
{ opcode: '+',
  chars: 11,
  lines: 0,
  attribs: '*0*1*2' }
> opiterator.next()
{ opcode: '+',
  chars: 1,
  lines: 1,
  attribs: '' }
> opiterator.next()
{ opcode: '+',
  chars: 11,
  lines: 0,
  attribs: '*0' }
> opiterator.next()
{ opcode: '+',
  chars: 2,
  lines: 2,
  attribs: '' }

The attribs are again a bunch of operators like .ops in the changeset was. But these operators are only + operators. They describe which part of the text has which attributes

For more information see /doc/easysync/easysync-notes.txt in the source.

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 pair 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#

?

...#

Toolbar controller#

src/node/utils/toolbar.js

button(opts)#

Returns: {Button}

Example: 

var orderedlist = toolbar.button({
  command: "insertorderedlist",
  localizationId: "pad.toolbar.ol.title",
  class: "buttonicon buttonicon-insertorderedlist"
})

You can also create buttons with text: 

var myButton = toolbar.button({
  command: "myButton",
  localizationId: "myPlugin.toolbar.myButton",
  class: "buttontext"
})

selectButton(opts)#

Returns: {SelectButton}

SelectButton.addOption(value, text, attributes)#

registerButton(name, item)#

isEnabled()#

disable()#

toggleDropDown(dropdown, callback)#

Shows the dropdown div.popup whose id equals dropdown.

registerCommand(cmd, callback)#

Register a handler for a specific command. Commands are fired if the corresponding button is clicked or the corresponding select is changed.

registerAceCommand(cmd, callback)#

Creates an ace callstack and calls the callback with an ace instance (and a toolbar item, if applicable): callback(cmd, ace, item).

Example: 

toolbar.registerAceCommand("insertorderedlist", function (cmd, ace) {
  ace.ace_doInsertOrderedList();
});

registerDropdownCommand(cmd, dropdown)#

Ties a div.popup where id equals dropdown to a command fired by clicking a button.

triggerCommand(cmd[, item])#

Triggers a command (optionally with some internal representation of the toolbar item that triggered it).

Plugins#

Etherpad 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 https://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/
 | locales/
 + 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/. Translations go into locales/

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. If you want to make use of our i18n system, you need to put your translations into locales/, though, in order to have them integrated. (See "Localization" for more info on how to localize your plugin)

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.)

A hook registration is a pairs of a hook name and a function reference (filename to require() + exported function name) 

{
  "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 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...

Styling#

When you install a client-side plugin (e.g. one that implements at least one client-side hook), the plugin name is added to the class attribute of the div #editorcontainerbox in the main window. This gives you the opportunity of tuning the appearance of the main UI in your plugin.

For example, this is the markup with no plugins installed: 

<div id="editorcontainerbox" class="">

and this is the contents after installing someplugin: 

<div id="editorcontainerbox" class="ep_someplugin">

This feature was introduced in Etherpad 1.8.

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: 

{
  "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, 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. 

{
  "name": "ep_PLUGINNAME",
  "version": "0.0.1",
  "description": "DESCRIPTION",
  "author": "USERNAME (REAL NAME) <MAIL@EXAMPLE.COM>",
  "contributors": [],
  "dependencies": {"MODULE": "0.3.20"},
  "engines": { "node": ">= 6.9.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 uses EJS for HTML templating. See the following link for more information about EJS: https://github.com/visionmedia/ejs.

Writing and running front-end tests for your plugin#

Etherpad allows you to easily create front-end tests for plugins.

  1. Create a new folder
    %your_plugin%/static/tests/frontend/specs

  2. Put your spec file in here (Example spec files are visible in %etherpad_root_folder%/frontend/tests/specs)

  3. Visit http://yourserver.com/frontend/tests your front-end tests will run.

Database structure#

Keys and their values#

groups#

A list of all existing groups (a JSON object with groupIDs as keys and 1 as values).

pad:$PADID#

Contains all information about pads

pad:$PADID:revs:$REVNUM#

Saves a revision $REVNUM of pad $PADID

pad:$PADID:chat:$CHATNUM#

Saves a chat entry with num $CHATNUM of pad $PADID

pad2readonly:$PADID#

Translates a padID to a readonlyID

readonly2pad:$READONLYID#

Translates a readonlyID to a padID

token2author:$TOKENID#

Translates a token to an authorID

globalAuthor:$AUTHORID#

Information about an author

mapper2group:$MAPPER#

Maps an external application identifier to an internal group

mapper2author:$MAPPER#

Maps an external application identifier to an internal author

group:$GROUPID#

a group of pads

author2sessions:$AUTHORID#

saves the sessions of an author

group2sessions:$GROUPID#