diff --git a/public/doc/v2.2.7/api/api.html b/public/doc/v2.2.7/api/api.html new file mode 100644 index 0000000..7447fe4 --- /dev/null +++ b/public/doc/v2.2.7/api/api.html @@ -0,0 +1,5761 @@ + + + + + + + +Embed parameters + + + + + +
+
+

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 and will auto-focus on Line 4.

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

showLineNumbers

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true

+
+
+
+

showControls

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true

+
+
+
+

showChat

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true

+
+
+
+

useMonospaceFont

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: false

+
+
+
+

userName

+
+
    +
  • +

    String

    +
    • +
+
+
+

Default: "unnamed"

+
+
+

Example: userName=Etherpad%20User

+
+
+
+

userColor

+
+
    +
  • +

    String (css hex color value)

    +
    • +
+
+
+

Default: randomly chosen by pad server

+
+
+

Example: userColor=%23ff9900

+
+
+
+

noColors

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: false

+
+
+
+

alwaysShowChat

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: false

+
+
+
+

lang

+
+
    +
  • +

    String

    +
    • +
+
+
+

Default: en

+
+
+

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

+
+
+
+

rtl

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true +Displays pad text from right to left.

+
+
+
+

#L

+
+
    +
  • +

    Int

    +
    • +
+
+
+

Default: 0 +Focuses pad at specific line number and places caret at beginning of this line +Special note: Is not a URL parameter but instead of a Hash value

+
+
+
+
+
+

HTTP API

+
+
+

What can I do with this API?

+
+

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

+
+
+
    +
  • +

    create/delete pads

    +
    • +
  • +

    grant/forbid access to pads

    +
    • +
  • +

    get/set pad content

    +
    • +
+
+
+

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.

+
+
+

OpenAPI

+
+

OpenAPI (formerly swagger) definitions are exposed under /api/openapi.json (latest) and /api/2.2.7/openapi.json. You can use official tools like Swagger Editor to view and explore them.

+
+
+
+
+

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

+
+
+

The current version can be queried via /api.

+
+
+
+

Request Format

+
+

The API is accessible via HTTP. Starting from 1.8, API endpoints can be invoked indifferently via GET or POST.

+
+
+

The URL of the HTTP request is of the form: /api/$APIVERSION/$FUNCTIONNAME. $APIVERSION depends on the endpoint you want to use. Depending on the verb you use (GET or POST) parameters can be passed differently.

+
+
+

When invoking via GET (mandatory until 1.7.5 included), parameters must be included in the query string (example: /api/$APIVERSION/$FUNCTIONNAME?apikey=<APIKEY>&param1=value1). Please note that starting with nodejs 8.14+ the total size of HTTP request headers has been capped to 8192 bytes. This limits the quantity of data that can be sent in an API request.

+
+
+

Starting from Etherpad 1.8 it is also possible to invoke the HTTP API via POST. In this case, querystring parameters will still be accepted, but any parameter with the same name sent via POST will take precedence. If you need to send large chunks of text (for example, for setText()) it is advisable to invoke via POST.

+
+
+

Example with cURL using GET (toy example, no encoding):

+
+
+
+
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname&text=this_text_will_NOT_be_encoded_by_curl_use_next_example"
+
+
+
+

Example with cURL using GET (better example, encodes text):

+
+
+
+
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname" --get --data-urlencode "text=Text sent via GET with proper encoding. For big documents, please use POST"
+
+
+
+

Example with cURL using POST:

+
+
+
+
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname" --data-urlencode "text=Text sent via POST with proper encoding. For big texts (>8 KB), use this method"
+
+
+
+
+

Response Format

+
+

Responses are valid JSON in the following format:

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

    code a return code

    +
    • +
  • +

    0 everything ok

    +
    • +
  • +

    1 wrong parameters

    +
    • +
  • +

    2 internal error

    +
    • +
  • +

    3 no such function

    +
    • +
  • +

    4 no or wrong API Key

    +
    • +
  • +

    message a status message. It’s ok if everything is fine, else it contains an error message

    +
    • +
  • +

    data the payload

    +
    • +
+
+
+
+

Overview

+
+
+API Overview +
+
+
+
+
+

Data Types

+
+
    +
  • +

    groupID a string, the unique id of a group. Format is g.16RANDOMCHARS, for example g.s8oes9dhwrvt0zif

    +
    • +
  • +

    sessionID a string, the unique id of a session. Format is s.16RANDOMCHARS, for example s.s8oes9dhwrvt0zif

    +
    • +
  • +

    authorID a string, the unique id of an author. Format is a.16RANDOMCHARS, for example a.s8oes9dhwrvt0zif

    +
    • +
  • +

    readOnlyID a string, the unique id of a readonly relation to a pad. Format is r.16RANDOMCHARS, for example r.s8oes9dhwrvt0zif

    +
    • +
  • +

    padID a string, format is GROUPID$PADNAME, for example the pad test of group g.s8oes9dhwrvt0zif has padID g.s8oes9dhwrvt0zif$test

    +
    • +
+
+
+

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.

+
+
+
+
+

API Methods

+
+

Groups

+
+

Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test

+
+
+
createGroup()
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

creates a new group

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
+
+
+
+
createGroupIfNotExistsFor(groupMapper)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

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)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

deletes a group

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"groupID does not exist", data: null}

    +
    • +
+
+
+
+
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], [authorId])
+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

creates a new pad in this group

+
+
+

Example returns:

+
+
+
    +
  • +

    {code: 0, message:"ok", data: {padID: "g.s8oes9dhwrvt0zif$test"}

    +
    • +
  • +

    {code: 1, message:"padName does already exist", data: null}

    +
    • +
  • +

    {code: 1, message:"groupID does not exist", data: null}

    +
    • +
+
+
+
+
listAllGroups()
+
+
    +
  • +

    API >= 1.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])
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

creates a new author

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
+
+
+
+
createAuthorIfNotExistsFor(authorMapper [, name])
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

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)
+
+
    +
  • +

    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)
+
+
    +
  • +

    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

+
+
+
+
+

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)
+
+
    +
  • +

    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)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

deletes a session

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"sessionID does not exist", data: null}

    +
    • +
+
+
+
+
getSessionInfo(sessionID)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

returns information 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)
+
+
    +
  • +

    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)
+
+
    +
  • +

    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}

    +
    • +
+
+
+
+
+

Pad Content

+
+

Pad content can be updated and retrieved through the API

+
+
+
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, [authorId])
+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

Sets the text of a pad.

+
+
+

If your text is long (>8 KB), please invoke via POST and include text parameter in the body of the request, not in the URL (since Etherpad 1.8).

+
+
+

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, [authorId])
+
+
    +
  • +

    API >= 1.2.13

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

Appends text to a pad.

+
+
+

If your text is long (>8 KB), please invoke via POST and include text parameter in the body of the request, not in the URL (since Etherpad 1.8).

+
+
+

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])
+
+
    +
  • +

    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}

    +
    • +
+
+
+
+
setHTML(padID, html, [authorId])
+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

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

+
+
+

If html is long (>8 KB), please invoke via POST and include html parameter in the body of the request, not in the URL (since Etherpad 1.8).

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+
getAttributePool(padID)
+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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])
+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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 https://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)
+
+
    +
  • +

    API >= 1.2.7

    +
    • +
+
+
+

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://etherpad.org\">http://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, [authorId])
+
+
    +
  • +

    API >= 1.2.11

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

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])
+
+
    +
  • +

    API >= 1.2.7

    +
    • +
+
+
+

returns

+
+
+
    +
  • +

    a part of the chat history, when start and end are given

    +
    • +
  • +

    the whole chat history, when no extra parameters are given

    +
    • +
+
+
+

Example returns:

+
+
+
    +
  • +

    {"code":0,"message":"ok","data":{"messages":[{"text":"foo","userId":"a.foo","time":1359199533759,"userName":"test"},{"text":"bar","userId":"a.foo","time":1359199534622,"userName":"test"}]}}

    +
    • +
  • +

    {code: 1, message:"start is higher or equal to the current chatHead", data: null}

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+
getChatHead(padID)
+
+
    +
  • +

    API >= 1.2.7

    +
    • +
+
+
+

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

+
+
+

Example returns:

+
+
+
    +
  • +

    {code: 0, message:"ok", data: {chatHead: 42}}

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+
appendChatMessage(padID, text, authorID [, time])
+
+
    +
  • +

    API >= 1.2.12

    +
    • +
+
+
+

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

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"text is no string", data: null}

    +
    • +
+
+
+
+
+
+

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], [authorId])

+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

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)

+
+
    +
  • +

    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}

    +
    • +
+
+
+
+

getSavedRevisionsCount(padID)

+
+
    +
  • +

    API >= 1.2.11

    +
    • +
+
+
+

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)

+
+
    +
  • +

    API >= 1.2.11

    +
    • +
+
+
+

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

+
+
    +
  • +

    API >= 1.2.11

    +
    • +
+
+
+

saves a revision

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+

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)

+
+
    +
  • +

    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,"id":"a.n4gEeMLsvg12452n"},{"colorId":"#d9a9cd","name":"Hmmm","timestamp":1345228796042,"id":"a.n4gEeMLsvg12452n"}]}}

    +
    • +
  • +

    {code: 0, message:"ok", data: {padUsers: []}}

    +
    • +
+
+
+
+

deletePad(padID)

+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

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

+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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}

    +
    • +
+
+
+
+

copyPadWithoutHistory(sourceID, destinationID, [force=false], [authorId])

+
+
    +
  • +

    API >= 1.2.15

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

copies a pad without copying the history and chat. If force is true and the destination pad exists, it will be overwritten. +Note that all the revisions will be lost! In most of the cases one should use copyPad API instead.

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+

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

+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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)

+
+
    +
  • +

    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}

    +
    • +
+
+
+
+

getPadID(readOnlyID)

+
+
    +
  • +

    API >= 1.2.10

    +
    • +
+
+
+

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)

+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

sets a boolean for the public status of a group pad

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
  • +

    {code: 1, message:"You can only get/set the publicStatus of pads that belong to a group", data: null}

    +
    • +
+
+
+
+

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}

    +
    • +
  • +

    {code: 1, message:"You can only get/set the publicStatus of pads that belong to a group", data: null}

    +
    • +
+
+
+
+

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)

+
+
    +
  • +

    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)

+
+
    +
  • +

    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}

    +
    • +
+
+
+
+

checkToken()

+
+
    +
  • +

    API >= 1.2

    +
    • +
+
+
+

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

+
+
    +
  • +

    API >= 1.2.1

    +
    • +
+
+
+

lists all pads on this epl instance

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
+
+
+
+

Global

+
+
getStats()
+
+
    +
  • +

    API >= 1.2.14

    +
    • +
+
+
+

get stats of the etherpad instance

+
+
+

Example returns:

+
+
+
    +
  • +

    {"code":0,"message":"ok","data":{"totalPads":3,"totalSessions": 2,"totalActivePads": 1}}

    +
    • +
+
+
+
+
+
+
+
+

Hooks

+
+
+

A hook function is registered with a hook via the plugin’s ep.json file. See +the Plugins section for details. A hook may have many registered functions from +different plugins.

+
+
+

Some hooks call their registered functions one at a time until one of them +returns a value. Others always call all of their registered functions and +combine the results (if applicable).

+
+
+

Registered hook functions

+
+

Note: The documentation in this section applies to every hook unless the +hook-specific documentation says otherwise.

+
+
+

Arguments

+
+

Hook functions are called with three arguments:

+
+
+
    +
  1. +

    hookName - The name of the hook being invoked.

    +
    2. +
  2. +

    context - An object with some relevant information about the context of the +call. See the hook-specific documentation for details.

    +
    3. +
  3. +

    cb - For asynchronous operations this callback can be called to signal +completion and optionally provide a return value. The callback takes a single +argument, the meaning of which depends on the hook (see the "Return values" +section for general information that applies to most hooks). This callback +always returns undefined.

    +
    4. +
+
+
+
+

Expected behavior

+
+

The presence of a callback parameter suggests that every hook function can run +asynchronously. While that is the eventual goal, there are some legacy hooks +that expect their hook functions to provide a value synchronously. For such +hooks, the hook functions must do one of the following:

+
+
+
    +
  • +

    Call the callback with a non-Promise value (undefined is acceptable) and +return undefined, in that order.

    +
    • +
  • +

    Return a non-Promise value other than undefined (null is acceptable) and +never call the callback. Note that async functions always return a +Promise, so they must never be used for synchronous hooks.

    +
    • +
  • +

    Only have two parameters (hookName and context) and return any non-Promise +value (undefined is acceptable).

    +
    • +
+
+
+

For hooks that permit asynchronous behavior, the hook functions must do one or +more of the following:

+
+
+
    +
  • +

    Return undefined and call the callback, in either order.

    +
    • +
  • +

    Return something other than undefined (null is acceptable) and never call +the callback. Note that async functions always return a Promise, so they +must never call the callback.

    +
    • +
  • +

    Only have two parameters (hookName and context).

    +
    • +
+
+
+

Note that the acceptable behaviors for asynchronous hook functions is a superset +of the acceptable behaviors for synchronous hook functions.

+
+
+ + + + + +
+
Warning
+		 +The number of parameters is determined by examining +Function.length, +which does not count default parameters +or "rest" parameters. +To avoid problems, do not use default or rest parameters when defining hook +functions. +
+
+
+
+

Return values

+
+

A hook function can provide a value to Etherpad in one of the following ways:

+
+
+
    +
  • +

    Pass the desired value as the first argument to the callback.

    +
    • +
  • +

    Return the desired value directly. The value must not be undefined unless +the hook function only has two parameters. (Hook functions with three +parameters that want to provide undefined should instead use the callback.)

    +
    • +
  • +

    For hooks that permit asynchronous behavior, return a Promise that resolves to +the desired value.

    +
    • +
  • +

    For hooks that permit asynchronous behavior, pass a Promise that resolves to +the desired value as the first argument to the callback.

    +
    • +
+
+
+

Examples:

+
+
+
+
exports.exampleOne = (hookName, context, callback) => {
+  return 'valueOne';
+};
+
+exports.exampleTwo = (hookName, context, callback) => {
+  callback('valueTwo');
+  return;
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleThree = (hookName, context, callback) => {
+  return new Promise('valueThree');
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleFour = (hookName, context, callback) => {
+  callback(new Promise('valueFour'));
+  return;
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleFive = async (hookName, context) => {
+  // Note that this function is async, so it actually returns a Promise that
+  // is resolved to 'valueFive'.
+  return 'valueFive';
+};
+
+
+
+

Etherpad collects the values provided by the hook functions into an array, +filters out all undefined values, then flattens the array one level. +Flattening one level makes it possible for a hook function to behave as if it +were multiple separate hook functions.

+
+
+

For example: Suppose a hook has eight registered functions that return the +following values: 1, [2], ['3a', '3b'] [[4]], undefined, +[undefined], [], and null. The value returned to the caller of the hook is +[1, 2, '3a', '3b', [4], undefined, null].

+
+
+
+
+
+
+

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. +
  2. +

    cls - The class of the current block element (useful for styling)

    +
    3. +
+
+
+

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. +
  2. +

    cls - The class of the current block element (useful for styling)

    +
    3. +
+
+
+

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. +
  2. +

    cls - The class of the current element (useful for styling)

    +
    3. +
+
+
+

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

    +
    2. +
+
+
+

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. +
  2. +

    key - the current attribute being processed

    +
    3. +
  3. +

    value - the value of the attribute being processed

    +
    4. +
+
+
+

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. +
  2. +

    browser - an object indicating which browser is accessing the page

    +
    3. +
+
+
+

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

    +
    2. +
+
+
+

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. +
  2. +

    editorInfo - information about the user who is making the change

    +
    3. +
  3. +

    rep - information about where the change is being made

    +
    4. +
  4. +

    documentAttributeManager - information about attributes in the document (this +is a mystery to me)

    +
    5. +
+
+
+

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. +
  2. +

    rep - information about where the user’s cursor is

    +
    3. +
  3. +

    documentAttributeManager - some kind of magic

    +
    4. +
+
+
+

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. +
  2. +

    clientVars - Object containing client-side configuration such as author ID +and plugin settings. Your plugin can manipulate this object via the +clientVars server-side hook.

    +
    3. +
  3. +

    pad - the pad object of the current pad.

    +
    4. +
+
+
+
+

postToolbarInit

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    ace - the ace object that is applied to this editor.

    +
    2. +
  2. +

    toolbar - Editbar instance. See below for the Editbar documentation.

    +
    3. +
+
+
+

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.

+
+
+
+

goToRevisionEvent

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    rev - The newRevision

    +
    2. +
+
+
+

This hook gets fired both on timeslider load (as timeslider shows a new +revision) and when the new revision is showed to a user. There doesn’t appear to +be any example available of this particular hook being used.

+
+
+
+

userJoinOrUpdate

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    info - the user information

    +
    2. +
+
+
+

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

+
+
+

This hook runs on the client side whenever a chat message is received from the +server. It can be used to create different notifications for chat messages. Hook +functions can modify the author, authorName, duration, rendered, +sticky, text, and timeStr context properties to change how the message is +processed. The text and timeStr properties may contain HTML and come +pre-sanitized; plugins should be careful to sanitize any added user input to +avoid introducing an XSS vulnerability.

+
+
+

Context properties:

+
+
+
    +
  • +

    authorName: The display name of the user that wrote the message.

    +
    • +
  • +

    author: The author ID of the user that wrote the message.

    +
    • +
  • +

    text: Sanitized message HTML, with URLs wrapped like <a +href="url">url</a>. (Note that message.text is not sanitized or processed +in any way.)

    +
    • +
  • +

    message: The raw message object as received from the server, except with +time correction and a default authorId property if missing. Plugins must not +modify this object. Warning: Unlike text, message.text is not +pre-sanitized or processed in any way.

    +
    • +
  • +

    rendered - Used to override the default message rendering. Initially set to +null. If the hook function sets this to a DOM element object or a jQuery +object, then that object will be used as the rendered message UI. Otherwise, +if this is set to null, then Etherpad will render a default UI for the +message using the other context properties.

    +
    • +
  • +

    sticky (boolean): Whether the gritter notification should fade out on its +own or just sit there until manually closed.

    +
    • +
  • +

    timestamp: When the chat message was sent (milliseconds since epoch), +corrected using the difference between the local clock and the server’s clock.

    +
    • +
  • +

    timeStr: The message timestamp as a formatted string.

    +
    • +
  • +

    duration: How long (in milliseconds) to display the gritter notification (0 +to disable).

    +
    • +
+
+
+
+

chatSendMessage

+
+

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

+
+
+

This hook runs on the client side whenever the user sends a new chat message. +Plugins can mutate the message object to change the message text or add metadata +to control how the message will be rendered by the chatNewMessage hook.

+
+
+

Context properties:

+
+
+
    +
  • +

    message: The message object that will be sent to the Etherpad server.

    +
    • +
+
+
+
+

collectContentPre

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    cc - the contentcollector object

    +
    2. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    styl - the style applied to the node (probably CSS) — Note the typo

    +
    5. +
  5. +

    cls - the HTML class string of the node

    +
    6. +
+
+
+

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. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    style - the style applied to the node (probably CSS)

    +
    5. +
  5. +

    cls - the HTML class string of the node

    +
    6. +
  6. +

    node - the node being modified

    +
    7. +
+
+
+

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. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    style - the style applied to the node (probably CSS)

    +
    5. +
  5. +

    cls - the HTML class string of the node

    +
    6. +
+
+
+

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)

    +
    2. +
+
+
+

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. +
  2. +

    editorInfo - information about the user who is making the change

    +
    3. +
  3. +

    rep - information about where the change is being made

    +
    4. +
  4. +

    root - the span element of the current line

    +
    5. +
  5. +

    point - the starting/ending element where the cursor highlights

    +
    6. +
  6. +

    documentAttributeManager - information about attributes in the document

    +
    7. +
+
+
+

This hook is provided to allow a plugin to turn DOM node selection into

+
+
+
+

aceKeyEvent

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    callstack - a bunch of information about the current action

    +
    2. +
  2. +

    editorInfo - information about the user who is making the change

    +
    3. +
  3. +

    rep - information about where the change is being made

    +
    4. +
  4. +

    documentAttributeManager - information about attributes in the document

    +
    5. +
  5. +

    evt - the fired event

    +
    6. +
+
+
+

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. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    text - the text for that line

    +
    5. +
+
+
+

This hook allows you to validate/manipulate the text before it’s sent to the +server side. To change the text, either:

+
+
+
    +
  • +

    Set the text context property to the desired value and return undefined.

    +
    • +
  • +

    (Deprecated) Return a string. If a hook function changes the text context +property, the return value is ignored. If no hook function changes text but +multiple hook functions return a string, the first one wins.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.collectContentLineText = (hookName, context) => {
+  context.text = tweakText(context.text);
+};
+
+
+
+
+

collectContentLineBreak

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    cc - the contentcollector object

    +
    2. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
+
+
+

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. +
  2. +

    text - the line text

    +
    3. +
  3. +

    class - line class

    +
    4. +
+
+
+

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. +
  2. +

    outerDynamicCSS - css manager for outer ace

    +
    3. +
  3. +

    parentDynamicCSS - css manager for parent document

    +
    4. +
  4. +

    info - author style info

    +
    5. +
  5. +

    author - author info

    +
    6. +
  6. +

    authorSelector - css selector for author span in inner ace

    +
    7. +
+
+
+

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. +
  2. +

    documentAttributeManager - information about attributes in the document

    +
    3. +
+
+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    settings - the settings object

    +
    2. +
+
+
+

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

+
+
+
+

shutdown

+
+

Called from: src/node/server.ts

+
+
+

Things in context: None

+
+
+

This hook runs before shutdown. Use it to stop timers, close sockets and files, +flush buffers, etc. The database is not available while this hook is running. +The shutdown function must not block for long because there is a short timeout +before the process is forcibly terminated.

+
+
+

The shutdown function must return a Promise, which must resolve to undefined. +Returning callback(value) will return a Promise that is resolved to value.

+
+
+

Example:

+
+
+
+
// using an async function
+exports.shutdown = async (hookName, context) => {
+  await flushBuffers();
+};
+
+
+
+
+

pluginUninstall

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    plugin_name - self-explanatory

    +
    2. +
+
+
+

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

    +
    2. +
+
+
+

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

+
+
+

Run during startup after the named plugin is initialized.

+
+
+

Context properties:

+
+
+
    +
  • +

    logger: An object with the following console-like methods: debug, +info, log, warn, error.

    +
    • +
+
+
+
+

expressPreSession

+
+

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

+
+
+

Called during server startup just before the +express-session middleware is +added to the Express Application object. Use this hook to add route handlers or +middleware that executes before express-session state is created and +authentication is performed. This is useful for creating public endpoints that +don’t spam the database with new express-session records or trigger +authentication.

+
+
+

WARNING: All handlers registered during this hook run before the built-in +authentication checks, so any handled endpoints will be public unless the +handler itself authenticates the user.

+
+
+

Context properties:

+
+
+ +
+
+

Example:

+
+
+
+
exports.expressPreSession = async (hookName, {app}) => {
+  app.get('/hello-world', (req, res) => res.send('hello world'));
+};
+
+
+
+
+

expressConfigure

+
+

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

+
+
+

Called during server startup just after the +express-session middleware is +added to the Express Application object. Use this hook to add route handlers or +middleware that executes after express-session state is created and +authentication is performed.

+
+
+

Context properties:

+
+
+ +
+
+
+

expressCreateServer

+
+

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

+
+
+

Identical to the expressConfigure hook (the two run in parallel with each +other) except this hook’s context includes the HTTP Server object.

+
+
+

Context properties:

+
+
+ +
+
+
+

expressCloseServer

+
+

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

+
+
+

Things in context: Nothing

+
+
+

This hook is called when the HTTP server is closing, which happens during +shutdown (see the shutdown hook) and when the server restarts (e.g., when a +plugin is installed via the /admin/plugins page). The HTTP server may or may +not already be closed when this hook executes.

+
+
+

Example:

+
+
+
+
exports.expressCloseServer = async () => {
+  await doSomeCleanup();
+};
+
+
+
+
+

eejsBlock_`<name>`

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    content - the content of the block

    +
    2. +
+
+
+

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:

+
+
+
    +
  • +

    htmlHead - after <html> and immediately before the title tag

    +
    • +
  • +

    styles - the style `<link>`s

    +
    • +
  • +

    body - the contents of the body tag

    +
    • +
  • +

    editbarMenuLeft - the left tool bar (consider using the toolbar controller instead of manually adding html here)

    +
    • +
  • +

    editbarMenuRight - right tool bar

    +
    • +
  • +

    afterEditbar - allows you to add stuff immediately after the toolbar

    +
    • +
  • +

    userlist - the contents of the userlist dropdown

    +
    • +
  • +

    loading - the initial loading message

    +
    • +
  • +

    mySettings - the left column of the settings dropdown ("My view"); intended for adding checkboxes only

    +
    • +
  • +

    mySettings.dropdowns - add your dropdown settings here

    +
    • +
  • +

    globalSettings - the right column of the settings dropdown ("Global view")

    +
    • +
  • +

    importColumn - import form

    +
    • +
  • +

    exportColumn - export form

    +
    • +
  • +

    modals - Contains all connectivity messages

    +
    • +
  • +

    embedPopup - the embed dropdown

    +
    • +
  • +

    scripts - Add your script tags here, if you really have to (consider use client-side hooks instead)

    +
    • +
+
+
+

timeslider.html blocks:

+
+
+
    +
  • +

    timesliderStyles

    +
    • +
  • +

    timesliderScripts

    +
    • +
  • +

    timesliderBody

    +
    • +
  • +

    timesliderTop

    +
    • +
  • +

    timesliderEditbarRight

    +
    • +
  • +

    modals

    +
    • +
+
+
+

index.html blocks:

+
+
+
    +
  • +

    indexCustomStyles - contains the index.css <link> tag, allows you to add your own or to customize the one provided by the active skin

    +
    • +
  • +

    indexWrapper - contains the form for creating new pads

    +
    • +
  • +

    indexCustomScripts - contains the index.js <script> tag, allows you to add your own or to customize the one provided by the active skin

    +
    • +
+
+
+
+

padInitToolbar

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    toolbar - the toolbar controller that will render the toolbar eventually

    +
    2. +
+
+
+

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 real ID (never the read-only ID) of the pad the user wants to +access

    +
    2. +
  2. +

    token - the token of the author

    +
    3. +
  3. +

    sessionCookie - the session the use has

    +
    4. +
+
+
+

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

+
+
+
+

getAuthorId

+
+

Called from src/node/db/AuthorManager.js

+
+
+

Called when looking up (or creating) the author ID for a user, except for author +IDs obtained via the HTTP API. Registered hook functions are called until one +returns a non-undefined value. If a truthy value is returned by a hook +function, it is used as the user’s author ID. Otherwise, the value of the +dbKey context property is used to look up the author ID. If there is no such +author ID at that key, a new author ID is generated and associated with that +key.

+
+
+

Context properties:

+
+
+
    +
  • +

    dbKey: Database key to use when looking up the user’s author ID if no hook +function returns an author ID. This is initialized to the user-supplied token +value (see the token context property), but hook functions can modify this +to control how author IDs are allocated to users. If no author ID is +associated with this database key, a new author ID will be randomly generated +and associated with the key. For security reasons, if this is modified it +should be modified to not look like a valid token (see the token context +property) unless the plugin intentionally wants the user to be able to +impersonate another user.

    +
    • +
  • +

    token: The user-supplied token, or nullish for an anonymous user. Tokens are +secret values that must not be disclosed to others. If non-null, the token is +guaranteed to be a string with the form t.<base64url> where <base64url> is +any valid non-empty base64url string (RFC 4648 section 5 with padding). +Example: t.twim3X2_KGiRj8cJ-3602g==.

    +
    • +
  • +

    user: If the user has authenticated, this is an object from settings.users +(or similar from an authentication plugin). Etherpad core and all good +authentication plugins set the username property of this object to a string +that uniquely identifies the authenticated user. This object is nullish if the +user has not authenticated.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.getAuthorId = async (hookName, context) => {
+  const {username} = context.user || {};
+  // If the user has not authenticated, or has "authenticated" as the guest
+  // user, do the default behavior (try another plugin if any, falling through
+  // to using the token as the database key).
+  if (!username || username === 'guest') return;
+  // The user is authenticated and has a username. Give the user a stable author
+  // ID so that they appear to be the same author even after clearing cookies or
+  // accessing the pad from another device. Note that this string is guaranteed
+  // to never have the form of a valid token; without that guarantee an
+  // unauthenticated user might be able to impersonate an authenticated user.
+  context.dbKey = `username=${username}`;
+  // Return a falsy but non-undefined value to stop Etherpad from calling any
+  // more getAuthorId hook functions and look up the author ID using the
+  // username-derived database key.
+  return '';
+};
+
+
+
+
+

padCreate

+
+

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

+
+
+

Called when a new pad is created.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object.

    +
    • +
  • +

    authorId: The ID of the author who created the pad.

    +
    • +
  • +

    author (deprecated): Synonym of authorId.

    +
    • +
+
+
+
+

padDefaultContent

+
+

Called from src/node/db/Pad.js

+
+
+

Called to obtain a pad’s initial content, unless the pad is being created with +specific content. The return value is ignored; to change the content, modify the +content context property.

+
+
+

This hook is run asynchronously. All registered hook functions are run +concurrently (via Promise.all()), so be careful to avoid race conditions when +reading and modifying the context properties.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The newly created Pad object.

    +
    • +
  • +

    authorId: The author ID of the user that is creating the pad.

    +
    • +
  • +

    type: String identifying the content type. Currently this is 'text' and +must not be changed. Future versions of Etherpad may add support for HTML, +jsdom objects, or other formats, so plugins must assert that this matches a +supported content type before reading content.

    +
    • +
  • +

    content: The pad’s initial content. Change this property to change the pad’s +initial content. If the content type is changed, the type property must also +be updated to match. Plugins must check the value of the type property +before reading this value.

    +
    • +
+
+
+
+

padLoad

+
+

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

+
+
+

Called when a pad is loaded, including after new pad creation.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object.

    +
    • +
+
+
+
+

padUpdate

+
+

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

+
+
+

Called when an existing pad is updated.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object.

    +
    • +
  • +

    authorId: The ID of the author who updated the pad.

    +
    • +
  • +

    author (deprecated): Synonym of authorId.

    +
    • +
  • +

    revs: The index of the new revision.

    +
    • +
  • +

    changeset: The changeset of this revision (see padUpdate).

    +
    • +
+
+
+
+

padCopy

+
+

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

+
+
+

Called when a pad is copied so that plugins can copy plugin-specific database +records or perform some other plugin-specific initialization.

+
+
+

Order of events when a pad is copied:

+
+
+
    +
  1. +

    Destination pad is deleted if it exists and overwrite is permitted. This +causes the padRemove hook to run.

    +
    2. +
  2. +

    Pad-specific database records are copied in the database, except for +records with plugin-specific database keys.

    +
    3. +
  3. +

    A new Pad object is created for the destination pad. This causes the +padLoad hook to run.

    +
    4. +
  4. +

    This hook runs.

    +
    5. +
+
+
+

Context properties:

+
+
+
    +
  • +

    srcPad: The source Pad object.

    +
    • +
  • +

    dstPad: The destination Pad object.

    +
    • +
+
+
+

Usage examples:

+
+
+ +
+
+
+

padRemove

+
+

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

+
+
+

Called when an existing pad is removed/deleted. Plugins should use this to clean +up any plugin-specific pad records from the database.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: Pad object for the pad that is being deleted.

    +
    • +
+
+
+

Usage examples:

+
+
+ +
+
+
+

padCheck

+
+

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

+
+
+

Called when a consistency check is run on a pad, after the core checks have +completed successfully. An exception should be thrown if the pad is faulty in +some way.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object that is being checked.

    +
    • +
+
+
+
+

socketio

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    app - the application object

    +
    2. +
  2. +

    io - the socketio object

    +
    3. +
  3. +

    server - the http server object

    +
    4. +
+
+
+

I have no idea what this is useful for, someone else will have to add this description.

+
+
+
+

preAuthorize

+
+

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

+
+
+

Called for each HTTP request before any authentication checks are performed. The +registered preAuthorize hook functions are called one at a time until one +explicitly grants or denies the request by returning true or false, +respectively. If none of the hook functions return anything, the access decision +is deferred to the normal authentication and authorization checks.

+
+
+

Example uses:

+
+
+
    +
  • +

    Always grant access to static content.

    +
    • +
  • +

    Process an OAuth callback.

    +
    • +
  • +

    Drop requests from IP addresses that have failed N authentication checks +within the past X minutes.

    +
    • +
+
+
+

Return values:

+
+
+
    +
  • +

    undefined (or []) defers the access decision to the next registered +preAuthorize hook function, or to the normal authentication and +authorization checks if no more preAuthorize hook functions remain.

    +
    • +
  • +

    true (or [true]) immediately grants access to the requested resource, +unless the request is for an /admin page in which case it is treated the +same as returning undefined. (This prevents buggy plugins from accidentally +granting admin access to the general public.)

    +
    • +
  • +

    false (or [false]) immediately denies the request. The preAuthnFailure +hook will be called to handle the failure.

    +
    • +
+
+
+

Context properties:

+
+
+
    +
  • +

    req: The Express Request object.

    +
    • +
  • +

    res: The Express Response +object.

    +
    • +
  • +

    next: Callback to immediately hand off handling to the next Express +middleware/handler, or to the next matching route if 'route' is passed as +the first argument. Do not call this unless you understand the consequences.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.preAuthorize = async (hookName, {req}) => {
+  if (await ipAddressIsFirewalled(req)) return false;
+  if (requestIsForStaticContent(req)) return true;
+  if (requestIsForOAuthCallback(req)) return true;
+  // Defer the decision to the next step by returning undefined.
+};
+
+
+
+
+

authorize

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
  3. +

    next - ?

    +
    4. +
  4. +

    resource - the path being accessed

    +
    5. +
+
+
+

This hook is called to handle authorization. It is especially useful for +controlling access to specific paths.

+
+
+

A plugin’s authorize function is only called if all of the following are true:

+
+
+
    +
  • +

    The request is not for static content or an API endpoint. (Requests for static +content and API endpoints are always authorized, even if unauthenticated.)

    +
    • +
  • +

    The requireAuthentication and requireAuthorization settings are both true.

    +
    • +
  • +

    The user has already successfully authenticated.

    +
    • +
  • +

    The user is not an admin (admin users are always authorized).

    +
    • +
  • +

    The path being accessed is not an /admin path (/admin paths can only be +accessed by admin users, and admin users are always authorized).

    +
    • +
  • +

    An authorize function from a different plugin has not already caused +authorization to pass or fail.

    +
    • +
+
+
+

Note that the authorize hook cannot grant access to /admin pages. If admin +access is desired, the is_admin user setting must be set to true. This can be +set in the settings file or by the authenticate hook.

+
+
+

You can pass the following values to the provided callback:

+
+
+
    +
  • +

    [true] or ['create'] will grant access to modify or create the pad if the +request is for a pad, otherwise access is simply granted. Access to a pad will +be downgraded to modify-only if settings.editOnly is true or the user’s +canCreate setting is set to false, and downgraded to read-only if the +user’s readOnly setting is true.

    +
    • +
  • +

    ['modify'] will grant access to modify but not create the pad if the request +is for a pad, otherwise access is simply granted. Access to a pad will be +downgraded to read-only if the user’s readOnly setting is true.

    +
    • +
  • +

    ['readOnly'] will grant read-only access.

    +
    • +
  • +

    [false] will deny access.

    +
    • +
  • +

    [] or undefined will defer the authorization decision to the next +authorization plugin (if any, otherwise deny).

    +
    • +
+
+
+

Example:

+
+
+
+
exports.authorize = (hookName, context, cb) => {
+  const user = context.req.session.user;
+  const path = context.req.path;  // or context.resource
+  if (isExplicitlyProhibited(user, path)) return cb([false]);
+  if (isExplicitlyAllowed(user, path)) return cb([true]);
+  return cb([]);  // Let the next authorization plugin decide
+};
+
+
+
+
+

authenticate

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
  3. +

    users - the users object from settings.json (possibly modified by plugins)

    +
    4. +
  4. +

    next - ?

    +
    5. +
  5. +

    username - the username used (optional)

    +
    6. +
  6. +

    password - the password used (optional)

    +
    7. +
+
+
+

This hook is called to handle authentication.

+
+
+

Plugins that supply an authenticate function should probably also supply an +authnFailure function unless falling back to HTTP basic authentication is +appropriate upon authentication failure.

+
+
+

This hook is only called if either the requireAuthentication setting is true +or the request is for an /admin page.

+
+
+

Calling the provided callback with [true] or [false] will cause +authentication to succeed or fail, respectively. Calling the callback with [] +or undefined will defer the authentication decision to the next authentication +plugin (if any, otherwise fall back to HTTP basic authentication).

+
+
+

If you wish to provide a mix of restricted and anonymous access (e.g., some pads +are private, others are public), you can "authenticate" (as a guest account) +users that have not yet logged in, and rely on other hooks (e.g., authorize, +onAccessCheck, handleMessageSecurity) to authorize specific privileged actions.

+
+
+

If authentication is successful, the authenticate function MUST set +context.req.session.user to the user’s settings object. The username +property of this object should be set to the user’s username. The settings +object should come from global settings (context.users[username]).

+
+
+

Example:

+
+
+
+
exports.authenticate = (hook_name, context, cb) => {
+  if (notApplicableToThisPlugin(context)) {
+    return cb([]);  // Let the next authentication plugin decide
+  }
+  const username = authenticate(context);
+  if (!username) {
+    console.warn(`ep_myplugin.authenticate: Failed authentication from IP ${context.req.ip}`);
+    return cb([false]);
+  }
+  console.info(`ep_myplugin.authenticate: Successful authentication from IP ${context.req.ip} for user ${username}`);
+  const users = context.users;
+  if (!(username in users)) users[username] = {};
+  users[username].username = username;
+  context.req.session.user = users[username];
+  return cb([true]);
+};
+
+
+
+
+

authFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
  3. +

    next - ?

    +
    4. +
+
+
+

DEPRECATED: Use authnFailure or authzFailure instead.

+
+
+

This hook is called to handle an authentication or authorization failure.

+
+
+

Plugins that supply an authenticate function should probably also supply an +authnFailure function unless falling back to HTTP basic authentication is +appropriate upon authentication failure.

+
+
+

A plugin’s authFailure function is only called if all of the following are true:

+
+
+
    +
  • +

    There was an authentication or authorization failure.

    +
    • +
  • +

    The failure was not already handled by an authFailure function from another +plugin.

    +
    • +
  • +

    For authentication failures: The failure was not already handled by the +authnFailure hook.

    +
    • +
  • +

    For authorization failures: The failure was not already handled by the +authzFailure hook.

    +
    • +
+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to the next authFailure plugin (if +any, otherwise fall back to HTTP basic authentication for an authentication +failure or a generic 403 page for an authorization failure).

+
+
+

Example:

+
+
+
+
exports.authFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) {
+    return cb([]);  // Let the next plugin handle the error
+  }
+  context.res.redirect(makeLoginURL(context.req));
+  return cb([true]);
+};
+
+
+
+
+

preAuthzFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
+
+
+

This hook is called to handle a pre-authentication authorization failure.

+
+
+

A plugin’s preAuthzFailure function is only called if the pre-authentication +authorization failure was not already handled by a preAuthzFailure function from +another plugin.

+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to a preAuthzFailure function from +another plugin (if any, otherwise fall back to a generic 403 error page).

+
+
+

Example:

+
+
+
+
exports.preAuthzFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) return cb([]);
+  context.res.status(403).send(renderFancy403Page(context.req));
+  return cb([true]);
+};
+
+
+
+
+

authnFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
+
+
+

This hook is called to handle an authentication failure.

+
+
+

Plugins that supply an authenticate function should probably also supply an +authnFailure function unless falling back to HTTP basic authentication is +appropriate upon authentication failure.

+
+
+

A plugin’s authnFailure function is only called if the authentication failure +was not already handled by an authnFailure function from another plugin.

+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to an authnFailure function from +another plugin (if any, otherwise fall back to the deprecated authFailure hook).

+
+
+

Example:

+
+
+
+
exports.authnFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) return cb([]);
+  context.res.redirect(makeLoginURL(context.req));
+  return cb([true]);
+};
+
+
+
+
+

authzFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
+
+
+

This hook is called to handle a post-authentication authorization failure.

+
+
+

A plugin’s authzFailure function is only called if the authorization failure was +not already handled by an authzFailure function from another plugin.

+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to an authzFailure function from +another plugin (if any, otherwise fall back to the deprecated authFailure hook).

+
+
+

Example:

+
+
+
+
exports.authzFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) return cb([]);
+  if (needsPremiumAccount(context.req) && !context.req.session.user.premium) {
+    context.res.status(200).send(makeUpgradeToPremiumAccountPage(context.req));
+    return cb([true]);
+  }
+  // Use the generic 403 forbidden response.
+  return cb([]);
+};
+
+
+
+
+

handleMessage

+
+

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

+
+
+

This hook allows plugins to drop or modify incoming socket.io messages from +clients, before Etherpad processes them. If any hook function returns null +then the message will not be subject to further processing.

+
+
+

Context properties:

+
+
+
    +
  • +

    message: The message being handled.

    +
    • +
  • +

    sessionInfo: Object describing the socket.io session with the following +properties:

    +
    • +
  • +

    authorId: The user’s author ID.

    +
    • +
  • +

    padId: The real (not read-only) ID of the pad.

    +
    • +
  • +

    readOnly: Whether the client has read-only access (true) or read/write +access (false).

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
  • +

    client: (Deprecated; use socket instead.) Synonym of socket.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.handleMessage = async (hookName, {message, socket}) => {
+  if (message.type === 'USERINFO_UPDATE') {
+    // Force the display name to the name associated with the account.
+    const user = socket.client.request.session.user || {};
+    if (user.name) message.data.userInfo.name = user.name;
+  }
+};
+
+
+
+
+

handleMessageSecurity

+
+

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

+
+
+

Called for each incoming message from a client. Allows plugins to grant +temporary write access to a pad.

+
+
+

Supported return values:

+
+
+
    +
  • +

    undefined: No change in access status.

    +
    • +
  • +

    'permitOnce': Override the user’s read-only access for the current +COLLABROOM message only. Has no effect if the current message is not a +COLLABROOM message, or if the user already has write access to the pad.

    +
    • +
  • +

    true: (Deprecated; return 'permitOnce' instead.) Override the user’s +read-only access for all COLLABROOM messages from the same socket.io +connection (including the current message, if applicable) until the client’s +next CLIENT_READY message. Has no effect if the user already has write +access to the pad. Read-only access is reset after each CLIENT_READY +message, so returning true has no effect for CLIENT_READY messages.

    +
    • +
+
+
+

Context properties:

+
+
+
    +
  • +

    message: The message being handled.

    +
    • +
  • +

    sessionInfo: Object describing the socket.io connection with the following +properties:

    +
    • +
  • +

    authorId: The user’s author ID.

    +
    • +
  • +

    padId: The real (not read-only) ID of the pad.

    +
    • +
  • +

    readOnly: Whether the client has read-only access (true) or read/write +access (false).

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
  • +

    client: (Deprecated; use socket instead.) Synonym of socket.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.handleMessageSecurity = async (hookName, context) => {
+  const {message, sessionInfo: {readOnly}} = context;
+  if (!readOnly || message.type !== 'COLLABROOM') return;
+  if (await messageIsBenign(message)) return 'permitOnce';
+};
+
+
+
+
+

clientVars

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    clientVars - the basic clientVars built by the core

    +
    2. +
  2. +

    pad - the pad this session is about

    +
    3. +
  3. +

    socket - the socket.io Socket object

    +
    4. +
+
+
+

This hook is called after a client connects but before the initial configuration +is sent to the client. Plugins can use this hook to manipulate the +configuration. (Example: Add a tracking ID for an external analytics tool that +is used client-side.)

+
+
+

You can manipulate clientVars in two different ways: +* Return an object. The object will be merged into clientVars via + Object.assign(), so any keys that already exist in clientVars will be + overwritten by the values in the returned object. +* Modify context.clientVars. Beware: Other plugins might also be reading or + manipulating the same context.clientVars object. To avoid race conditions, + you are encouraged to return an object rather than modify + context.clientVars.

+
+
+

If needed, you can access the user’s account information (if authenticated) via +context.socket.client.request.session.user.

+
+
+

Examples:

+
+
+
+
// Using an async function
+exports.clientVars = async (hookName, context) => {
+  const user = context.socket.client.request.session.user || {};
+  return {'accountUsername': user.username || '<unknown>'}
+};
+
+// Using a regular function
+exports.clientVars = (hookName, context, callback) => {
+  const user = context.socket.client.request.session.user || {};
+  return callback({'accountUsername': user.username || '<unknown>'});
+};
+
+
+
+
+

getLineHTMLForExport

+
+

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

+
+
+

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

+
+
+

Context properties:

+
+
+
    +
  • +

    apool: Pool object.

    +
    • +
  • +

    attribLine: Line attributes.

    +
    • +
  • +

    line:

    +
    • +
  • +

    lineContent:

    +
    • +
  • +

    text: Line text.

    +
    • +
  • +

    padId: Writable (not read-only) pad identifier.

    +
    • +
+
+
+

Example:

+
+
+
+
const AttributeMap = require('ep_etherpad-lite/static/js/AttributeMap');
+const Changeset = require('ep_etherpad-lite/static/js/Changeset');
+
+exports.getLineHTMLForExport = async (hookName, context) => {
+  if (!context.attribLine) return;
+  const [op] = Changeset.deserializeOps(context.attribLine);
+  if (op == null) return;
+  const heading = AttributeMap.fromString(op.attribs, context.apool).get('heading');
+  if (!heading) return;
+  context.lineContent = `<${heading}>${context.lineContent}</${heading}>`;
+};
+
+
+
+
+

exportHTMLAdditionalContent

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    padId

    +
    2. +
+
+
+

This hook will allow a plug-in developer to include additional HTML content in +the body of the exported HTML.

+
+
+

Example:

+
+
+
+
exports.exportHTMLAdditionalContent = async (hookName, {padId}) => {
+  return 'I am groot in ' + padId;
+};
+
+
+
+
+

stylesForExport

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    padId - The Pad Id

    +
    2. +
+
+
+

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

+
+
+

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.

+
+
+

An attributes object is passed to the aceAttribClasses hook functions instead of +the usual context object. A hook function can either modify this object directly +or provide an object whose properties will be assigned to the attributes object.

+
+
+

Example:

+
+
+
+
exports.aceAttribClasses = (hookName, attrs, cb) => {
+  return cb([{
+    sub: 'tag:sub',
+  }]);
+};
+
+
+
+
+

exportFileName

+
+

Called from src/node/handler/ExportHandler.js

+
+
+

Things in context:

+
+
+
    +
  1. +

    padId

    +
    2. +
+
+
+

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

    +
    2. +
+
+
+

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

    +
    2. +
+
+
+

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"]]);
+};
+
+
+
+
+

exportEtherpadAdditionalContent

+
+

Called from src/node/utils/ExportEtherpad.js and +src/node/utils/ImportEtherpad.js.

+
+
+

Called when exporting to an .etherpad file or when importing from an +.etherpad file. The hook function should return prefixes for pad-specific +records that should be included in the export/import. On export, all +${prefix}:${padId} and ${prefix}:${padId}:* records are included in the +generated .etherpad file. On import, all ${prefix}:${padId} and +${prefix}:${padId}:* records are loaded into the database.

+
+
+

Context properties: None.

+
+
+

Example:

+
+
+
+
// Add support for exporting comments metadata
+exports.exportEtherpadAdditionalContent = () => ['comments'];
+
+
+
+
+

exportEtherpad

+
+

Called from src/node/utils/ExportEtherpad.js.

+
+
+

Called when exporting to an .etherpad file.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The exported pad’s Pad object.

    +
    • +
  • +

    data: JSONable output object. This is pre-populated with records from core +Etherpad as well as pad-specific records with prefixes from the +exportEtherpadAdditionalContent hook. Registered hook functions can modify +this object (but not replace the object) to perform any desired +transformations to the exported data (such as the inclusion of +plugin-specific records). All registered hook functions are executed +concurrently, so care should be taken to avoid race conditions with other +plugins.

    +
    • +
  • +

    dstPadId: The pad ID that should be used when writing pad-specific records +to data (instead of pad.id). This avoids leaking the writable pad ID +when a user exports a read-only pad. This might be a dummy value; plugins +should not assume that it is either the pad’s real writable ID or its +read-only ID.

    +
    • +
+
+
+
+

importEtherpad

+
+

Called from src/node/utils/ImportEtherpad.js.

+
+
+

Called when importing from an .etherpad file.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: Temporary Pad object containing the pad’s data read from the imported +.etherpad file. The pad.db object is a temporary in-memory database +whose records will be copied to the real database after they are validated +(see the padCheck hook). Registered hook functions MUST NOT use the real +database to access (read or write) pad-specific records; they MUST instead +use pad.db. All registered hook functions are executed concurrently, so +care should be taken to avoid race conditions with other plugins.

    +
    • +
  • +

    data: Raw JSONable object from the .etherpad file. This data must not be +modified.

    +
    • +
  • +

    srcPadId: The pad ID used for the pad-specific information in data.

    +
    • +
+
+
+
+

import

+
+

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

+
+
+

Called when a user submits a document for import, before the document is +converted to HTML. The hook function should return a truthy value if the hook +function elected to convert the document to HTML.

+
+
+

Context properties:

+
+
+
    +
  • +

    destFile: The destination HTML filename.

    +
    • +
  • +

    fileEnding: The lower-cased filename extension from srcFile with leading +period (examples: '.docx', '.html', '.etherpad').

    +
    • +
  • +

    padId: The identifier of the destination pad.

    +
    • +
  • +

    srcFile: The document to convert.

    +
    • +
  • +

    ImportError: Subclass of Error that can be thrown to provide a specific +error message to the user. The constructor’s first argument must be a string +matching one of the known error identifiers.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.import = async (hookName, {fileEnding, ImportError}) => {
+  // Reject all *.etherpad imports with a permission denied message.
+  if (fileEnding === '.etherpad') throw new ImportError('permission');
+};
+
+
+
+
+

userJoin

+
+

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

+
+
+

Called after users have been notified that a new user has joined the pad.

+
+
+

Context properties:

+
+
+
    +
  • +

    authorId: The user’s author identifier.

    +
    • +
  • +

    displayName: The user’s display name.

    +
    • +
  • +

    padId: The real (not read-only) identifier of the pad the user joined. This +MUST NOT be shared with any users that are connected with read-only access.

    +
    • +
  • +

    readOnly: Whether the user only has read-only access.

    +
    • +
  • +

    readOnlyPadId: The read-only identifier of the pad the user joined.

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.userJoin = async (hookName, {authorId, displayName, padId}) => {
+  console.log(`${authorId} (${displayName}) joined pad ${padId});
+};
+
+
+
+
+

userLeave

+
+

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

+
+
+

Called when a user disconnects from a pad. This is useful if you want to perform +certain actions after a pad has been edited.

+
+
+

Context properties:

+
+
+
    +
  • +

    authorId: The user’s author ID.

    +
    • +
  • +

    padId: The pad’s real (not read-only) identifier.

    +
    • +
  • +

    readOnly: If truthy, the user only has read-only access.

    +
    • +
  • +

    readOnlyPadId: The pad’s read-only identifier.

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.userLeave = async (hookName, {author, padId}) => {
+  console.log(`${author} left pad ${padId}`);
+};
+
+
+
+
+

chatNewMessage

+
+

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

+
+
+

Called when a user (or plugin) generates a new chat message, just before it is +saved to the pad and relayed to all connected users.

+
+
+

Context properties:

+
+
+
    +
  • +

    message: The chat message object. Plugins can mutate this object to change +the message text or add custom metadata to control how the message will be +rendered by the chatNewMessage client-side hook. The message’s authorId +property can be trusted (the server overwrites any client-provided author ID +value with the user’s actual author ID before this hook runs).

    +
    • +
  • +

    padId: The pad’s real (not read-only) identifier.

    +
    • +
  • +

    pad: The pad’s Pad object.

    +
    • +
+
+
+
+
+
+

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

+
+
+

The changeset +library +provides tools to create, read, and apply changesets.

+
+
+

Changeset

+
+
+
const Changeset = require('ep_etherpad-lite/static/js/Changeset');
+
+
+
+

A changeset describes the difference between two revisions of a document. When a +user edits a pad, the browser generates and sends a changeset to the server, +which relays it to the other users and saves a copy (so that every past revision +is accessible).

+
+
+

A transmitted changeset looks like this:

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

Attribute Pool

+
+
+
const AttributePool = require('ep_etherpad-lite/static/js/AttributePool');
+
+
+
+

Changesets do not include any attribute key–value pairs. Instead, they use +numeric identifiers that reference attributes kept in an attribute pool. +This attribute interning reduces the transmission overhead of attributes that +are used many times.

+
+
+

There is one attribute pool per pad, and it includes every current and +historical attribute used in the pad.

+
+
+
+

Further Reading

+
+

Detailed information about the changesets & Easysync protocol:

+
+
+ +
+
+
+
+
+

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)

+
+
    +
  • +

    {Object} opts

    +
    • +
  • +

    command - this command fill be fired on the editbar on click

    +
    • +
  • +

    localizationId - will be set as data-l10-id

    +
    • +
  • +

    class - here you can add additional classes to the button

    +
    • +
+
+
+

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)

+
+
    +
  • +

    {Object} opts

    +
    • +
  • +

    id - id of the menu item

    +
    • +
  • +

    selectId - id of the select element

    +
    • +
  • +

    command - this command fill be fired on the editbar on change

    +
    • +
+
+
+

Returns: {SelectButton}

+
+
+
+

SelectButton.addOption(value, text, attributes)

+
+
    +
  • +

    {String} value - The value of this option

    +
    • +
  • +

    {String} text - the label text used for this option

    +
    • +
  • +

    {Object} attributes - any additional html attributes go here (e.g. data-l10n-id)

    +
    • +
+
+
+
+

registerButton(name, item)

+
+
    +
  • +

    {String} name - used to reference the item in the toolbar config in settings.json

    +
    • +
  • +

    {Button|SelectButton} item - the button to add

    +
    • +
+
+
+
+
+
+

Editbar

+
+
+

src/static/js/pad_editbar.js

+
+
+

isEnabled()

+ +
+
+

disable()

+ +
+
+

toggleDropDown(dropdown)

+
+

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

+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/api/changeset_library.html b/public/doc/v2.2.7/api/changeset_library.html new file mode 100644 index 0000000..38f3946 --- /dev/null +++ b/public/doc/v2.2.7/api/changeset_library.html @@ -0,0 +1,513 @@ + + + + + + + +Changeset Library + + + + + +
+
+

Changeset Library

+
+
+

The changeset +library +provides tools to create, read, and apply changesets.

+
+
+

Changeset

+
+
+
const Changeset = require('ep_etherpad-lite/static/js/Changeset');
+
+
+
+

A changeset describes the difference between two revisions of a document. When a +user edits a pad, the browser generates and sends a changeset to the server, +which relays it to the other users and saves a copy (so that every past revision +is accessible).

+
+
+

A transmitted changeset looks like this:

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

Attribute Pool

+
+
+
const AttributePool = require('ep_etherpad-lite/static/js/AttributePool');
+
+
+
+

Changesets do not include any attribute key–value pairs. Instead, they use +numeric identifiers that reference attributes kept in an attribute pool. +This attribute interning reduces the transmission overhead of attributes that +are used many times.

+
+
+

There is one attribute pool per pad, and it includes every current and +historical attribute used in the pad.

+
+
+
+

Further Reading

+
+

Detailed information about the changesets & Easysync protocol:

+
+
+ +
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/api/editbar.html b/public/doc/v2.2.7/api/editbar.html new file mode 100644 index 0000000..92a2e38 --- /dev/null +++ b/public/doc/v2.2.7/api/editbar.html @@ -0,0 +1,503 @@ + + + + + + + +Editbar + + + + + +
+
+

Editbar

+
+
+

src/static/js/pad_editbar.js

+
+
+

isEnabled()

+ +
+
+

disable()

+ +
+
+

toggleDropDown(dropdown)

+
+

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

+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/api/editorInfo.html b/public/doc/v2.2.7/api/editorInfo.html new file mode 100644 index 0000000..a47cdb9 --- /dev/null +++ b/public/doc/v2.2.7/api/editorInfo.html @@ -0,0 +1,688 @@ + + + + + + + +editorInfo + + + + + +
+
+

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_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_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(?)

+ +
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/api/embed_parameters.html b/public/doc/v2.2.7/api/embed_parameters.html new file mode 100644 index 0000000..65f5ae9 --- /dev/null +++ b/public/doc/v2.2.7/api/embed_parameters.html @@ -0,0 +1,621 @@ + + + + + + + +Embed parameters + + + + + +
+
+

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 and will auto-focus on Line 4.

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

showLineNumbers

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true

+
+
+
+

showControls

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true

+
+
+
+

showChat

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true

+
+
+
+

useMonospaceFont

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: false

+
+
+
+

userName

+
+
    +
  • +

    String

    +
    • +
+
+
+

Default: "unnamed"

+
+
+

Example: userName=Etherpad%20User

+
+
+
+

userColor

+
+
    +
  • +

    String (css hex color value)

    +
    • +
+
+
+

Default: randomly chosen by pad server

+
+
+

Example: userColor=%23ff9900

+
+
+
+

noColors

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: false

+
+
+
+

alwaysShowChat

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: false

+
+
+
+

lang

+
+
    +
  • +

    String

    +
    • +
+
+
+

Default: en

+
+
+

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

+
+
+
+

rtl

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true +Displays pad text from right to left.

+
+
+
+

#L

+
+
    +
  • +

    Int

    +
    • +
+
+
+

Default: 0 +Focuses pad at specific line number and places caret at beginning of this line +Special note: Is not a URL parameter but instead of a Hash value

+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/api/hooks_client-side.html b/public/doc/v2.2.7/api/hooks_client-side.html new file mode 100644 index 0000000..5a8336e --- /dev/null +++ b/public/doc/v2.2.7/api/hooks_client-side.html @@ -0,0 +1,1384 @@ + + + + + + + +Client-side hooks + + + + + +
+
+

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. +
  2. +

    cls - The class of the current block element (useful for styling)

    +
    3. +
+
+
+

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. +
  2. +

    cls - The class of the current block element (useful for styling)

    +
    3. +
+
+
+

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. +
  2. +

    cls - The class of the current element (useful for styling)

    +
    3. +
+
+
+

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

    +
    2. +
+
+
+

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. +
  2. +

    key - the current attribute being processed

    +
    3. +
  3. +

    value - the value of the attribute being processed

    +
    4. +
+
+
+

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. +
  2. +

    browser - an object indicating which browser is accessing the page

    +
    3. +
+
+
+

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

    +
    2. +
+
+
+

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. +
  2. +

    editorInfo - information about the user who is making the change

    +
    3. +
  3. +

    rep - information about where the change is being made

    +
    4. +
  4. +

    documentAttributeManager - information about attributes in the document (this +is a mystery to me)

    +
    5. +
+
+
+

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. +
  2. +

    rep - information about where the user’s cursor is

    +
    3. +
  3. +

    documentAttributeManager - some kind of magic

    +
    4. +
+
+
+

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. +
  2. +

    clientVars - Object containing client-side configuration such as author ID +and plugin settings. Your plugin can manipulate this object via the +clientVars server-side hook.

    +
    3. +
  3. +

    pad - the pad object of the current pad.

    +
    4. +
+
+
+
+

postToolbarInit

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    ace - the ace object that is applied to this editor.

    +
    2. +
  2. +

    toolbar - Editbar instance. See below for the Editbar documentation.

    +
    3. +
+
+
+

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.

+
+
+
+

goToRevisionEvent

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    rev - The newRevision

    +
    2. +
+
+
+

This hook gets fired both on timeslider load (as timeslider shows a new +revision) and when the new revision is showed to a user. There doesn’t appear to +be any example available of this particular hook being used.

+
+
+
+

userJoinOrUpdate

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    info - the user information

    +
    2. +
+
+
+

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

+
+
+

This hook runs on the client side whenever a chat message is received from the +server. It can be used to create different notifications for chat messages. Hook +functions can modify the author, authorName, duration, rendered, +sticky, text, and timeStr context properties to change how the message is +processed. The text and timeStr properties may contain HTML and come +pre-sanitized; plugins should be careful to sanitize any added user input to +avoid introducing an XSS vulnerability.

+
+
+

Context properties:

+
+
+
    +
  • +

    authorName: The display name of the user that wrote the message.

    +
    • +
  • +

    author: The author ID of the user that wrote the message.

    +
    • +
  • +

    text: Sanitized message HTML, with URLs wrapped like <a +href="url">url</a>. (Note that message.text is not sanitized or processed +in any way.)

    +
    • +
  • +

    message: The raw message object as received from the server, except with +time correction and a default authorId property if missing. Plugins must not +modify this object. Warning: Unlike text, message.text is not +pre-sanitized or processed in any way.

    +
    • +
  • +

    rendered - Used to override the default message rendering. Initially set to +null. If the hook function sets this to a DOM element object or a jQuery +object, then that object will be used as the rendered message UI. Otherwise, +if this is set to null, then Etherpad will render a default UI for the +message using the other context properties.

    +
    • +
  • +

    sticky (boolean): Whether the gritter notification should fade out on its +own or just sit there until manually closed.

    +
    • +
  • +

    timestamp: When the chat message was sent (milliseconds since epoch), +corrected using the difference between the local clock and the server’s clock.

    +
    • +
  • +

    timeStr: The message timestamp as a formatted string.

    +
    • +
  • +

    duration: How long (in milliseconds) to display the gritter notification (0 +to disable).

    +
    • +
+
+
+
+

chatSendMessage

+
+

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

+
+
+

This hook runs on the client side whenever the user sends a new chat message. +Plugins can mutate the message object to change the message text or add metadata +to control how the message will be rendered by the chatNewMessage hook.

+
+
+

Context properties:

+
+
+
    +
  • +

    message: The message object that will be sent to the Etherpad server.

    +
    • +
+
+
+
+

collectContentPre

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    cc - the contentcollector object

    +
    2. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    styl - the style applied to the node (probably CSS) — Note the typo

    +
    5. +
  5. +

    cls - the HTML class string of the node

    +
    6. +
+
+
+

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. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    style - the style applied to the node (probably CSS)

    +
    5. +
  5. +

    cls - the HTML class string of the node

    +
    6. +
  6. +

    node - the node being modified

    +
    7. +
+
+
+

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. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    style - the style applied to the node (probably CSS)

    +
    5. +
  5. +

    cls - the HTML class string of the node

    +
    6. +
+
+
+

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)

    +
    2. +
+
+
+

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. +
  2. +

    editorInfo - information about the user who is making the change

    +
    3. +
  3. +

    rep - information about where the change is being made

    +
    4. +
  4. +

    root - the span element of the current line

    +
    5. +
  5. +

    point - the starting/ending element where the cursor highlights

    +
    6. +
  6. +

    documentAttributeManager - information about attributes in the document

    +
    7. +
+
+
+

This hook is provided to allow a plugin to turn DOM node selection into

+
+
+
+

aceKeyEvent

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    callstack - a bunch of information about the current action

    +
    2. +
  2. +

    editorInfo - information about the user who is making the change

    +
    3. +
  3. +

    rep - information about where the change is being made

    +
    4. +
  4. +

    documentAttributeManager - information about attributes in the document

    +
    5. +
  5. +

    evt - the fired event

    +
    6. +
+
+
+

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. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    text - the text for that line

    +
    5. +
+
+
+

This hook allows you to validate/manipulate the text before it’s sent to the +server side. To change the text, either:

+
+
+
    +
  • +

    Set the text context property to the desired value and return undefined.

    +
    • +
  • +

    (Deprecated) Return a string. If a hook function changes the text context +property, the return value is ignored. If no hook function changes text but +multiple hook functions return a string, the first one wins.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.collectContentLineText = (hookName, context) => {
+  context.text = tweakText(context.text);
+};
+
+
+
+
+

collectContentLineBreak

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    cc - the contentcollector object

    +
    2. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
+
+
+

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. +
  2. +

    text - the line text

    +
    3. +
  3. +

    class - line class

    +
    4. +
+
+
+

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. +
  2. +

    outerDynamicCSS - css manager for outer ace

    +
    3. +
  3. +

    parentDynamicCSS - css manager for parent document

    +
    4. +
  4. +

    info - author style info

    +
    5. +
  5. +

    author - author info

    +
    6. +
  6. +

    authorSelector - css selector for author span in inner ace

    +
    7. +
+
+
+

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. +
  2. +

    documentAttributeManager - information about attributes in the document

    +
    3. +
+
+
+

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.

+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/api/hooks_overview.html b/public/doc/v2.2.7/api/hooks_overview.html new file mode 100644 index 0000000..5dbcf14 --- /dev/null +++ b/public/doc/v2.2.7/api/hooks_overview.html @@ -0,0 +1,630 @@ + + + + + + + +Hooks + + + + + +
+
+

Hooks

+
+
+

A hook function is registered with a hook via the plugin’s ep.json file. See +the Plugins section for details. A hook may have many registered functions from +different plugins.

+
+
+

Some hooks call their registered functions one at a time until one of them +returns a value. Others always call all of their registered functions and +combine the results (if applicable).

+
+
+

Registered hook functions

+
+

Note: The documentation in this section applies to every hook unless the +hook-specific documentation says otherwise.

+
+
+

Arguments

+
+

Hook functions are called with three arguments:

+
+
+
    +
  1. +

    hookName - The name of the hook being invoked.

    +
    2. +
  2. +

    context - An object with some relevant information about the context of the +call. See the hook-specific documentation for details.

    +
    3. +
  3. +

    cb - For asynchronous operations this callback can be called to signal +completion and optionally provide a return value. The callback takes a single +argument, the meaning of which depends on the hook (see the "Return values" +section for general information that applies to most hooks). This callback +always returns undefined.

    +
    4. +
+
+
+
+

Expected behavior

+
+

The presence of a callback parameter suggests that every hook function can run +asynchronously. While that is the eventual goal, there are some legacy hooks +that expect their hook functions to provide a value synchronously. For such +hooks, the hook functions must do one of the following:

+
+
+
    +
  • +

    Call the callback with a non-Promise value (undefined is acceptable) and +return undefined, in that order.

    +
    • +
  • +

    Return a non-Promise value other than undefined (null is acceptable) and +never call the callback. Note that async functions always return a +Promise, so they must never be used for synchronous hooks.

    +
    • +
  • +

    Only have two parameters (hookName and context) and return any non-Promise +value (undefined is acceptable).

    +
    • +
+
+
+

For hooks that permit asynchronous behavior, the hook functions must do one or +more of the following:

+
+
+
    +
  • +

    Return undefined and call the callback, in either order.

    +
    • +
  • +

    Return something other than undefined (null is acceptable) and never call +the callback. Note that async functions always return a Promise, so they +must never call the callback.

    +
    • +
  • +

    Only have two parameters (hookName and context).

    +
    • +
+
+
+

Note that the acceptable behaviors for asynchronous hook functions is a superset +of the acceptable behaviors for synchronous hook functions.

+
+
+ + + + + +
+
Warning
+		 +The number of parameters is determined by examining +Function.length, +which does not count default parameters +or "rest" parameters. +To avoid problems, do not use default or rest parameters when defining hook +functions. +
+
+
+
+

Return values

+
+

A hook function can provide a value to Etherpad in one of the following ways:

+
+
+
    +
  • +

    Pass the desired value as the first argument to the callback.

    +
    • +
  • +

    Return the desired value directly. The value must not be undefined unless +the hook function only has two parameters. (Hook functions with three +parameters that want to provide undefined should instead use the callback.)

    +
    • +
  • +

    For hooks that permit asynchronous behavior, return a Promise that resolves to +the desired value.

    +
    • +
  • +

    For hooks that permit asynchronous behavior, pass a Promise that resolves to +the desired value as the first argument to the callback.

    +
    • +
+
+
+

Examples:

+
+
+
+
exports.exampleOne = (hookName, context, callback) => {
+  return 'valueOne';
+};
+
+exports.exampleTwo = (hookName, context, callback) => {
+  callback('valueTwo');
+  return;
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleThree = (hookName, context, callback) => {
+  return new Promise('valueThree');
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleFour = (hookName, context, callback) => {
+  callback(new Promise('valueFour'));
+  return;
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleFive = async (hookName, context) => {
+  // Note that this function is async, so it actually returns a Promise that
+  // is resolved to 'valueFive'.
+  return 'valueFive';
+};
+
+
+
+

Etherpad collects the values provided by the hook functions into an array, +filters out all undefined values, then flattens the array one level. +Flattening one level makes it possible for a hook function to behave as if it +were multiple separate hook functions.

+
+
+

For example: Suppose a hook has eight registered functions that return the +following values: 1, [2], ['3a', '3b'] [[4]], undefined, +[undefined], [], and null. The value returned to the caller of the hook is +[1, 2, '3a', '3b', [4], undefined, null].

+
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/api/hooks_server-side.html b/public/doc/v2.2.7/api/hooks_server-side.html new file mode 100644 index 0000000..2cf9928 --- /dev/null +++ b/public/doc/v2.2.7/api/hooks_server-side.html @@ -0,0 +1,2336 @@ + + + + + + + +Server-side hooks + + + + + +
+
+

Server-side hooks

+
+
+

These hooks are called on server-side.

+
+
+

loadSettings

+
+

Called from: src/node/server.ts

+
+
+

Things in context:

+
+
+
    +
  1. +

    settings - the settings object

    +
    2. +
+
+
+

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

+
+
+
+

shutdown

+
+

Called from: src/node/server.ts

+
+
+

Things in context: None

+
+
+

This hook runs before shutdown. Use it to stop timers, close sockets and files, +flush buffers, etc. The database is not available while this hook is running. +The shutdown function must not block for long because there is a short timeout +before the process is forcibly terminated.

+
+
+

The shutdown function must return a Promise, which must resolve to undefined. +Returning callback(value) will return a Promise that is resolved to value.

+
+
+

Example:

+
+
+
+
// using an async function
+exports.shutdown = async (hookName, context) => {
+  await flushBuffers();
+};
+
+
+
+
+

pluginUninstall

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    plugin_name - self-explanatory

    +
    2. +
+
+
+

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

    +
    2. +
+
+
+

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

+
+
+

Run during startup after the named plugin is initialized.

+
+
+

Context properties:

+
+
+
    +
  • +

    logger: An object with the following console-like methods: debug, +info, log, warn, error.

    +
    • +
+
+
+
+

expressPreSession

+
+

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

+
+
+

Called during server startup just before the +express-session middleware is +added to the Express Application object. Use this hook to add route handlers or +middleware that executes before express-session state is created and +authentication is performed. This is useful for creating public endpoints that +don’t spam the database with new express-session records or trigger +authentication.

+
+
+

WARNING: All handlers registered during this hook run before the built-in +authentication checks, so any handled endpoints will be public unless the +handler itself authenticates the user.

+
+
+

Context properties:

+
+
+ +
+
+

Example:

+
+
+
+
exports.expressPreSession = async (hookName, {app}) => {
+  app.get('/hello-world', (req, res) => res.send('hello world'));
+};
+
+
+
+
+

expressConfigure

+
+

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

+
+
+

Called during server startup just after the +express-session middleware is +added to the Express Application object. Use this hook to add route handlers or +middleware that executes after express-session state is created and +authentication is performed.

+
+
+

Context properties:

+
+
+ +
+
+
+

expressCreateServer

+
+

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

+
+
+

Identical to the expressConfigure hook (the two run in parallel with each +other) except this hook’s context includes the HTTP Server object.

+
+
+

Context properties:

+
+
+ +
+
+
+

expressCloseServer

+
+

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

+
+
+

Things in context: Nothing

+
+
+

This hook is called when the HTTP server is closing, which happens during +shutdown (see the shutdown hook) and when the server restarts (e.g., when a +plugin is installed via the /admin/plugins page). The HTTP server may or may +not already be closed when this hook executes.

+
+
+

Example:

+
+
+
+
exports.expressCloseServer = async () => {
+  await doSomeCleanup();
+};
+
+
+
+
+

eejsBlock_`<name>`

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    content - the content of the block

    +
    2. +
+
+
+

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:

+
+
+
    +
  • +

    htmlHead - after <html> and immediately before the title tag

    +
    • +
  • +

    styles - the style `<link>`s

    +
    • +
  • +

    body - the contents of the body tag

    +
    • +
  • +

    editbarMenuLeft - the left tool bar (consider using the toolbar controller instead of manually adding html here)

    +
    • +
  • +

    editbarMenuRight - right tool bar

    +
    • +
  • +

    afterEditbar - allows you to add stuff immediately after the toolbar

    +
    • +
  • +

    userlist - the contents of the userlist dropdown

    +
    • +
  • +

    loading - the initial loading message

    +
    • +
  • +

    mySettings - the left column of the settings dropdown ("My view"); intended for adding checkboxes only

    +
    • +
  • +

    mySettings.dropdowns - add your dropdown settings here

    +
    • +
  • +

    globalSettings - the right column of the settings dropdown ("Global view")

    +
    • +
  • +

    importColumn - import form

    +
    • +
  • +

    exportColumn - export form

    +
    • +
  • +

    modals - Contains all connectivity messages

    +
    • +
  • +

    embedPopup - the embed dropdown

    +
    • +
  • +

    scripts - Add your script tags here, if you really have to (consider use client-side hooks instead)

    +
    • +
+
+
+

timeslider.html blocks:

+
+
+
    +
  • +

    timesliderStyles

    +
    • +
  • +

    timesliderScripts

    +
    • +
  • +

    timesliderBody

    +
    • +
  • +

    timesliderTop

    +
    • +
  • +

    timesliderEditbarRight

    +
    • +
  • +

    modals

    +
    • +
+
+
+

index.html blocks:

+
+
+
    +
  • +

    indexCustomStyles - contains the index.css <link> tag, allows you to add your own or to customize the one provided by the active skin

    +
    • +
  • +

    indexWrapper - contains the form for creating new pads

    +
    • +
  • +

    indexCustomScripts - contains the index.js <script> tag, allows you to add your own or to customize the one provided by the active skin

    +
    • +
+
+
+
+

padInitToolbar

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    toolbar - the toolbar controller that will render the toolbar eventually

    +
    2. +
+
+
+

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 real ID (never the read-only ID) of the pad the user wants to +access

    +
    2. +
  2. +

    token - the token of the author

    +
    3. +
  3. +

    sessionCookie - the session the use has

    +
    4. +
+
+
+

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

+
+
+
+

getAuthorId

+
+

Called from src/node/db/AuthorManager.js

+
+
+

Called when looking up (or creating) the author ID for a user, except for author +IDs obtained via the HTTP API. Registered hook functions are called until one +returns a non-undefined value. If a truthy value is returned by a hook +function, it is used as the user’s author ID. Otherwise, the value of the +dbKey context property is used to look up the author ID. If there is no such +author ID at that key, a new author ID is generated and associated with that +key.

+
+
+

Context properties:

+
+
+
    +
  • +

    dbKey: Database key to use when looking up the user’s author ID if no hook +function returns an author ID. This is initialized to the user-supplied token +value (see the token context property), but hook functions can modify this +to control how author IDs are allocated to users. If no author ID is +associated with this database key, a new author ID will be randomly generated +and associated with the key. For security reasons, if this is modified it +should be modified to not look like a valid token (see the token context +property) unless the plugin intentionally wants the user to be able to +impersonate another user.

    +
    • +
  • +

    token: The user-supplied token, or nullish for an anonymous user. Tokens are +secret values that must not be disclosed to others. If non-null, the token is +guaranteed to be a string with the form t.<base64url> where <base64url> is +any valid non-empty base64url string (RFC 4648 section 5 with padding). +Example: t.twim3X2_KGiRj8cJ-3602g==.

    +
    • +
  • +

    user: If the user has authenticated, this is an object from settings.users +(or similar from an authentication plugin). Etherpad core and all good +authentication plugins set the username property of this object to a string +that uniquely identifies the authenticated user. This object is nullish if the +user has not authenticated.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.getAuthorId = async (hookName, context) => {
+  const {username} = context.user || {};
+  // If the user has not authenticated, or has "authenticated" as the guest
+  // user, do the default behavior (try another plugin if any, falling through
+  // to using the token as the database key).
+  if (!username || username === 'guest') return;
+  // The user is authenticated and has a username. Give the user a stable author
+  // ID so that they appear to be the same author even after clearing cookies or
+  // accessing the pad from another device. Note that this string is guaranteed
+  // to never have the form of a valid token; without that guarantee an
+  // unauthenticated user might be able to impersonate an authenticated user.
+  context.dbKey = `username=${username}`;
+  // Return a falsy but non-undefined value to stop Etherpad from calling any
+  // more getAuthorId hook functions and look up the author ID using the
+  // username-derived database key.
+  return '';
+};
+
+
+
+
+

padCreate

+
+

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

+
+
+

Called when a new pad is created.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object.

    +
    • +
  • +

    authorId: The ID of the author who created the pad.

    +
    • +
  • +

    author (deprecated): Synonym of authorId.

    +
    • +
+
+
+
+

padDefaultContent

+
+

Called from src/node/db/Pad.js

+
+
+

Called to obtain a pad’s initial content, unless the pad is being created with +specific content. The return value is ignored; to change the content, modify the +content context property.

+
+
+

This hook is run asynchronously. All registered hook functions are run +concurrently (via Promise.all()), so be careful to avoid race conditions when +reading and modifying the context properties.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The newly created Pad object.

    +
    • +
  • +

    authorId: The author ID of the user that is creating the pad.

    +
    • +
  • +

    type: String identifying the content type. Currently this is 'text' and +must not be changed. Future versions of Etherpad may add support for HTML, +jsdom objects, or other formats, so plugins must assert that this matches a +supported content type before reading content.

    +
    • +
  • +

    content: The pad’s initial content. Change this property to change the pad’s +initial content. If the content type is changed, the type property must also +be updated to match. Plugins must check the value of the type property +before reading this value.

    +
    • +
+
+
+
+

padLoad

+
+

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

+
+
+

Called when a pad is loaded, including after new pad creation.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object.

    +
    • +
+
+
+
+

padUpdate

+
+

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

+
+
+

Called when an existing pad is updated.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object.

    +
    • +
  • +

    authorId: The ID of the author who updated the pad.

    +
    • +
  • +

    author (deprecated): Synonym of authorId.

    +
    • +
  • +

    revs: The index of the new revision.

    +
    • +
  • +

    changeset: The changeset of this revision (see padUpdate).

    +
    • +
+
+
+
+

padCopy

+
+

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

+
+
+

Called when a pad is copied so that plugins can copy plugin-specific database +records or perform some other plugin-specific initialization.

+
+
+

Order of events when a pad is copied:

+
+
+
    +
  1. +

    Destination pad is deleted if it exists and overwrite is permitted. This +causes the padRemove hook to run.

    +
    2. +
  2. +

    Pad-specific database records are copied in the database, except for +records with plugin-specific database keys.

    +
    3. +
  3. +

    A new Pad object is created for the destination pad. This causes the +padLoad hook to run.

    +
    4. +
  4. +

    This hook runs.

    +
    5. +
+
+
+

Context properties:

+
+
+
    +
  • +

    srcPad: The source Pad object.

    +
    • +
  • +

    dstPad: The destination Pad object.

    +
    • +
+
+
+

Usage examples:

+
+
+ +
+
+
+

padRemove

+
+

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

+
+
+

Called when an existing pad is removed/deleted. Plugins should use this to clean +up any plugin-specific pad records from the database.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: Pad object for the pad that is being deleted.

    +
    • +
+
+
+

Usage examples:

+
+
+ +
+
+
+

padCheck

+
+

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

+
+
+

Called when a consistency check is run on a pad, after the core checks have +completed successfully. An exception should be thrown if the pad is faulty in +some way.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object that is being checked.

    +
    • +
+
+
+
+

socketio

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    app - the application object

    +
    2. +
  2. +

    io - the socketio object

    +
    3. +
  3. +

    server - the http server object

    +
    4. +
+
+
+

I have no idea what this is useful for, someone else will have to add this description.

+
+
+
+

preAuthorize

+
+

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

+
+
+

Called for each HTTP request before any authentication checks are performed. The +registered preAuthorize hook functions are called one at a time until one +explicitly grants or denies the request by returning true or false, +respectively. If none of the hook functions return anything, the access decision +is deferred to the normal authentication and authorization checks.

+
+
+

Example uses:

+
+
+
    +
  • +

    Always grant access to static content.

    +
    • +
  • +

    Process an OAuth callback.

    +
    • +
  • +

    Drop requests from IP addresses that have failed N authentication checks +within the past X minutes.

    +
    • +
+
+
+

Return values:

+
+
+
    +
  • +

    undefined (or []) defers the access decision to the next registered +preAuthorize hook function, or to the normal authentication and +authorization checks if no more preAuthorize hook functions remain.

    +
    • +
  • +

    true (or [true]) immediately grants access to the requested resource, +unless the request is for an /admin page in which case it is treated the +same as returning undefined. (This prevents buggy plugins from accidentally +granting admin access to the general public.)

    +
    • +
  • +

    false (or [false]) immediately denies the request. The preAuthnFailure +hook will be called to handle the failure.

    +
    • +
+
+
+

Context properties:

+
+
+
    +
  • +

    req: The Express Request object.

    +
    • +
  • +

    res: The Express Response +object.

    +
    • +
  • +

    next: Callback to immediately hand off handling to the next Express +middleware/handler, or to the next matching route if 'route' is passed as +the first argument. Do not call this unless you understand the consequences.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.preAuthorize = async (hookName, {req}) => {
+  if (await ipAddressIsFirewalled(req)) return false;
+  if (requestIsForStaticContent(req)) return true;
+  if (requestIsForOAuthCallback(req)) return true;
+  // Defer the decision to the next step by returning undefined.
+};
+
+
+
+
+

authorize

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
  3. +

    next - ?

    +
    4. +
  4. +

    resource - the path being accessed

    +
    5. +
+
+
+

This hook is called to handle authorization. It is especially useful for +controlling access to specific paths.

+
+
+

A plugin’s authorize function is only called if all of the following are true:

+
+
+
    +
  • +

    The request is not for static content or an API endpoint. (Requests for static +content and API endpoints are always authorized, even if unauthenticated.)

    +
    • +
  • +

    The requireAuthentication and requireAuthorization settings are both true.

    +
    • +
  • +

    The user has already successfully authenticated.

    +
    • +
  • +

    The user is not an admin (admin users are always authorized).

    +
    • +
  • +

    The path being accessed is not an /admin path (/admin paths can only be +accessed by admin users, and admin users are always authorized).

    +
    • +
  • +

    An authorize function from a different plugin has not already caused +authorization to pass or fail.

    +
    • +
+
+
+

Note that the authorize hook cannot grant access to /admin pages. If admin +access is desired, the is_admin user setting must be set to true. This can be +set in the settings file or by the authenticate hook.

+
+
+

You can pass the following values to the provided callback:

+
+
+
    +
  • +

    [true] or ['create'] will grant access to modify or create the pad if the +request is for a pad, otherwise access is simply granted. Access to a pad will +be downgraded to modify-only if settings.editOnly is true or the user’s +canCreate setting is set to false, and downgraded to read-only if the +user’s readOnly setting is true.

    +
    • +
  • +

    ['modify'] will grant access to modify but not create the pad if the request +is for a pad, otherwise access is simply granted. Access to a pad will be +downgraded to read-only if the user’s readOnly setting is true.

    +
    • +
  • +

    ['readOnly'] will grant read-only access.

    +
    • +
  • +

    [false] will deny access.

    +
    • +
  • +

    [] or undefined will defer the authorization decision to the next +authorization plugin (if any, otherwise deny).

    +
    • +
+
+
+

Example:

+
+
+
+
exports.authorize = (hookName, context, cb) => {
+  const user = context.req.session.user;
+  const path = context.req.path;  // or context.resource
+  if (isExplicitlyProhibited(user, path)) return cb([false]);
+  if (isExplicitlyAllowed(user, path)) return cb([true]);
+  return cb([]);  // Let the next authorization plugin decide
+};
+
+
+
+
+

authenticate

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
  3. +

    users - the users object from settings.json (possibly modified by plugins)

    +
    4. +
  4. +

    next - ?

    +
    5. +
  5. +

    username - the username used (optional)

    +
    6. +
  6. +

    password - the password used (optional)

    +
    7. +
+
+
+

This hook is called to handle authentication.

+
+
+

Plugins that supply an authenticate function should probably also supply an +authnFailure function unless falling back to HTTP basic authentication is +appropriate upon authentication failure.

+
+
+

This hook is only called if either the requireAuthentication setting is true +or the request is for an /admin page.

+
+
+

Calling the provided callback with [true] or [false] will cause +authentication to succeed or fail, respectively. Calling the callback with [] +or undefined will defer the authentication decision to the next authentication +plugin (if any, otherwise fall back to HTTP basic authentication).

+
+
+

If you wish to provide a mix of restricted and anonymous access (e.g., some pads +are private, others are public), you can "authenticate" (as a guest account) +users that have not yet logged in, and rely on other hooks (e.g., authorize, +onAccessCheck, handleMessageSecurity) to authorize specific privileged actions.

+
+
+

If authentication is successful, the authenticate function MUST set +context.req.session.user to the user’s settings object. The username +property of this object should be set to the user’s username. The settings +object should come from global settings (context.users[username]).

+
+
+

Example:

+
+
+
+
exports.authenticate = (hook_name, context, cb) => {
+  if (notApplicableToThisPlugin(context)) {
+    return cb([]);  // Let the next authentication plugin decide
+  }
+  const username = authenticate(context);
+  if (!username) {
+    console.warn(`ep_myplugin.authenticate: Failed authentication from IP ${context.req.ip}`);
+    return cb([false]);
+  }
+  console.info(`ep_myplugin.authenticate: Successful authentication from IP ${context.req.ip} for user ${username}`);
+  const users = context.users;
+  if (!(username in users)) users[username] = {};
+  users[username].username = username;
+  context.req.session.user = users[username];
+  return cb([true]);
+};
+
+
+
+
+

authFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
  3. +

    next - ?

    +
    4. +
+
+
+

DEPRECATED: Use authnFailure or authzFailure instead.

+
+
+

This hook is called to handle an authentication or authorization failure.

+
+
+

Plugins that supply an authenticate function should probably also supply an +authnFailure function unless falling back to HTTP basic authentication is +appropriate upon authentication failure.

+
+
+

A plugin’s authFailure function is only called if all of the following are true:

+
+
+
    +
  • +

    There was an authentication or authorization failure.

    +
    • +
  • +

    The failure was not already handled by an authFailure function from another +plugin.

    +
    • +
  • +

    For authentication failures: The failure was not already handled by the +authnFailure hook.

    +
    • +
  • +

    For authorization failures: The failure was not already handled by the +authzFailure hook.

    +
    • +
+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to the next authFailure plugin (if +any, otherwise fall back to HTTP basic authentication for an authentication +failure or a generic 403 page for an authorization failure).

+
+
+

Example:

+
+
+
+
exports.authFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) {
+    return cb([]);  // Let the next plugin handle the error
+  }
+  context.res.redirect(makeLoginURL(context.req));
+  return cb([true]);
+};
+
+
+
+
+

preAuthzFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
+
+
+

This hook is called to handle a pre-authentication authorization failure.

+
+
+

A plugin’s preAuthzFailure function is only called if the pre-authentication +authorization failure was not already handled by a preAuthzFailure function from +another plugin.

+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to a preAuthzFailure function from +another plugin (if any, otherwise fall back to a generic 403 error page).

+
+
+

Example:

+
+
+
+
exports.preAuthzFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) return cb([]);
+  context.res.status(403).send(renderFancy403Page(context.req));
+  return cb([true]);
+};
+
+
+
+
+

authnFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
+
+
+

This hook is called to handle an authentication failure.

+
+
+

Plugins that supply an authenticate function should probably also supply an +authnFailure function unless falling back to HTTP basic authentication is +appropriate upon authentication failure.

+
+
+

A plugin’s authnFailure function is only called if the authentication failure +was not already handled by an authnFailure function from another plugin.

+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to an authnFailure function from +another plugin (if any, otherwise fall back to the deprecated authFailure hook).

+
+
+

Example:

+
+
+
+
exports.authnFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) return cb([]);
+  context.res.redirect(makeLoginURL(context.req));
+  return cb([true]);
+};
+
+
+
+
+

authzFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
+
+
+

This hook is called to handle a post-authentication authorization failure.

+
+
+

A plugin’s authzFailure function is only called if the authorization failure was +not already handled by an authzFailure function from another plugin.

+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to an authzFailure function from +another plugin (if any, otherwise fall back to the deprecated authFailure hook).

+
+
+

Example:

+
+
+
+
exports.authzFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) return cb([]);
+  if (needsPremiumAccount(context.req) && !context.req.session.user.premium) {
+    context.res.status(200).send(makeUpgradeToPremiumAccountPage(context.req));
+    return cb([true]);
+  }
+  // Use the generic 403 forbidden response.
+  return cb([]);
+};
+
+
+
+
+

handleMessage

+
+

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

+
+
+

This hook allows plugins to drop or modify incoming socket.io messages from +clients, before Etherpad processes them. If any hook function returns null +then the message will not be subject to further processing.

+
+
+

Context properties:

+
+
+
    +
  • +

    message: The message being handled.

    +
    • +
  • +

    sessionInfo: Object describing the socket.io session with the following +properties:

    +
    • +
  • +

    authorId: The user’s author ID.

    +
    • +
  • +

    padId: The real (not read-only) ID of the pad.

    +
    • +
  • +

    readOnly: Whether the client has read-only access (true) or read/write +access (false).

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
  • +

    client: (Deprecated; use socket instead.) Synonym of socket.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.handleMessage = async (hookName, {message, socket}) => {
+  if (message.type === 'USERINFO_UPDATE') {
+    // Force the display name to the name associated with the account.
+    const user = socket.client.request.session.user || {};
+    if (user.name) message.data.userInfo.name = user.name;
+  }
+};
+
+
+
+
+

handleMessageSecurity

+
+

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

+
+
+

Called for each incoming message from a client. Allows plugins to grant +temporary write access to a pad.

+
+
+

Supported return values:

+
+
+
    +
  • +

    undefined: No change in access status.

    +
    • +
  • +

    'permitOnce': Override the user’s read-only access for the current +COLLABROOM message only. Has no effect if the current message is not a +COLLABROOM message, or if the user already has write access to the pad.

    +
    • +
  • +

    true: (Deprecated; return 'permitOnce' instead.) Override the user’s +read-only access for all COLLABROOM messages from the same socket.io +connection (including the current message, if applicable) until the client’s +next CLIENT_READY message. Has no effect if the user already has write +access to the pad. Read-only access is reset after each CLIENT_READY +message, so returning true has no effect for CLIENT_READY messages.

    +
    • +
+
+
+

Context properties:

+
+
+
    +
  • +

    message: The message being handled.

    +
    • +
  • +

    sessionInfo: Object describing the socket.io connection with the following +properties:

    +
    • +
  • +

    authorId: The user’s author ID.

    +
    • +
  • +

    padId: The real (not read-only) ID of the pad.

    +
    • +
  • +

    readOnly: Whether the client has read-only access (true) or read/write +access (false).

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
  • +

    client: (Deprecated; use socket instead.) Synonym of socket.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.handleMessageSecurity = async (hookName, context) => {
+  const {message, sessionInfo: {readOnly}} = context;
+  if (!readOnly || message.type !== 'COLLABROOM') return;
+  if (await messageIsBenign(message)) return 'permitOnce';
+};
+
+
+
+
+

clientVars

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    clientVars - the basic clientVars built by the core

    +
    2. +
  2. +

    pad - the pad this session is about

    +
    3. +
  3. +

    socket - the socket.io Socket object

    +
    4. +
+
+
+

This hook is called after a client connects but before the initial configuration +is sent to the client. Plugins can use this hook to manipulate the +configuration. (Example: Add a tracking ID for an external analytics tool that +is used client-side.)

+
+
+

You can manipulate clientVars in two different ways: +* Return an object. The object will be merged into clientVars via + Object.assign(), so any keys that already exist in clientVars will be + overwritten by the values in the returned object. +* Modify context.clientVars. Beware: Other plugins might also be reading or + manipulating the same context.clientVars object. To avoid race conditions, + you are encouraged to return an object rather than modify + context.clientVars.

+
+
+

If needed, you can access the user’s account information (if authenticated) via +context.socket.client.request.session.user.

+
+
+

Examples:

+
+
+
+
// Using an async function
+exports.clientVars = async (hookName, context) => {
+  const user = context.socket.client.request.session.user || {};
+  return {'accountUsername': user.username || '<unknown>'}
+};
+
+// Using a regular function
+exports.clientVars = (hookName, context, callback) => {
+  const user = context.socket.client.request.session.user || {};
+  return callback({'accountUsername': user.username || '<unknown>'});
+};
+
+
+
+
+

getLineHTMLForExport

+
+

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

+
+
+

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

+
+
+

Context properties:

+
+
+
    +
  • +

    apool: Pool object.

    +
    • +
  • +

    attribLine: Line attributes.

    +
    • +
  • +

    line:

    +
    • +
  • +

    lineContent:

    +
    • +
  • +

    text: Line text.

    +
    • +
  • +

    padId: Writable (not read-only) pad identifier.

    +
    • +
+
+
+

Example:

+
+
+
+
const AttributeMap = require('ep_etherpad-lite/static/js/AttributeMap');
+const Changeset = require('ep_etherpad-lite/static/js/Changeset');
+
+exports.getLineHTMLForExport = async (hookName, context) => {
+  if (!context.attribLine) return;
+  const [op] = Changeset.deserializeOps(context.attribLine);
+  if (op == null) return;
+  const heading = AttributeMap.fromString(op.attribs, context.apool).get('heading');
+  if (!heading) return;
+  context.lineContent = `<${heading}>${context.lineContent}</${heading}>`;
+};
+
+
+
+
+

exportHTMLAdditionalContent

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    padId

    +
    2. +
+
+
+

This hook will allow a plug-in developer to include additional HTML content in +the body of the exported HTML.

+
+
+

Example:

+
+
+
+
exports.exportHTMLAdditionalContent = async (hookName, {padId}) => {
+  return 'I am groot in ' + padId;
+};
+
+
+
+
+

stylesForExport

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    padId - The Pad Id

    +
    2. +
+
+
+

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

+
+
+

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.

+
+
+

An attributes object is passed to the aceAttribClasses hook functions instead of +the usual context object. A hook function can either modify this object directly +or provide an object whose properties will be assigned to the attributes object.

+
+
+

Example:

+
+
+
+
exports.aceAttribClasses = (hookName, attrs, cb) => {
+  return cb([{
+    sub: 'tag:sub',
+  }]);
+};
+
+
+
+
+

exportFileName

+
+

Called from src/node/handler/ExportHandler.js

+
+
+

Things in context:

+
+
+
    +
  1. +

    padId

    +
    2. +
+
+
+

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

    +
    2. +
+
+
+

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

    +
    2. +
+
+
+

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"]]);
+};
+
+
+
+
+

exportEtherpadAdditionalContent

+
+

Called from src/node/utils/ExportEtherpad.js and +src/node/utils/ImportEtherpad.js.

+
+
+

Called when exporting to an .etherpad file or when importing from an +.etherpad file. The hook function should return prefixes for pad-specific +records that should be included in the export/import. On export, all +${prefix}:${padId} and ${prefix}:${padId}:* records are included in the +generated .etherpad file. On import, all ${prefix}:${padId} and +${prefix}:${padId}:* records are loaded into the database.

+
+
+

Context properties: None.

+
+
+

Example:

+
+
+
+
// Add support for exporting comments metadata
+exports.exportEtherpadAdditionalContent = () => ['comments'];
+
+
+
+
+

exportEtherpad

+
+

Called from src/node/utils/ExportEtherpad.js.

+
+
+

Called when exporting to an .etherpad file.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The exported pad’s Pad object.

    +
    • +
  • +

    data: JSONable output object. This is pre-populated with records from core +Etherpad as well as pad-specific records with prefixes from the +exportEtherpadAdditionalContent hook. Registered hook functions can modify +this object (but not replace the object) to perform any desired +transformations to the exported data (such as the inclusion of +plugin-specific records). All registered hook functions are executed +concurrently, so care should be taken to avoid race conditions with other +plugins.

    +
    • +
  • +

    dstPadId: The pad ID that should be used when writing pad-specific records +to data (instead of pad.id). This avoids leaking the writable pad ID +when a user exports a read-only pad. This might be a dummy value; plugins +should not assume that it is either the pad’s real writable ID or its +read-only ID.

    +
    • +
+
+
+
+

importEtherpad

+
+

Called from src/node/utils/ImportEtherpad.js.

+
+
+

Called when importing from an .etherpad file.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: Temporary Pad object containing the pad’s data read from the imported +.etherpad file. The pad.db object is a temporary in-memory database +whose records will be copied to the real database after they are validated +(see the padCheck hook). Registered hook functions MUST NOT use the real +database to access (read or write) pad-specific records; they MUST instead +use pad.db. All registered hook functions are executed concurrently, so +care should be taken to avoid race conditions with other plugins.

    +
    • +
  • +

    data: Raw JSONable object from the .etherpad file. This data must not be +modified.

    +
    • +
  • +

    srcPadId: The pad ID used for the pad-specific information in data.

    +
    • +
+
+
+
+

import

+
+

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

+
+
+

Called when a user submits a document for import, before the document is +converted to HTML. The hook function should return a truthy value if the hook +function elected to convert the document to HTML.

+
+
+

Context properties:

+
+
+
    +
  • +

    destFile: The destination HTML filename.

    +
    • +
  • +

    fileEnding: The lower-cased filename extension from srcFile with leading +period (examples: '.docx', '.html', '.etherpad').

    +
    • +
  • +

    padId: The identifier of the destination pad.

    +
    • +
  • +

    srcFile: The document to convert.

    +
    • +
  • +

    ImportError: Subclass of Error that can be thrown to provide a specific +error message to the user. The constructor’s first argument must be a string +matching one of the known error identifiers.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.import = async (hookName, {fileEnding, ImportError}) => {
+  // Reject all *.etherpad imports with a permission denied message.
+  if (fileEnding === '.etherpad') throw new ImportError('permission');
+};
+
+
+
+
+

userJoin

+
+

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

+
+
+

Called after users have been notified that a new user has joined the pad.

+
+
+

Context properties:

+
+
+
    +
  • +

    authorId: The user’s author identifier.

    +
    • +
  • +

    displayName: The user’s display name.

    +
    • +
  • +

    padId: The real (not read-only) identifier of the pad the user joined. This +MUST NOT be shared with any users that are connected with read-only access.

    +
    • +
  • +

    readOnly: Whether the user only has read-only access.

    +
    • +
  • +

    readOnlyPadId: The read-only identifier of the pad the user joined.

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.userJoin = async (hookName, {authorId, displayName, padId}) => {
+  console.log(`${authorId} (${displayName}) joined pad ${padId});
+};
+
+
+
+
+

userLeave

+
+

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

+
+
+

Called when a user disconnects from a pad. This is useful if you want to perform +certain actions after a pad has been edited.

+
+
+

Context properties:

+
+
+
    +
  • +

    authorId: The user’s author ID.

    +
    • +
  • +

    padId: The pad’s real (not read-only) identifier.

    +
    • +
  • +

    readOnly: If truthy, the user only has read-only access.

    +
    • +
  • +

    readOnlyPadId: The pad’s read-only identifier.

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.userLeave = async (hookName, {author, padId}) => {
+  console.log(`${author} left pad ${padId}`);
+};
+
+
+
+
+

chatNewMessage

+
+

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

+
+
+

Called when a user (or plugin) generates a new chat message, just before it is +saved to the pad and relayed to all connected users.

+
+
+

Context properties:

+
+
+
    +
  • +

    message: The chat message object. Plugins can mutate this object to change +the message text or add custom metadata to control how the message will be +rendered by the chatNewMessage client-side hook. The message’s authorId +property can be trusted (the server overwrites any client-provided author ID +value with the user’s actual author ID before this hook runs).

    +
    • +
  • +

    padId: The pad’s real (not read-only) identifier.

    +
    • +
  • +

    pad: The pad’s Pad object.

    +
    • +
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/api/http_api.html b/public/doc/v2.2.7/api/http_api.html new file mode 100644 index 0000000..4e15e05 --- /dev/null +++ b/public/doc/v2.2.7/api/http_api.html @@ -0,0 +1,2075 @@ + + + + + + + +HTTP API + + + + + +
+
+

HTTP API

+
+
+

What can I do with this API?

+
+

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

+
+
+
    +
  • +

    create/delete pads

    +
    • +
  • +

    grant/forbid access to pads

    +
    • +
  • +

    get/set pad content

    +
    • +
+
+
+

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.

+
+
+

OpenAPI

+
+

OpenAPI (formerly swagger) definitions are exposed under /api/openapi.json (latest) and /api/2.2.7/openapi.json. You can use official tools like Swagger Editor to view and explore them.

+
+
+
+
+

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

+
+
+

The current version can be queried via /api.

+
+
+
+

Request Format

+
+

The API is accessible via HTTP. Starting from 1.8, API endpoints can be invoked indifferently via GET or POST.

+
+
+

The URL of the HTTP request is of the form: /api/$APIVERSION/$FUNCTIONNAME. $APIVERSION depends on the endpoint you want to use. Depending on the verb you use (GET or POST) parameters can be passed differently.

+
+
+

When invoking via GET (mandatory until 1.7.5 included), parameters must be included in the query string (example: /api/$APIVERSION/$FUNCTIONNAME?apikey=<APIKEY>&param1=value1). Please note that starting with nodejs 8.14+ the total size of HTTP request headers has been capped to 8192 bytes. This limits the quantity of data that can be sent in an API request.

+
+
+

Starting from Etherpad 1.8 it is also possible to invoke the HTTP API via POST. In this case, querystring parameters will still be accepted, but any parameter with the same name sent via POST will take precedence. If you need to send large chunks of text (for example, for setText()) it is advisable to invoke via POST.

+
+
+

Example with cURL using GET (toy example, no encoding):

+
+
+
+
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname&text=this_text_will_NOT_be_encoded_by_curl_use_next_example"
+
+
+
+

Example with cURL using GET (better example, encodes text):

+
+
+
+
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname" --get --data-urlencode "text=Text sent via GET with proper encoding. For big documents, please use POST"
+
+
+
+

Example with cURL using POST:

+
+
+
+
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname" --data-urlencode "text=Text sent via POST with proper encoding. For big texts (>8 KB), use this method"
+
+
+
+
+

Response Format

+
+

Responses are valid JSON in the following format:

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

    code a return code

    +
    • +
  • +

    0 everything ok

    +
    • +
  • +

    1 wrong parameters

    +
    • +
  • +

    2 internal error

    +
    • +
  • +

    3 no such function

    +
    • +
  • +

    4 no or wrong API Key

    +
    • +
  • +

    message a status message. It’s ok if everything is fine, else it contains an error message

    +
    • +
  • +

    data the payload

    +
    • +
+
+
+
+

Overview

+
+
+API Overview +
+
+
+
+
+

Data Types

+
+
    +
  • +

    groupID a string, the unique id of a group. Format is g.16RANDOMCHARS, for example g.s8oes9dhwrvt0zif

    +
    • +
  • +

    sessionID a string, the unique id of a session. Format is s.16RANDOMCHARS, for example s.s8oes9dhwrvt0zif

    +
    • +
  • +

    authorID a string, the unique id of an author. Format is a.16RANDOMCHARS, for example a.s8oes9dhwrvt0zif

    +
    • +
  • +

    readOnlyID a string, the unique id of a readonly relation to a pad. Format is r.16RANDOMCHARS, for example r.s8oes9dhwrvt0zif

    +
    • +
  • +

    padID a string, format is GROUPID$PADNAME, for example the pad test of group g.s8oes9dhwrvt0zif has padID g.s8oes9dhwrvt0zif$test

    +
    • +
+
+
+

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.

+
+
+
+
+

API Methods

+
+

Groups

+
+

Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test

+
+
+
createGroup()
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

creates a new group

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
+
+
+
+
createGroupIfNotExistsFor(groupMapper)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

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)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

deletes a group

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"groupID does not exist", data: null}

    +
    • +
+
+
+
+
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], [authorId])
+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

creates a new pad in this group

+
+
+

Example returns:

+
+
+
    +
  • +

    {code: 0, message:"ok", data: {padID: "g.s8oes9dhwrvt0zif$test"}

    +
    • +
  • +

    {code: 1, message:"padName does already exist", data: null}

    +
    • +
  • +

    {code: 1, message:"groupID does not exist", data: null}

    +
    • +
+
+
+
+
listAllGroups()
+
+
    +
  • +

    API >= 1.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])
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

creates a new author

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
+
+
+
+
createAuthorIfNotExistsFor(authorMapper [, name])
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

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)
+
+
    +
  • +

    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)
+
+
    +
  • +

    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

+
+
+
+
+

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)
+
+
    +
  • +

    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)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

deletes a session

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"sessionID does not exist", data: null}

    +
    • +
+
+
+
+
getSessionInfo(sessionID)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

returns information 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)
+
+
    +
  • +

    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)
+
+
    +
  • +

    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}

    +
    • +
+
+
+
+
+

Pad Content

+
+

Pad content can be updated and retrieved through the API

+
+
+
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, [authorId])
+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

Sets the text of a pad.

+
+
+

If your text is long (>8 KB), please invoke via POST and include text parameter in the body of the request, not in the URL (since Etherpad 1.8).

+
+
+

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, [authorId])
+
+
    +
  • +

    API >= 1.2.13

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

Appends text to a pad.

+
+
+

If your text is long (>8 KB), please invoke via POST and include text parameter in the body of the request, not in the URL (since Etherpad 1.8).

+
+
+

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])
+
+
    +
  • +

    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}

    +
    • +
+
+
+
+
setHTML(padID, html, [authorId])
+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

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

+
+
+

If html is long (>8 KB), please invoke via POST and include html parameter in the body of the request, not in the URL (since Etherpad 1.8).

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+
getAttributePool(padID)
+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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])
+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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 https://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)
+
+
    +
  • +

    API >= 1.2.7

    +
    • +
+
+
+

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://etherpad.org\">http://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, [authorId])
+
+
    +
  • +

    API >= 1.2.11

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

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])
+
+
    +
  • +

    API >= 1.2.7

    +
    • +
+
+
+

returns

+
+
+
    +
  • +

    a part of the chat history, when start and end are given

    +
    • +
  • +

    the whole chat history, when no extra parameters are given

    +
    • +
+
+
+

Example returns:

+
+
+
    +
  • +

    {"code":0,"message":"ok","data":{"messages":[{"text":"foo","userId":"a.foo","time":1359199533759,"userName":"test"},{"text":"bar","userId":"a.foo","time":1359199534622,"userName":"test"}]}}

    +
    • +
  • +

    {code: 1, message:"start is higher or equal to the current chatHead", data: null}

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+
getChatHead(padID)
+
+
    +
  • +

    API >= 1.2.7

    +
    • +
+
+
+

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

+
+
+

Example returns:

+
+
+
    +
  • +

    {code: 0, message:"ok", data: {chatHead: 42}}

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+
appendChatMessage(padID, text, authorID [, time])
+
+
    +
  • +

    API >= 1.2.12

    +
    • +
+
+
+

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

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"text is no string", data: null}

    +
    • +
+
+
+
+
+
+

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], [authorId])

+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

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)

+
+
    +
  • +

    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}

    +
    • +
+
+
+
+

getSavedRevisionsCount(padID)

+
+
    +
  • +

    API >= 1.2.11

    +
    • +
+
+
+

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)

+
+
    +
  • +

    API >= 1.2.11

    +
    • +
+
+
+

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

+
+
    +
  • +

    API >= 1.2.11

    +
    • +
+
+
+

saves a revision

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+

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)

+
+
    +
  • +

    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,"id":"a.n4gEeMLsvg12452n"},{"colorId":"#d9a9cd","name":"Hmmm","timestamp":1345228796042,"id":"a.n4gEeMLsvg12452n"}]}}

    +
    • +
  • +

    {code: 0, message:"ok", data: {padUsers: []}}

    +
    • +
+
+
+
+

deletePad(padID)

+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

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

+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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}

    +
    • +
+
+
+
+

copyPadWithoutHistory(sourceID, destinationID, [force=false], [authorId])

+
+
    +
  • +

    API >= 1.2.15

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

copies a pad without copying the history and chat. If force is true and the destination pad exists, it will be overwritten. +Note that all the revisions will be lost! In most of the cases one should use copyPad API instead.

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+

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

+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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)

+
+
    +
  • +

    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}

    +
    • +
+
+
+
+

getPadID(readOnlyID)

+
+
    +
  • +

    API >= 1.2.10

    +
    • +
+
+
+

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)

+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

sets a boolean for the public status of a group pad

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
  • +

    {code: 1, message:"You can only get/set the publicStatus of pads that belong to a group", data: null}

    +
    • +
+
+
+
+

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}

    +
    • +
  • +

    {code: 1, message:"You can only get/set the publicStatus of pads that belong to a group", data: null}

    +
    • +
+
+
+
+

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)

+
+
    +
  • +

    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)

+
+
    +
  • +

    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}

    +
    • +
+
+
+
+

checkToken()

+
+
    +
  • +

    API >= 1.2

    +
    • +
+
+
+

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

+
+
    +
  • +

    API >= 1.2.1

    +
    • +
+
+
+

lists all pads on this epl instance

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
+
+
+
+

Global

+
+
getStats()
+
+
    +
  • +

    API >= 1.2.14

    +
    • +
+
+
+

get stats of the etherpad instance

+
+
+

Example returns:

+
+
+
    +
  • +

    {"code":0,"message":"ok","data":{"totalPads":3,"totalSessions": 2,"totalActivePads": 1}}

    +
    • +
+
+
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/api/pluginfw.html b/public/doc/v2.2.7/api/pluginfw.html new file mode 100644 index 0000000..20440d4 --- /dev/null +++ b/public/doc/v2.2.7/api/pluginfw.html @@ -0,0 +1,482 @@ + + + + + + + +Plugin Framework + + + + + +
+
+

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

+
+

?

+
+
+
+

…​

+ +
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/api/toolbar.html b/public/doc/v2.2.7/api/toolbar.html new file mode 100644 index 0000000..7f2997c --- /dev/null +++ b/public/doc/v2.2.7/api/toolbar.html @@ -0,0 +1,552 @@ + + + + + + + +Toolbar controller + + + + + +
+
+

Toolbar controller

+
+
+

src/node/utils/toolbar.js

+
+
+

button(opts)

+
+
    +
  • +

    {Object} opts

    +
    • +
  • +

    command - this command fill be fired on the editbar on click

    +
    • +
  • +

    localizationId - will be set as data-l10-id

    +
    • +
  • +

    class - here you can add additional classes to the button

    +
    • +
+
+
+

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)

+
+
    +
  • +

    {Object} opts

    +
    • +
  • +

    id - id of the menu item

    +
    • +
  • +

    selectId - id of the select element

    +
    • +
  • +

    command - this command fill be fired on the editbar on change

    +
    • +
+
+
+

Returns: {SelectButton}

+
+
+
+

SelectButton.addOption(value, text, attributes)

+
+
    +
  • +

    {String} value - The value of this option

    +
    • +
  • +

    {String} text - the label text used for this option

    +
    • +
  • +

    {Object} attributes - any additional html attributes go here (e.g. data-l10n-id)

    +
    • +
+
+
+
+

registerButton(name, item)

+
+
    +
  • +

    {String} name - used to reference the item in the toolbar config in settings.json

    +
    • +
  • +

    {Button|SelectButton} item - the button to add

    +
    • +
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/cookies.html b/public/doc/v2.2.7/cookies.html new file mode 100644 index 0000000..f2f7457 --- /dev/null +++ b/public/doc/v2.2.7/cookies.html @@ -0,0 +1,544 @@ + + + + + + + +Cookies + + + + + +
+
+

Cookies

+
+
+

Cookies used by Etherpad.

+
+ ++++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Name

Sample value

Domain

Path

Expires/max-age

Http-only

Secure

Usage description

express_sid

s%3A7yCNjRmTW8ylGQ53I2IhOwYF9…​

example.org

/

Session

true

true

Session ID of the Express web framework. When Etherpad is behind a reverse proxy, and an administrator wants to use session stickiness, he may use this cookie. If you are behind a reverse proxy, please remember to set trustProxy: true in settings.json. Set in webaccess.js#L131.

language

en

example.org

/

Session

false

true

The language of the UI (e.g.: en-GB, it). Set in pad_editor.js#L111.

prefs / prefsHttp

%7B%22epThemesExtTheme%22…​

example.org

/p

year 3000

false

true

Client-side preferences (e.g.: font family, chat always visible, show authorship colors, …​). Set in pad_cookie.js#L49. prefs is used if Etherpad is accessed over HTTPS, prefsHttp if accessed over HTTP. For more info see https://github.com/ether/etherpad-lite/issues/3179.

token

t.tFzkihhhBf4xKEpCK3PU

example.org

/

60 days

false

true

A random token representing the author, of the form t.randomstring_of_lenght_20. The random string is generated by the client, at pad.js#L55-L66. This cookie is always set by the client at pad.js#L153-L158 without any solicitation from the server. It is used for all the pads accessed via the web UI (not used for the HTTP API). On the server side, its value is accessed at SecurityManager.js#L33.

+
+

For more info, visit the related discussion at https://github.com/ether/etherpad-lite/issues/3563.

+
+
+

Etherpad HTTP API clients may make use (if they choose so) to send another cookie:

+
+ +++++ + + + + + + + + + + + + +

Name

Sample value

Domain

Usage description

sessionID

s.1c70968b333b25476a2c7bdd0e0bed17

+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/database.html b/public/doc/v2.2.7/database.html new file mode 100644 index 0000000..9b09867 --- /dev/null +++ b/public/doc/v2.2.7/database.html @@ -0,0 +1,623 @@ + + + + + + + +Database structure + + + + + +
+
+

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

+
+
+
    +
  • +

    atext - the latest attributed text

    +
    • +
  • +

    pool - the attribute pool

    +
    • +
  • +

    head - the number of the latest revision

    +
    • +
  • +

    chatHead - the number of the latest chat entry

    +
    • +
  • +

    public - flag that disables security for this pad

    +
    • +
  • +

    passwordHash - string that contains a salted sha512 sum of this pad’s password

    +
    • +
+
+
+
+

pad:$PADID:revs:$REVNUM

+
+

Saves a revision $REVNUM of pad $PADID

+
+
+
    +
  • +

    meta

    +
    • +
  • +

    author - the autorID of this revision

    +
    • +
  • +

    timestamp - the timestamp of when this revision was created

    +
    • +
  • +

    changeset - the changeset of this revision

    +
    • +
+
+
+
+

pad:$PADID:chat:$CHATNUM

+
+

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

+
+
+
    +
  • +

    text - the text of this chat entry

    +
    • +
  • +

    userId - the authorID of this chat entry

    +
    • +
  • +

    time - the timestamp of this chat entry

    +
    • +
+
+
+
+

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

+
+
+
    +
  • +

    name - the name of this author as shown in the pad

    +
    • +
  • +

    colorID - the colorID of this author as shown in the pad

    +
    • +
+
+
+
+

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

+
+
+
    +
  • +

    pads - object with pad names in it, values are 1 +==== session:$SESSIONID +a session between an author and a group

    +
    • +
  • +

    groupID - the groupID the session belongs too

    +
    • +
  • +

    authorID - the authorID the session belongs too

    +
    • +
  • +

    validUntil - the timestamp until this session is valid

    +
    • +
+
+
+
+

author2sessions:$AUTHORID

+
+

saves the sessions of an author

+
+
+
    +
  • +

    sessionsIDs - object with sessionIDs in it, values are 1

    +
    • +
+
+
+
+

group2sessions:$GROUPID

+
+
    +
  • +

    sessionsIDs - object with sessionIDs in it, values are 1

    +
    • +
+
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/docker.html b/public/doc/v2.2.7/docker.html new file mode 100644 index 0000000..2e22646 --- /dev/null +++ b/public/doc/v2.2.7/docker.html @@ -0,0 +1,1208 @@ + + + + + + + +Docker + + + + + +
+
+

Docker

+
+
+

The official Docker image is available on https://hub.docker.com/r/etherpad/etherpad.

+
+
+

Downloading from Docker Hub

+
+

If you are ok downloading a prebuilt image from Docker Hub, these are the commands:

+
+
+
+
# gets the latest published version
+docker pull etherpad/etherpad
+
+# gets a specific version
+docker pull etherpad/etherpad:1.8.0
+
+
+
+
+

Build a personalized container

+
+

If you want to use a personalized settings file, you will have to rebuild your image. +All of the following instructions are as a member of the docker group. +By default, the Etherpad Docker image is built and run in production mode: no development dependencies are installed, and asset bundling speeds up page load time.

+
+
+
+

Building and running with docker compose

+
+

A docker compose file is provided in the project. Please first copy .env.default to .env and adjust the variables to your preference.

+
+
+
+
docker compose up -d # will build and start the docker container on port 9001 with development settings.
+
+
+
+

Starting dev server:

+
+
+
+
docker compose exec app bash -c "./bin/run.sh"
+
+
+
+

For production, please create your own docker compose file and change the target property in the build section to production. In addition, change the NODE_ENV in environment to production. For instance:

+
+
+
+
docker compose -f docker-compose-production.yml up -d
+
+
+
+

For plugins, please add them in the build section under ETHERPAD_PLUGINS, for instance:

+
+
+
+
     args:
+        ETHERPAD_PLUGINS: >-
+          ep_image_upload
+          ep_embedded_hyperlinks2
+          ep_headings2
+          ep_align
+					...
+
+
+
+

Rebuilding with custom settings

+
+

Edit <BASEDIR>/settings.json.docker at your will. When rebuilding the image, this file will be copied inside your image and renamed to settings.json.

+
+
+

Each configuration parameter can also be set via an environment variable, using the syntax "${ENV_VAR}" or "${ENV_VAR:default_value}". For details, refer to settings.json.template.

+
+
+
+

Rebuilding including some plugins

+
+

If you want to install some plugins in your container, it is sufficient to list them in the ETHERPAD_PLUGINS build variable. +The variable value has to be a space separated, double quoted list of plugin names (see examples).

+
+
+

Some plugins will need personalized settings. Just refer to the previous section, and include them in your custom settings.json.docker.

+
+
+
+

Rebuilding including export functionality for DOC/PDF/ODT

+
+

If you want to be able to export your pads to DOC/PDF/ODT files, you can install +either Abiword or Libreoffice via setting a build variable.

+
+
+
Via Abiword
+
+

For installing Abiword, set the INSTALL_ABIWORD build variable to any value.

+
+
+

Also, you will need to configure the path to the abiword executable +via setting the abiword property in <BASEDIR>/settings.json.docker to +/usr/bin/abiword or via setting the environment variable ABIWORD to +/usr/bin/abiword.

+
+
+
+
Via Libreoffice
+
+

For installing Libreoffice instead, set the INSTALL_SOFFICE build variable +to any value.

+
+
+

Also, you will need to configure the path to the libreoffice executable +via setting the soffice property in <BASEDIR>/settings.json.docker to +/usr/bin/soffice or via setting the environment variable SOFFICE to +/usr/bin/soffice.

+
+
+
+
+

Examples

+
+

Build a Docker image from the currently checked-out code:

+
+
+
+
docker build --tag <YOUR_USERNAME>/etherpad .
+
+
+
+

Include two plugins in the container:

+
+
+
+
docker build --build-arg ETHERPAD_PLUGINS="ep_comments_page ep_author_neat" --tag <YOUR_USERNAME>/etherpad .
+
+
+
+
+
+

Running your instance:

+
+

To run your instance:

+
+
+
+
docker run --detach --publish <DESIRED_PORT>:9001 <YOUR_USERNAME>/etherpad
+
+
+
+

And point your browser to http://<YOUR_IP>:<DESIRED_PORT>;

+
+
+
+

Options available by default

+
+

The settings.json.docker available by default allows to control almost every setting via environment variables.

+
+
+

General

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Variable

Description

Default

TITLE

The name of the instance

Etherpad

FAVICON

favicon default name, or a fully specified URL to your own favicon

favicon.ico

DEFAULT_PAD_TEXT

The default text of a pad

Welcome to Etherpad! 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! Get involved with Etherpad at https://etherpad.org

IP

IP which etherpad should bind at. Change to :: for IPv6

0.0.0.0

PORT

port which etherpad should bind at

9001

ADMIN_PASSWORD

the password for the admin user (leave unspecified if you do not want to create it)

USER_PASSWORD

the password for the first user user (leave unspecified if you do not want to create it)

+
+
+

Database

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Variable

Description

Default

DB_TYPE

a database supported by https://www.npmjs.com/package/ueberdb2

not set, thus will fall back to DirtyDB (please choose one instead)

DB_HOST

the host of the database

DB_PORT

the port of the database

DB_NAME

the database name

DB_USER

a database user with sufficient permissions to create tables

DB_PASS

the password for the database username

DB_CHARSET

the character set for the tables (only required for MySQL)

DB_FILENAME

in case DB_TYPE is DirtyDB or sqlite, the database file.

var/dirty.db, var/etherpad.sq3

+
+

If your database needs additional settings, you will have to use a personalized settings.json.docker and rebuild the container (or otherwise put the updated settings.json inside your image).

+
+
+
+

Pad Options

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Variable

Description

Default

PAD_OPTIONS_NO_COLORS

false

PAD_OPTIONS_SHOW_CONTROLS

true

PAD_OPTIONS_SHOW_CHAT

true

PAD_OPTIONS_SHOW_LINE_NUMBERS

true

PAD_OPTIONS_USE_MONOSPACE_FONT

false

PAD_OPTIONS_USER_NAME

null

PAD_OPTIONS_USER_COLOR

null

PAD_OPTIONS_RTL

false

PAD_OPTIONS_ALWAYS_SHOW_CHAT

false

PAD_OPTIONS_CHAT_AND_USERS

false

PAD_OPTIONS_LANG

null

+
+
+

Shortcuts

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Variable

Description

Default

PAD_SHORTCUTS_ENABLED_ALT_F9

focus on the File Menu and/or editbar

true

PAD_SHORTCUTS_ENABLED_ALT_C

focus on the Chat window

true

PAD_SHORTCUTS_ENABLED_CMD_S

save a revision

true

PAD_SHORTCUTS_ENABLED_CMD_Z

undo/redo

true

PAD_SHORTCUTS_ENABLED_CMD_Y

redo

true

PAD_SHORTCUTS_ENABLED_CMD_I

italic

true

PAD_SHORTCUTS_ENABLED_CMD_B

bold

true

PAD_SHORTCUTS_ENABLED_CMD_U

underline

true

PAD_SHORTCUTS_ENABLED_CMD_H

backspace

true

PAD_SHORTCUTS_ENABLED_CMD_5

strike through

true

PAD_SHORTCUTS_ENABLED_CMD_SHIFT_1

ordered list

true

PAD_SHORTCUTS_ENABLED_CMD_SHIFT_2

shows a gritter popup showing a line author

true

PAD_SHORTCUTS_ENABLED_CMD_SHIFT_L

unordered list

true

PAD_SHORTCUTS_ENABLED_CMD_SHIFT_N

ordered list

true

PAD_SHORTCUTS_ENABLED_CMD_SHIFT_C

clear authorship

true

PAD_SHORTCUTS_ENABLED_DELETE

true

PAD_SHORTCUTS_ENABLED_RETURN

true

PAD_SHORTCUTS_ENABLED_ESC

in mozilla versions 14-19 avoid reconnecting pad

true

PAD_SHORTCUTS_ENABLED_TAB

indent

true

PAD_SHORTCUTS_ENABLED_CTRL_HOME

scroll to top of pad

true

PAD_SHORTCUTS_ENABLED_PAGE_UP

true

PAD_SHORTCUTS_ENABLED_PAGE_DOWN

true

+
+
+

Skins

+
+

You can use the UI skin variants builder at /p/test#skinvariantsbuilder

+
+
+

For the colibris skin only, you can choose how to render the three main containers: + * toolbar (top menu with icons) + * editor (containing the text of the pad) + * background (area outside of editor, mostly visible when using page style)

+
+
+

For each of the 3 containers you can choose 4 color combinations: + * super-light + * light + * dark + * super-dark

+
+
+

For the editor container, you can also make it full width by adding full-width-editor variant (by default editor is rendered as a page, with a max-width of 900px).

+
+ +++++ + + + + + + + + + + + + + + + + + +

Variable

Description

Default

SKIN_NAME

either no-skin, colibris or an existing directory under src/static/skins

colibris

SKIN_VARIANTS

multiple skin variants separated by spaces

super-light-toolbar super-light-editor light-background

+
+
+

Logging

+ +++++ + + + + + + + + + + + + + + + + + +

Variable

Description

Default

LOGLEVEL

valid values are DEBUG, INFO, WARN and ERROR

INFO

DISABLE_IP_LOGGING

Privacy: disable IP logging

false

+
+
+

Advanced

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Variable

Description

Default

COOKIE_KEY_ROTATION_INTERVAL

How often (ms) to rotate in a new secret for signing cookies

86400000 (1 day)

COOKIE_SAME_SITE

Value of the SameSite cookie property.

"Lax"

COOKIE_SESSION_LIFETIME

How long (ms) a user can be away before they must log in again.

864000000 (10 days)

COOKIE_SESSION_REFRESH_INTERVAL

How often (ms) to write the latest cookie expiration time.

86400000 (1 day)

SHOW_SETTINGS_IN_ADMIN_PAGE

hide/show the settings.json in admin page

true

TRUST_PROXY

set to true if you are using a reverse proxy in front of Etherpad (for example: Traefik for SSL termination via Let’s Encrypt). This will affect security and correctness of the logs if not done

false

IMPORT_MAX_FILE_SIZE

maximum allowed file size when importing a pad, in bytes.

52428800 (50 MB)

IMPORT_EXPORT_MAX_REQ_PER_IP

maximum number of import/export calls per IP.

10

IMPORT_EXPORT_RATE_LIMIT_WINDOW

the call rate for import/export requests will be estimated in this time window (in milliseconds)

90000

COMMIT_RATE_LIMIT_DURATION

duration of the rate limit window for commits by individual users/IPs (in seconds)

1

COMMIT_RATE_LIMIT_POINTS

maximum number of changes per IP to allow during the rate limit window

10

SUPPRESS_ERRORS_IN_PAD_TEXT

Should we suppress errors from being visible in the default Pad Text?

`false

REQUIRE_SESSION

If this option is enabled, a user must have a session to access pads. This effectively allows only group pads to be accessed.

false

EDIT_ONLY

Users may edit pads but not create new ones. Pad creation is only via the API. This applies both to group pads and regular pads.

false

MINIFY

If true, all css & js will be minified before sending to the client. This will improve the loading performance massively, but makes it difficult to debug the javascript/css

true

MAX_AGE

How long may clients use served javascript code (in seconds)? Not setting this may cause problems during deployment. Set to 0 to disable caching.

21600 (6 hours)

ABIWORD

Absolute path to the Abiword executable. Abiword is needed to get advanced import/export features of pads. Setting it to null disables Abiword and will only allow plain text and HTML import/exports.

null

SOFFICE

This is the absolute path to the soffice executable. LibreOffice can be used in lieu of Abiword to export pads. Setting it to null disables LibreOffice exporting.

null

ALLOW_UNKNOWN_FILE_ENDS

Allow import of file types other than the supported ones: txt, doc, docx, rtf, odt, html & htm

true

REQUIRE_AUTHENTICATION

This setting is used if you require authentication of all users. Note: "/admin" always requires authentication.

false

REQUIRE_AUTHORIZATION

Require authorization by a module, or a user with is_admin set, see below.

false

AUTOMATIC_RECONNECTION_TIMEOUT

Time (in seconds) to automatically reconnect pad when a "Force reconnect" message is shown to user. Set to 0 to disable automatic reconnection.

0

FOCUS_LINE_PERCENTAGE_ABOVE

Percentage of viewport height to be additionally scrolled. e.g. 0.5, to place caret line in the middle of viewport, when user edits a line above of the viewport. Set to 0 to disable extra scrolling

0

FOCUS_LINE_PERCENTAGE_BELOW

Percentage of viewport height to be additionally scrolled. e.g. 0.5, to place caret line in the middle of viewport, when user edits a line below of the viewport. Set to 0 to disable extra scrolling

0

FOCUS_LINE_PERCENTAGE_ARROW_UP

Percentage of viewport height to be additionally scrolled when user presses arrow up in the line of the top of the viewport. Set to 0 to let the scroll to be handled as default by Etherpad

0

FOCUS_LINE_DURATION

Time (in milliseconds) used to animate the scroll transition. Set to 0 to disable animation

0

FOCUS_LINE_CARET_SCROLL

Flag to control if it should scroll when user places the caret in the last line of the viewport

false

SOCKETIO_MAX_HTTP_BUFFER_SIZE

The maximum size (in bytes) of a single message accepted via Socket.IO. If a client sends a larger message, its connection gets closed to prevent DoS (memory exhaustion) attacks.

50000

LOAD_TEST

Allow Load Testing tools to hit the Etherpad Instance. WARNING: this will disable security on the instance.

false

DUMP_ON_UNCLEAN_EXIT

Enable dumping objects preventing a clean exit of Node.js. WARNING: this has a significant performance impact.

false

EXPOSE_VERSION

Expose Etherpad version in the web interface and in the Server http header. Do not enable on production machines.

false

+
+
+

Examples

+
+

Use a Postgres database, no admin user enabled:

+
+
+
+
docker run -d \
+	--name etherpad         \
+	-p 9001:9001            \
+	-e 'DB_TYPE=postgres'   \
+	-e 'DB_HOST=db.local'   \
+	-e 'DB_PORT=4321'       \
+	-e 'DB_NAME=etherpad'   \
+	-e 'DB_USER=dbusername' \
+	-e 'DB_PASS=mypassword' \
+	etherpad/etherpad
+
+
+
+

Run enabling the administrative user admin:

+
+
+
+
docker run -d \
+	--name etherpad \
+	-p 9001:9001 \
+	-e 'ADMIN_PASSWORD=supersecret' \
+	etherpad/etherpad
+
+
+
+

Run a test instance running DirtyDB on a persistent volume:

+
+
+
+
docker run -d \
+	-v etherpad_data:/opt/etherpad-lite/var \
+	-p 9001:9001 \
+	etherpad/etherpad
+
+
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/documentation.html b/public/doc/v2.2.7/documentation.html new file mode 100644 index 0000000..5a5b1d9 --- /dev/null +++ b/public/doc/v2.2.7/documentation.html @@ -0,0 +1,467 @@ + + + + + + + +About this Documentation + + + + + +
+
+

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 src/bin/doc/generate.js program. +The HTML template is located at doc/template.html.

+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/easysync/README.md b/public/doc/v2.2.7/easysync/README.md new file mode 100644 index 0000000..326fd81 --- /dev/null +++ b/public/doc/v2.2.7/easysync/README.md @@ -0,0 +1,2 @@ +# About this folder +We put all documentations we found about the original Etherpad together in this folder. Most of this is still valid for the current (node.js based) Etherpad. \ No newline at end of file diff --git a/public/doc/v2.2.7/easysync/easysync-full-description.pdf b/public/doc/v2.2.7/easysync/easysync-full-description.pdf new file mode 100644 index 0000000..c552166 Binary files /dev/null and b/public/doc/v2.2.7/easysync/easysync-full-description.pdf differ diff --git a/public/doc/v2.2.7/easysync/easysync-full-description.tex b/public/doc/v2.2.7/easysync/easysync-full-description.tex new file mode 100644 index 0000000..5c936b2 --- /dev/null +++ b/public/doc/v2.2.7/easysync/easysync-full-description.tex @@ -0,0 +1,372 @@ +\documentclass{article} +\usepackage{hyperref} + +\begin{document} + +\title{Etherpad and EasySync Technical Manual} +\author{AppJet, Inc., with modifications by the Etherpad Foundation} +\date{\today} + +\maketitle + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\tableofcontents +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Documents} +\begin{itemize} +\item A document is a list of characters, or a string. +\item A document can also be represented as a list of \emph{changesets}. +\end{itemize} + +\section{Changesets} + +\begin{itemize} +\item A changeset represents a change to a document. +\item A changeset can be applied to a document to produce a new document. +\item When a document is represented as a list of changesets, it is assumed that the first changeset applies to the empty document, []. +\end{itemize} + + +\section{Changeset representation} \label{representation} + +$$(\ell \rightarrow \ell')[c_1,c_2,c_3,...]$$ + +where + +\begin{itemize} +\item[] $\ell$ is the length of the document before the change, +\item[] $\ell'$ is the length of the document after the change, +\item[] $[c_1,c_2,c_3,...]$ is an array of $\ell'$ characters that described the document after the change. +\end{itemize} + +Note that $\forall c_i : 0 \leq i \leq \ell'$ is either an integer or a character. + +\begin{itemize} +\item Integers represent retained characters in the original document. +\item Characters represent insertions. +\end{itemize} + +\section{Constraints on Changesets} + +\begin{itemize} +\item Changesets are canonical and therefor comparable. When represented in computer memory, we always use the same representation for the same changeset. If the memory representation of two changesets differ, they must be different changesets. +\item Changesets are compact. Thus, if there are two ways to represent a changeset in computer memory, then we always use the representation that takes up the fewest bytes. +\end{itemize} + +Later we will discuss optimizations to changeset +representation (using ``strips'' and other such +techniques). The two constraints must apply to any +representation of changesets. + +\section{Notation} + +\begin{itemize} +\item We use the algebraic multiplication notation to represent changeset application. +\item While changesets are defined as operations on documents, documents themselves are represented as a list of changesets, initially applying to the empty document. +\end{itemize} + +\paragraph{Example} +$A=(0\rightarrow 5)[``hello"]$ +$B=(5\rightarrow 11)[0-4, ``\ world"]$ + +We can write the document ``hello world'' as $A\cdot B$ or +just $AB$. Note that the ``initial document'' can be made +into the changeset $(0\rightarrow +N)[``<\mathit{the\ document\ text}>"]$. + +When $A$ and $B$ are changesets, we can also refer to $(AB)$ as ``the composition'' of $A$ and $B$. Changesets are closed under composition. + +\section{Composition of Changesets} + +For any two changesets $A$, $B$ such that + +\begin{itemize} +\item[] $A=(n_1\rightarrow n_2)[\cdots]$ +\item[] $B=(n_2\rightarrow n_3)[\cdots]$ +\end{itemize} +it is clear that there is a third changeset $C=(n_1\rightarrow n_3)[\cdots]$ such that applying $C$ to a document $X$ yields the same resulting document as does applying $A$ and then $B$. In this case, we write $AB=C$. + +Given the representation from Section \ref{representation}, it is straightforward to compute the composition of two changesets. + +\section{Changeset Merging} + +Now we come to realtime document editing. Suppose two different users make two different changes to the same document at the same time. It is impossible to compose these changes. For example, if we have the document $X$ of length $n$, we may have $A=(n\rightarrow n_a)[\ldots n_a \mathrm{characters}]$, $B=(n\rightarrow n_b)[\ldots n_b \mathrm{characters}]$ where $n\neq n_a\neq n_b$. + +It is impossible to compute $(XA)B$ because $B$ can only be applied to a document of length $n$, and $(XA)$ has length $n_a$. Similarly, $A$ cannot be applied to $(XB)$ because $(XB)$ has length $n_b$. + +This is where \emph{merging} comes in. Merging takes two changesets that apply to the same initial document (and that cannot be composed), and computes a single new changeset that preserves the intent of both changes. The merge of $A$ and $B$ is written as $m(A,B)$. For the Etherpad system to work, we require that $m(A,B)=m(B,A)$. + +Aside from what we have said so far about merging, there are many different implementations that will lead to a workable system. We have created one implementation for text that has the following constraints. + +\section{Follows} \label{follows} + +When users $A$ and $B$ have the same document $X$ on their screen, and they proceed to make respective changesets $A$ and $B$, it is no use to compute $m(A,B)$, because $m(A,B)$ applies to document $X$, but the users are already looking at document $XA$ and $XB$. What we really want is to compute $B'$ and $A'$ such that +$$XAB' = XBA' = Xm(A,B)$$ + +``Following'' computes these $B'$ and $A'$ changesets. The definition of the ``follow'' function $f$ is such that $Af(A,B)=Bf(B,A)=m(A,B)=m(B,A)$. When we compute $f(A,B)$ +\begin{itemize} +\item Insertions in $A$ become retained characters in $f(A,B)$ +\item Insertions in $B$ become insertions in $f(A,B)$ +\item Retain whatever characters are retained in \emph{both} $A$ and $B$ +\end{itemize} + +\paragraph{Example} + +Suppose we have the initial document $X=(0\rightarrow 8)[``\mathit{baseball}"]$ and user $A$ changes it to ``basil'' with changeset $A$, and user $B$ changes it to ``below'' with changeset $B$. + +We have +$X=(0\rightarrow 8)[``\mathit{baseball}"]$ \\ +$A=(8\rightarrow 5)[0-1, ``\mathit{si}", 7]$ \\ +$B=(8\rightarrow 5)[0, ``\mathit{e}", 6, ``\mathit{ow}"]$ \\ + +First we compute the merge $m(A,B)=m(B,A)$ according to the constraints + +$$m(A,B)=(8\rightarrow 6)[0, "e", "si", "ow"] = (8\rightarrow 6)[0, ``\mathit{esiow}"]$$ + +Then we need to compute the follows $B'=f(A,B)$ and $A'=f(B,A)$. + +$$B'=f(A,B)=(5\rightarrow 6)[0,``\mathit{e}",2,3,``\mathit{ow}"]$$ + +Note that the numbers $0$, $2$, and $3$ are indices into $A=(8\rightarrow 5)[0,1,``\mathit{si}",7]$ + +\begin{tabular}{ccccc} +0 & 1 & 2 & 3 & 4 \\ +0 & 1 & s & i & 7 +\end{tabular} + +$A'=f(B,A)=(5\rightarrow 6)[0,1,"si",3,4]$ + +We can now double check that $AB'=BA'=m(A,B)=(8\rightarrow 6)[0,``\mathit{esiow}"]$. + +Now that we have made the mathematical meaning of the +preceding pages complete, we can build a client/server +system to support realtime editing by multiple users. + +\section{System Overview} + +There is a server that holds the current state of a +document. Clients (users) can connect to the server from +their web browsers. The clients and server maintain state +and can send messages to one another in real-time, but +because we are in a web browser scenario, clients cannot +send each other messages directly, and must go through the +server always. (This may distinguish from prior art?) + +The other critical design feature of the system is that +\emph{A client must always be able to edit their local + copy of the document, so the user is never blocked from + typing because of waiting to send or receive data.} + +\section{Client State} + +At any moment in time, a client maintains its state in the +form of 3 changesets. The client document looks like +$A\cdot X \cdot Y$, where + +$A$ is the latest server version, the composition of all +changesets committed to the server, from this client or +from others, that the server has informed this client +about. Initially $A=(0\rightarrow N)[<\mathit{initial\ document\ text}>]$. + +$X$ is the composition of all changesets this client has +submitted to the server but has not heard back about yet. +Initially $X=(N\rightarrow N)[0,1,2,\ldots, N-1]$, in +other words, the identity, henceforth denoted $I_N$. + +$Y$ is the composition of all changesets this client has +made but has not yet submitted to the server yet. +Initially $Y=(N\rightarrow N)[0,1,2,\ldots, N-1]$. + +\section{Client Operations} + +A client can do 5 things. + +\begin{enumerate} +\item Incorporate new typing into local state +\item Submit a changeset to the server +\item Hear back acknowledgement of a submitted changeset +\item Hear from the server about other clients' changesets +\item Connect to the server and request the initial document +\end{enumerate} + +As these 5 events happen, the client updates its +representation $A\cdot X \cdot Y$ according to the +relations that follow. Changes ``move left'' as time goes +by: into $Y$ when the user types, into $X$ when change +sets are submitted to the server, and into $A$ when the +server acknowledges changesets. + +\subsection{New local typing} + +When a user makes an edit $E$ to the document, the client +computes the composition $(Y\cdot E)$ and updates its local +state, i.e. $Y \leftarrow Y\cdot E$. I.e., if $Y$ is the +variable holding local unsubmitted changes, it will be +assigned the new value $(Y\cdot E)$. + +\subsection{Submitting changesets to server} + +When a client submit its local changes to the server, it +transmits a copy of $Y$ and then assigns $Y$ to $X$, and +assigns the identity to $Y$. I.e., + +\begin{enumerate} +\item Send $Y$ to server, +\item $X \leftarrow Y$ +\item $Y \leftarrow I_N$ + (the identity). +\end{enumerate} + +This happens every 500ms as long as it receives an +acknowledgement. Must receive ACK before submitting +again. Note that $X$ is always equal to the identity +before the second step occurs, so no information is lost. + +\subsection{Hear ACK from server} + +When the client hears ACK from server, + +$A \leftarrow A\cdot X$ \\ +$X \leftarrow I_N$ + +\subsection{Hear about another client's changeset} + +When a client hears about another client's changeset $B$, +it computes a new $A$, $X$, and $Y$, which we will call +$A'$, $X'$, and $Y'$ respectively. It also computes a +changeset $D$ which is applied to the current text view on +the client, $V$. Because $AXY$ must always equal the +current view, $AXY=V$ before the client hears about $B$, +and $A'X'Y'=VD$ after the computation is performed. + +The steps are: + +\begin{enumerate} +\item Compute $A' = AB$ +\item Compute $X' = f(B,X)$ +\item Compute $Y' = f(f(X,B), Y)$ +\item Compute $D=f(Y,f(X,B))$ +\item Assign $A \leftarrow A'$, $X \leftarrow X'$, $Y \leftarrow Y'$. +\item Apply $D$ to the current view of the document + displayed on the user's screen. +\end{enumerate} + +In steps 2,3, and 4, $f$ is the follow operation described +in Section \ref{follows}. + +\paragraph{Proof that $\mathbf{AXY=V \Rightarrow A'X'Y'=VD}$.} +Substituting $A'X'Y'=(AB)(f(B,X))(f(f(X,B),Y))$, we +recall that merges are commutative. So for any two +changesets $P$ and $Q$, +$$m(P,Q)=m(Q,P)=Qf(Q,P)=Pf(P,Q)$$ + +Applying this to the relation above, we see +\begin{eqnarray*} +A'X'Y'&=& AB f(B,X) f(f(X,B),Y) \\ + &=&AX f(X,B) f(f(X,B),Y) \\ + &=&A X Y f(Y, f(X,B)) \\ + &=&A X Y D \\ + &=&V D +\end{eqnarray*} +As claimed. + +\subsection{Connect to server} + +When a client connects to the server for the first time, +it first generates a random unique ID and sends this to +the server. The client remembers this ID and sends it +with each changeset to the server. + +The client receives the latest version of the document +from the server, called HEADTEXT. The client then sets + +\begin{itemize} +\item[] $A \leftarrow \mathrm{HEADTEXT}$ +\item[] $X \leftarrow I_N$ +\item[] $Y \leftarrow I_N$ +\end{itemize} + +And finally, the client displays HEADTEXT on the screen. + +\section{Server Overview} + +Like the client(s), the server has state and performs +operations. Operations are only performed in response to +messages from clients. + +\section{Server State} + +The server maintains a document as an ordered list of +\emph{revision records}. A revision record is a data +structure that contains a changeset and authorship +information. + +\begin{verbatim} +RevisionRecord = { + ChangeSet, + Source (unique ID), + Revision Number (consecutive order, starting at 0) +} +\end{verbatim} + +For efficiency, the server may also store a variable +called HEADTEXT, which is the composition of all +changesets in the list of revision records. This is an +optimization, because clearly this can be computed from +the set of revision records. + +\section{Server Operations Overview} + +The server does two things in addition to maintaining +state representing the set of connected clients and +remembering what revision number each client is up to date +with: + +\begin{enumerate} +\item Respond to a client's connection requesting the initial document. +\item Respond to a client's submission of a new changeset. +\end{enumerate} + +\subsection{Respond to client connect} +When a server receives a connection request from a client, +it receives the client's unique ID and stores that in the +server's set of connected clients. It then sends the +client the contents of HEADTEXT, and the corresponding +revision number. Finally the server notes that this +client is up to date with that revision number. + +\subsection{Respond to client changeset} + +When the server receives information from a client about +the client's changeset $C$, it does five things: + +\begin{enumerate} +\item Notes that this change applies to revision number + $r_c$ (the client's latest revision). +\item Creates a new changeset $C'$ that is relative to the + server's most recent revision number, which we call + $r_H$ ($H$ for HEAD). $C'$ can be computed using + follows (Section \ref{follows}). Remember that the server has a series of + changesets, +$$S_0\rightarrow S_1\rightarrow \ldots S_{r_c}\rightarrow S_{r_c+1} \rightarrow \ldots \rightarrow S_{r_H} $$ +$C$ is relative to $S_{r_c}$, but we need to compute $C'$ relative to $S_{r_H}$. +We can compute a new $C$ relative to $S_{r_c+1}$ by computing $f(S_{r_c+1},C)$. Similarly we can repeat for +$S_{r_c+2}$ and so forth until we have $C'$ represented relative to $S_{r_H}$. +\item Send $C'$ to all other clients +\item Send ACK back to original client +\item Add $C'$ to the server's list of revision records by creating a new revision record out of this and the client's ID. + +\appendix + +\section*{Additional topics} +\begin{enumerate} +\item Optimizations (strips, more caching, etc.) +\item Pseudocode for composition, merge, and follow +\item How authorship information is used to color-code the document based on who typed what +\item How persistent connections are maintained between client and server +\end{enumerate} +\end{enumerate} + + +\end{document} diff --git a/public/doc/v2.2.7/easysync/easysync-notes.pdf b/public/doc/v2.2.7/easysync/easysync-notes.pdf new file mode 100644 index 0000000..d0af379 Binary files /dev/null and b/public/doc/v2.2.7/easysync/easysync-notes.pdf differ diff --git a/public/doc/v2.2.7/easysync/easysync-notes.tex b/public/doc/v2.2.7/easysync/easysync-notes.tex new file mode 100644 index 0000000..b2c4320 --- /dev/null +++ b/public/doc/v2.2.7/easysync/easysync-notes.tex @@ -0,0 +1,200 @@ +\documentclass[12pt]{article} + +\usepackage[T1]{fontenc} +\usepackage[USenglish]{babel} + + +\begin{document} + +\title{Easysync Protocol} +\author{AppJet, Inc., with modifications by the Etherpad Foundation} +\date{\today} + +\maketitle + +\section{Attributes} + +An ``attribute'' is a (key,value) pair such as +\verb|(author,abc123)| or \verb|(bold,true)|. +Sometimes an attribute is treated as an instruction to add +that attribute, in which case an empty value means to +remove it. So \verb|(bold,)| removes the ``bold'' +attribute. Attributes are interned and given numeric IDs, +so the number ``\verb|6|'' could represent +``\verb|(bold,true)|'', for example. This mapping is +stored in an attribute pool which may be shared by +multiple changesets. + +Entries in the pool must be unique, so that attributes can +be compared by their IDs. Attribute names cannot contain +commas. + +A changeset looks something like the following: + +\begin{verbatim} +Z:5g>1|5=2p=v*4*5+1$x +\end{verbatim} + +With the corresponding pool containing these entries (among others): + +\begin{itemize} +\item[] \verb|4| $\rightarrow$ \verb|(author,1059348573)| +\item[] \verb|5| $\rightarrow$ \verb|(bold,true)| +\end{itemize} + +This changeset, together with the attribute pool, +represents inserting a bold letter ``x'' into the middle +of a line. + +The string consists of: + +\begin{itemize} +\item a letter \verb|Z| (the ``magic character'' and + format version identifier) +\item a series punctuation marks (operation codes or + ``opcodes'' for short), together with alphanumerics + (numeric values in base 36). +\item a dollar sign (\verb|$|) +\item a string of characters used for insertion operations + (the ``char bank'') +\end{itemize} + +In the example above, if we separate out the operations +and convert the numbers to base 10, then we get: +\begin{verbatim} +Z :196 >1 |5=97 =31 *4 *5 +1 $x +\end{verbatim} +Here are descriptions of the operations, where capital +letters are variables: + +\begin{description} +\item{{\bf :N}} \quad \\ +Source text has length $N$ (must be first op) +\item{{\bf >N}} \quad \\ +Final text is $N$ (positive) characters longer than source +text (must be second op) +\item{{\bf 0 }} \quad \\ +Final text is same length as source text +\item{{\bf +N }} \quad \\ +Insert $N$ characters from the bank, none of them newlines +\item{{\bf -N}} \quad \\ +Skip over (delete) $N$ characters from the source text, +none of them newlines +\item{{\bf =N}} \quad \\ +Keep $N$ characters from the source text, none of them newlines +\item{{\bf |L+N}} \quad \\ +Insert $N$ characters from the source text, containing $L$ +newlines. The last character inserted MUST be a newline, +but not the (new) document's final newline. +\item{{\bf |L-N}} \quad \\ +Delete $N$ characters from the source text, containing $L$ +newlines. The last character inserted MUST be a newline, +but not the (old) document's final newline. +\item{{\bf |L=N}} \quad \\ +Keep $N$ characters from the source text, containing L +newlines. The last character kept MUST be a newline, and +the final newline of the document is allowed. +\item{{\bf *I}} \quad \\ +Apply attribute $I$ from the pool to the following +\verb|+|, \verb|=|, \verb_|+_, or \verb_|=_ command. In +other words, any number of \verb|*| ops can come before a +\verb_+_, \verb_=_, or \verb_|_ but not between a \verb_|_ +and the corresponding \verb_+_ or \verb_=_. If \verb_+_, +text is inserted having this attribute. If \verb_=_, text +is kept but with the attribute applied as an attribute +addition or removal. Consecutive attributes must be sorted +lexically by (key,value) with key and value taken as +strings. It's illegal to have duplicate keys for +(key,value) pairs that apply to the same text. It's +illegal to have an empty value for a key in the case of an +insertion (\verb_+_), the pair should just be omitted. +\end{description} + +Characters from the source text that aren't accounted for +are assumed to be kept with the same attributes. + +\paragraph{Additional Constraints} + +\begin{itemize} +\item Consecutive \verb_+_, \verb_-_, and \verb_=_ ops of + the same type that could be combined are not allowed. + Whether combination is possible depends on the + attributes of the ops and whether each is multiline or + not. For example, two multiline deletions can never be + consecutive, nor can any insertion come after a + non-multiline insertion with the same attributes. +\item ``No-op'' ops are not allowed, such as deleting 0 + characters. However, attribute applications that don't + have any effect are allowed. +\item Characters at the end of the source text cannot be + explicitly kept with no changes; if the change doesn't + affect the last $N$ characters, those ``keep'' ops must + be left off. +\item In any consecutive sequence of insertions (\verb_+_) + and deletions (\verb_-_) with no keeps (\verb_=_), the + deletions must come before the insertions. +\item The document text before and after will always end + with a newline. This policy avoids a lot of + special-casing of the end of the document. If a final + newline is always added when importing text and removed + when exporting text, then the changeset representation + can be used to process text files that may or may not + have a final newline. +\end{itemize} + +\paragraph{Attribution string} + +An \emph{attribution string} is a series of inserts with +no deletions or keeps. For example, ``\verb_*3+8|1+5_'' +describes the attributes of a string of length 13, where +the first 8 chars have attribute 3 and the next 5 chars +have no attributes, with the last of these 5 chars being a +newline. Constraints apply similar to those affecting +changesets, but the restriction about the final newline of +the new document being added doesn't apply. + +Attributes in an attribution string cannot be empty, like +``\verb|(bold,)|'', they should instead be absent. + + +\section{Further Considerations} + +\begin{itemize} +\item composing changesets/attributions with different + pools. +\item generalizing ``applyToAttribution'' to make + ``mutateAttributionLines'' and ``compose'' +\end{itemize} + +\section{Using Unicode?} + +\begin{itemize} +\item no unicode (for efficient escaping, sightliness) +\item efficient operations for ACE and collab (attributed text, etc.) +\item good for time-slider +\item good for API +\item line-ending aware +X more coherent (deleting or styling text merging with insertion) +\item server-side syntax highlighting? +\item unify author map with attribute pool +\item unify attributed text with changeset rep +\item not: reversible +\item force final newline of document to be preserved +\end{itemize} + +\paragraph{Unicode bad!} + +\begin{itemize} +\item ugly (hard to read) +\item more complex to parse +\item harder to store and transmit correctly +\item doesn't save all that much space anyway +\item blows up in size when string-escaped +\item embarrassing for API +\end{itemize} + + +\end{document} diff --git a/public/doc/v2.2.7/easysync/easysync-notes.txt b/public/doc/v2.2.7/easysync/easysync-notes.txt new file mode 100644 index 0000000..72adadd --- /dev/null +++ b/public/doc/v2.2.7/easysync/easysync-notes.txt @@ -0,0 +1,133 @@ + + +Copied from the old Etherpad. Found in /infrastructure/ace/ + +Goals: + +- no unicode (for efficient escaping, sightliness) +- efficient operations for ACE and collab (attributed text, etc.) +- good for time-slider +- good for API +- line-ending aware +X more coherent (deleting or styling text merging with insertion) +- server-side syntax highlighting? +- unify author map with attribute pool +- unify attributed text with changeset rep +- not: reversible +- force final newline of document to be preserved + +- Unicode bad: + - ugly (hard to read) + - more complex to parse + - harder to store and transmit correctly + - doesn't save all that much space anyway + - blows up in size when string-escaped + - embarrassing for API + + +# Attributes: + +An "attribute" is a (key,value) pair such as (author,abc123456) or +(bold,true). Sometimes an attribute is treated as an instruction to +add that attribute, in which case an empty value means to remove it. +So (bold,) removes the "bold" attribute. Attributes are interned and +given numeric IDs, so the number "6" could represent "(bold,true)", +for example. This mapping is stored in an attribute "pool" which may +be shared by multiple changesets. + +Entries in the pool must be unique, so that attributes can be compared +by their IDs. Attribute names cannot contain commas. + +A changeset looks something like the following: + +Z:5g>1|5=2p=v*4*5+1$x + +With the corresponding pool containing these entries: + +... +4 -> (author,1059348573) +5 -> (bold,true) +... + +This changeset, together with the pool, represents inserting +a bold letter "x" into the middle of a line. The string consists of: + +- a letter Z (the "magic character" and format version identifier) +- a series of opcodes (punctuation) and numeric values in base 36 (the + alphanumerics) +- a dollar sign ($) +- a string of characters used by insertion operations (the "char bank") + +If we separate out the operations and convert the numbers to base 10, we get: + +Z :196 >1 |5=97 =31 *4 *5 +1 $"x" + +Here are descriptions of the operations, where capital letters are variables: + +":N" : Source text has length N (must be first op) +">N" : Final text is N (positive) characters longer than source text (must be second op) +"0" : Final text is same length as source text +"+N" : Insert N characters from the bank, none of them newlines +"-N" : Skip over (delete) N characters from the source text, none of them newlines +"=N" : Keep N characters from the source text, none of them newlines +"|L+N" : Insert N characters from the source text, containing L newlines. The last + character inserted MUST be a newline, but not the (new) document's final newline. +"|L-N" : Delete N characters from the source text, containing L newlines. The last + character inserted MUST be a newline, but not the (old) document's final newline. +"|L=N" : Keep N characters from the source text, containing L newlines. The last character + kept MUST be a newline, and the final newline of the document is allowed. +"*I" : Apply attribute I from the pool to the following +, =, |+, or |= command. + In other words, any number of * ops can come before a +, =, or | but not + between a | and the corresponding + or =. + If +, text is inserted having this attribute. If =, text is kept but with + the attribute applied as an attribute addition or removal. + Consecutive attributes must be sorted lexically by (key,value) with key + and value taken as strings. It's illegal to have duplicate keys + for (key,value) pairs that apply to the same text. It's illegal to + have an empty value for a key in the case of an insertion (+), the + pair should just be omitted. + +Characters from the source text that aren't accounted for are assumed to be kept +with the same attributes. + +Additional Constraints: + +- Consecutive +, -, and = ops of the same type that could be combined are not allowed. + Whether combination is possible depends on the attributes of the ops and whether + each is multiline or not. For example, two multiline deletions can never be + consecutive, nor can any insertion come after a non-multiline insertion with the + same attributes. +- "No-op" ops are not allowed, such as deleting 0 characters. However, attribute + applications that don't have any effect are allowed. +- Characters at the end of the source text cannot be explicitly kept with no changes; + if the change doesn't affect the last N characters, those "keep" ops must be left off. +- In any consecutive sequence of insertions (+) and deletions (-) with no keeps (=), + the deletions must come before the insertions. +- The document text before and after will always end with a newline. This policy avoids + a lot of special-casing of the end of the document. If a final newline is + always added when importing text and removed when exporting text, then the + changeset representation can be used to process text files that may or may not + have a final newline. + +Attribution string: + +An "attribution string" is a series of inserts with no deletions or keeps. +For example, "*3+8|1+5" describes the attributes of a string of length 13, +where the first 8 chars have attribute 3 and the next 5 chars have no +attributes, with the last of these 5 chars being a newline. Constraints +apply similar to those affecting changesets, but the restriction about +the final newline of the new document being added doesn't apply. + +Attributes in an attribution string cannot be empty, like "(bold,)", they should +instead be absent. + + + + + +------- +Considerations: + +- composing changesets/attributions with different pools +- generalizing "applyToAttribution" to make "mutateAttributionLines" and "compose" diff --git a/public/doc/v2.2.7/etherpad_basic.png b/public/doc/v2.2.7/etherpad_basic.png new file mode 100644 index 0000000..1b5d32e Binary files /dev/null and b/public/doc/v2.2.7/etherpad_basic.png differ diff --git a/public/doc/v2.2.7/etherpad_demo.gif b/public/doc/v2.2.7/etherpad_demo.gif new file mode 100644 index 0000000..2fa8464 Binary files /dev/null and b/public/doc/v2.2.7/etherpad_demo.gif differ diff --git a/public/doc/v2.2.7/etherpad_full_features.png b/public/doc/v2.2.7/etherpad_full_features.png new file mode 100644 index 0000000..4b0d5f0 Binary files /dev/null and b/public/doc/v2.2.7/etherpad_full_features.png differ diff --git a/public/doc/v2.2.7/etherpad_skin_variants.gif b/public/doc/v2.2.7/etherpad_skin_variants.gif new file mode 100644 index 0000000..0905697 Binary files /dev/null and b/public/doc/v2.2.7/etherpad_skin_variants.gif differ diff --git a/public/doc/v2.2.7/favicon.ico b/public/doc/v2.2.7/favicon.ico new file mode 100644 index 0000000..1a4f8aa Binary files /dev/null and b/public/doc/v2.2.7/favicon.ico differ diff --git a/public/doc/v2.2.7/index.html b/public/doc/v2.2.7/index.html new file mode 100644 index 0000000..45ad187 --- /dev/null +++ b/public/doc/v2.2.7/index.html @@ -0,0 +1,7505 @@ + + + + + + + +Etherpad v2.2.7 Manual & Documentation + + + + + +
+
+

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 src/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:

+
+
+
    +
  • +

    totalUsers (counter)

    +
    • +
  • +

    connects (meter)

    +
    • +
  • +

    disconnects (meter)

    +
    • +
  • +

    pendingEdits (counter)

    +
    • +
  • +

    edits (timer)

    +
    • +
  • +

    failedChangesets (meter)

    +
    • +
  • +

    httpRequests (timer)

    +
    • +
  • +

    http500 (meter)

    +
    • +
  • +

    memoryUsage (gauge)

    +
    • +
+
+
+

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. +
  2. +

    Visit our TWN project page

    +
    3. +
  3. +

    Click on Translate Etherpad lite interface

    +
    4. +
  4. +

    Choose a target language, you’d like to translate our interface to, and hit Fetch

    +
    5. +
  5. +

    Start translating!

    +
    6. +
+
+
+

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

+
+
    +
  • +

    The name of the file must be the language code of the language it contains translations for (see supported lang codes; e.g. en ? English, es ? Spanish…​)

    +
    • +
  • +

    The extension of the file must be .json

    +
    • +
  • +

    The default language is English, so your plugin should always provide en.json

    +
    • +
  • +

    In order to avoid naming conflicts, your message keys should start with the name of your plugin followed by a dot (see below)

    +
    • +
+
+
+

ep_your-plugin/locales/en.json

+
+
+
+
{
+  "ep_your-plugin.h1": "Heading 1"
+}
+
+
+
+

ep_your-plugin/locales/es.json

+
+
+
+
{
+  "ep_your-plugin.h1": "Título 1"
+}
+
+
+
+

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"
+}
+
+
+
+
+
+

Customization for Administrators

+
+

As an Etherpad administrator, it is possible to overwrite core messages as well as messages in plugins. These include error messages, labels, and user instructions. Whereas the localization in the source code is in separate files separated by locale, an administrator’s custom localizations are in settings.json under the customLocaleStrings key, with each locale separated by a sub-key underneath.

+
+
+

For example, let’s say you want to change the text on the "New Pad" button on Etherpad’s home page. If you look in locales/en.json (or locales/en-gb.json) you’ll see the key for this text is "index.newPad". You could add the following to settings.json:

+
+
+
+
  "customLocaleStrings": {
+    "fr": {
+      "index.newPad": "Créer un document"
+    },
+    "en-gb": {
+      "index.newPad": "Create a document"
+    },
+    "en": {
+      "index.newPad": "Create a document"
+    }
+  }
+
+
+
+
+
+
+

Docker

+
+
+

The official Docker image is available on https://hub.docker.com/r/etherpad/etherpad.

+
+
+

Downloading from Docker Hub

+
+

If you are ok downloading a prebuilt image from Docker Hub, these are the commands:

+
+
+
+
# gets the latest published version
+docker pull etherpad/etherpad
+
+# gets a specific version
+docker pull etherpad/etherpad:1.8.0
+
+
+
+
+

Build a personalized container

+
+

If you want to use a personalized settings file, you will have to rebuild your image. +All of the following instructions are as a member of the docker group. +By default, the Etherpad Docker image is built and run in production mode: no development dependencies are installed, and asset bundling speeds up page load time.

+
+
+
+

Building and running with docker compose

+
+

A docker compose file is provided in the project. Please first copy .env.default to .env and adjust the variables to your preference.

+
+
+
+
docker compose up -d # will build and start the docker container on port 9001 with development settings.
+
+
+
+

Starting dev server:

+
+
+
+
docker compose exec app bash -c "./bin/run.sh"
+
+
+
+

For production, please create your own docker compose file and change the target property in the build section to production. In addition, change the NODE_ENV in environment to production. For instance:

+
+
+
+
docker compose -f docker-compose-production.yml up -d
+
+
+
+

For plugins, please add them in the build section under ETHERPAD_PLUGINS, for instance:

+
+
+
+
     args:
+        ETHERPAD_PLUGINS: >-
+          ep_image_upload
+          ep_embedded_hyperlinks2
+          ep_headings2
+          ep_align
+					...
+
+
+
+

Rebuilding with custom settings

+
+

Edit <BASEDIR>/settings.json.docker at your will. When rebuilding the image, this file will be copied inside your image and renamed to settings.json.

+
+
+

Each configuration parameter can also be set via an environment variable, using the syntax "${ENV_VAR}" or "${ENV_VAR:default_value}". For details, refer to settings.json.template.

+
+
+
+

Rebuilding including some plugins

+
+

If you want to install some plugins in your container, it is sufficient to list them in the ETHERPAD_PLUGINS build variable. +The variable value has to be a space separated, double quoted list of plugin names (see examples).

+
+
+

Some plugins will need personalized settings. Just refer to the previous section, and include them in your custom settings.json.docker.

+
+
+
+

Rebuilding including export functionality for DOC/PDF/ODT

+
+

If you want to be able to export your pads to DOC/PDF/ODT files, you can install +either Abiword or Libreoffice via setting a build variable.

+
+
+
Via Abiword
+
+

For installing Abiword, set the INSTALL_ABIWORD build variable to any value.

+
+
+

Also, you will need to configure the path to the abiword executable +via setting the abiword property in <BASEDIR>/settings.json.docker to +/usr/bin/abiword or via setting the environment variable ABIWORD to +/usr/bin/abiword.

+
+
+
+
Via Libreoffice
+
+

For installing Libreoffice instead, set the INSTALL_SOFFICE build variable +to any value.

+
+
+

Also, you will need to configure the path to the libreoffice executable +via setting the soffice property in <BASEDIR>/settings.json.docker to +/usr/bin/soffice or via setting the environment variable SOFFICE to +/usr/bin/soffice.

+
+
+
+
+

Examples

+
+

Build a Docker image from the currently checked-out code:

+
+
+
+
docker build --tag <YOUR_USERNAME>/etherpad .
+
+
+
+

Include two plugins in the container:

+
+
+
+
docker build --build-arg ETHERPAD_PLUGINS="ep_comments_page ep_author_neat" --tag <YOUR_USERNAME>/etherpad .
+
+
+
+
+
+

Running your instance:

+
+

To run your instance:

+
+
+
+
docker run --detach --publish <DESIRED_PORT>:9001 <YOUR_USERNAME>/etherpad
+
+
+
+

And point your browser to http://<YOUR_IP>:<DESIRED_PORT>;

+
+
+
+

Options available by default

+
+

The settings.json.docker available by default allows to control almost every setting via environment variables.

+
+
+

General

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Variable

Description

Default

TITLE

The name of the instance

Etherpad

FAVICON

favicon default name, or a fully specified URL to your own favicon

favicon.ico

DEFAULT_PAD_TEXT

The default text of a pad

Welcome to Etherpad! 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! Get involved with Etherpad at https://etherpad.org

IP

IP which etherpad should bind at. Change to :: for IPv6

0.0.0.0

PORT

port which etherpad should bind at

9001

ADMIN_PASSWORD

the password for the admin user (leave unspecified if you do not want to create it)

USER_PASSWORD

the password for the first user user (leave unspecified if you do not want to create it)

+
+
+

Database

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Variable

Description

Default

DB_TYPE

a database supported by https://www.npmjs.com/package/ueberdb2

not set, thus will fall back to DirtyDB (please choose one instead)

DB_HOST

the host of the database

DB_PORT

the port of the database

DB_NAME

the database name

DB_USER

a database user with sufficient permissions to create tables

DB_PASS

the password for the database username

DB_CHARSET

the character set for the tables (only required for MySQL)

DB_FILENAME

in case DB_TYPE is DirtyDB or sqlite, the database file.

var/dirty.db, var/etherpad.sq3

+
+

If your database needs additional settings, you will have to use a personalized settings.json.docker and rebuild the container (or otherwise put the updated settings.json inside your image).

+
+
+
+

Pad Options

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Variable

Description

Default

PAD_OPTIONS_NO_COLORS

false

PAD_OPTIONS_SHOW_CONTROLS

true

PAD_OPTIONS_SHOW_CHAT

true

PAD_OPTIONS_SHOW_LINE_NUMBERS

true

PAD_OPTIONS_USE_MONOSPACE_FONT

false

PAD_OPTIONS_USER_NAME

null

PAD_OPTIONS_USER_COLOR

null

PAD_OPTIONS_RTL

false

PAD_OPTIONS_ALWAYS_SHOW_CHAT

false

PAD_OPTIONS_CHAT_AND_USERS

false

PAD_OPTIONS_LANG

null

+
+
+

Shortcuts

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Variable

Description

Default

PAD_SHORTCUTS_ENABLED_ALT_F9

focus on the File Menu and/or editbar

true

PAD_SHORTCUTS_ENABLED_ALT_C

focus on the Chat window

true

PAD_SHORTCUTS_ENABLED_CMD_S

save a revision

true

PAD_SHORTCUTS_ENABLED_CMD_Z

undo/redo

true

PAD_SHORTCUTS_ENABLED_CMD_Y

redo

true

PAD_SHORTCUTS_ENABLED_CMD_I

italic

true

PAD_SHORTCUTS_ENABLED_CMD_B

bold

true

PAD_SHORTCUTS_ENABLED_CMD_U

underline

true

PAD_SHORTCUTS_ENABLED_CMD_H

backspace

true

PAD_SHORTCUTS_ENABLED_CMD_5

strike through

true

PAD_SHORTCUTS_ENABLED_CMD_SHIFT_1

ordered list

true

PAD_SHORTCUTS_ENABLED_CMD_SHIFT_2

shows a gritter popup showing a line author

true

PAD_SHORTCUTS_ENABLED_CMD_SHIFT_L

unordered list

true

PAD_SHORTCUTS_ENABLED_CMD_SHIFT_N

ordered list

true

PAD_SHORTCUTS_ENABLED_CMD_SHIFT_C

clear authorship

true

PAD_SHORTCUTS_ENABLED_DELETE

true

PAD_SHORTCUTS_ENABLED_RETURN

true

PAD_SHORTCUTS_ENABLED_ESC

in mozilla versions 14-19 avoid reconnecting pad

true

PAD_SHORTCUTS_ENABLED_TAB

indent

true

PAD_SHORTCUTS_ENABLED_CTRL_HOME

scroll to top of pad

true

PAD_SHORTCUTS_ENABLED_PAGE_UP

true

PAD_SHORTCUTS_ENABLED_PAGE_DOWN

true

+
+
+

Skins

+
+

You can use the UI skin variants builder at /p/test#skinvariantsbuilder

+
+
+

For the colibris skin only, you can choose how to render the three main containers: + * toolbar (top menu with icons) + * editor (containing the text of the pad) + * background (area outside of editor, mostly visible when using page style)

+
+
+

For each of the 3 containers you can choose 4 color combinations: + * super-light + * light + * dark + * super-dark

+
+
+

For the editor container, you can also make it full width by adding full-width-editor variant (by default editor is rendered as a page, with a max-width of 900px).

+
+ +++++ + + + + + + + + + + + + + + + + + +

Variable

Description

Default

SKIN_NAME

either no-skin, colibris or an existing directory under src/static/skins

colibris

SKIN_VARIANTS

multiple skin variants separated by spaces

super-light-toolbar super-light-editor light-background

+
+
+

Logging

+ +++++ + + + + + + + + + + + + + + + + + +

Variable

Description

Default

LOGLEVEL

valid values are DEBUG, INFO, WARN and ERROR

INFO

DISABLE_IP_LOGGING

Privacy: disable IP logging

false

+
+
+

Advanced

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Variable

Description

Default

COOKIE_KEY_ROTATION_INTERVAL

How often (ms) to rotate in a new secret for signing cookies

86400000 (1 day)

COOKIE_SAME_SITE

Value of the SameSite cookie property.

"Lax"

COOKIE_SESSION_LIFETIME

How long (ms) a user can be away before they must log in again.

864000000 (10 days)

COOKIE_SESSION_REFRESH_INTERVAL

How often (ms) to write the latest cookie expiration time.

86400000 (1 day)

SHOW_SETTINGS_IN_ADMIN_PAGE

hide/show the settings.json in admin page

true

TRUST_PROXY

set to true if you are using a reverse proxy in front of Etherpad (for example: Traefik for SSL termination via Let’s Encrypt). This will affect security and correctness of the logs if not done

false

IMPORT_MAX_FILE_SIZE

maximum allowed file size when importing a pad, in bytes.

52428800 (50 MB)

IMPORT_EXPORT_MAX_REQ_PER_IP

maximum number of import/export calls per IP.

10

IMPORT_EXPORT_RATE_LIMIT_WINDOW

the call rate for import/export requests will be estimated in this time window (in milliseconds)

90000

COMMIT_RATE_LIMIT_DURATION

duration of the rate limit window for commits by individual users/IPs (in seconds)

1

COMMIT_RATE_LIMIT_POINTS

maximum number of changes per IP to allow during the rate limit window

10

SUPPRESS_ERRORS_IN_PAD_TEXT

Should we suppress errors from being visible in the default Pad Text?

`false

REQUIRE_SESSION

If this option is enabled, a user must have a session to access pads. This effectively allows only group pads to be accessed.

false

EDIT_ONLY

Users may edit pads but not create new ones. Pad creation is only via the API. This applies both to group pads and regular pads.

false

MINIFY

If true, all css & js will be minified before sending to the client. This will improve the loading performance massively, but makes it difficult to debug the javascript/css

true

MAX_AGE

How long may clients use served javascript code (in seconds)? Not setting this may cause problems during deployment. Set to 0 to disable caching.

21600 (6 hours)

ABIWORD

Absolute path to the Abiword executable. Abiword is needed to get advanced import/export features of pads. Setting it to null disables Abiword and will only allow plain text and HTML import/exports.

null

SOFFICE

This is the absolute path to the soffice executable. LibreOffice can be used in lieu of Abiword to export pads. Setting it to null disables LibreOffice exporting.

null

ALLOW_UNKNOWN_FILE_ENDS

Allow import of file types other than the supported ones: txt, doc, docx, rtf, odt, html & htm

true

REQUIRE_AUTHENTICATION

This setting is used if you require authentication of all users. Note: "/admin" always requires authentication.

false

REQUIRE_AUTHORIZATION

Require authorization by a module, or a user with is_admin set, see below.

false

AUTOMATIC_RECONNECTION_TIMEOUT

Time (in seconds) to automatically reconnect pad when a "Force reconnect" message is shown to user. Set to 0 to disable automatic reconnection.

0

FOCUS_LINE_PERCENTAGE_ABOVE

Percentage of viewport height to be additionally scrolled. e.g. 0.5, to place caret line in the middle of viewport, when user edits a line above of the viewport. Set to 0 to disable extra scrolling

0

FOCUS_LINE_PERCENTAGE_BELOW

Percentage of viewport height to be additionally scrolled. e.g. 0.5, to place caret line in the middle of viewport, when user edits a line below of the viewport. Set to 0 to disable extra scrolling

0

FOCUS_LINE_PERCENTAGE_ARROW_UP

Percentage of viewport height to be additionally scrolled when user presses arrow up in the line of the top of the viewport. Set to 0 to let the scroll to be handled as default by Etherpad

0

FOCUS_LINE_DURATION

Time (in milliseconds) used to animate the scroll transition. Set to 0 to disable animation

0

FOCUS_LINE_CARET_SCROLL

Flag to control if it should scroll when user places the caret in the last line of the viewport

false

SOCKETIO_MAX_HTTP_BUFFER_SIZE

The maximum size (in bytes) of a single message accepted via Socket.IO. If a client sends a larger message, its connection gets closed to prevent DoS (memory exhaustion) attacks.

50000

LOAD_TEST

Allow Load Testing tools to hit the Etherpad Instance. WARNING: this will disable security on the instance.

false

DUMP_ON_UNCLEAN_EXIT

Enable dumping objects preventing a clean exit of Node.js. WARNING: this has a significant performance impact.

false

EXPOSE_VERSION

Expose Etherpad version in the web interface and in the Server http header. Do not enable on production machines.

false

+
+
+

Examples

+
+

Use a Postgres database, no admin user enabled:

+
+
+
+
docker run -d \
+	--name etherpad         \
+	-p 9001:9001            \
+	-e 'DB_TYPE=postgres'   \
+	-e 'DB_HOST=db.local'   \
+	-e 'DB_PORT=4321'       \
+	-e 'DB_NAME=etherpad'   \
+	-e 'DB_USER=dbusername' \
+	-e 'DB_PASS=mypassword' \
+	etherpad/etherpad
+
+
+
+

Run enabling the administrative user admin:

+
+
+
+
docker run -d \
+	--name etherpad \
+	-p 9001:9001 \
+	-e 'ADMIN_PASSWORD=supersecret' \
+	etherpad/etherpad
+
+
+
+

Run a test instance running DirtyDB on a persistent volume:

+
+
+
+
docker run -d \
+	-v etherpad_data:/opt/etherpad-lite/var \
+	-p 9001:9001 \
+	etherpad/etherpad
+
+
+
+
+
+
+
+

Skins

+
+
+

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

+
+
+
    +
  • +

    index.js: javascript that will be run in /

    +
    • +
  • +

    index.css: stylesheet affecting /

    +
    • +
  • +

    pad.js: javascript that will be run in /p/:padid

    +
    • +
  • +

    pad.css: stylesheet affecting /p/:padid

    +
    • +
  • +

    timeslider.js: javascript that will be run in /p/:padid/timeslider

    +
    • +
  • +

    timeslider.css: stylesheet affecting /p/:padid/timeslider

    +
    • +
  • +

    favicon.ico: overrides the default favicon

    +
    • +
  • +

    robots.txt: overrides the default robots.txt

    +
    • +
+
+
+

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

+
+
+

Since Etherpad 1.7.5, two skins are included:

+
+
+
    +
  • +

    no-skin: an empty skin, leaving the default Etherpad appearance unchanged, that you can use as a guidance to develop your own.

    +
    • +
  • +

    colibris: a new, experimental skin, that will become the default in Etherpad 2.0.

    +
    • +
+
+
+
+
+

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 and will auto-focus on Line 4.

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

showLineNumbers

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true

+
+
+
+

showControls

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true

+
+
+
+

showChat

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true

+
+
+
+

useMonospaceFont

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: false

+
+
+
+

userName

+
+
    +
  • +

    String

    +
    • +
+
+
+

Default: "unnamed"

+
+
+

Example: userName=Etherpad%20User

+
+
+
+

userColor

+
+
    +
  • +

    String (css hex color value)

    +
    • +
+
+
+

Default: randomly chosen by pad server

+
+
+

Example: userColor=%23ff9900

+
+
+
+

noColors

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: false

+
+
+
+

alwaysShowChat

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: false

+
+
+
+

lang

+
+
    +
  • +

    String

    +
    • +
+
+
+

Default: en

+
+
+

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

+
+
+
+

rtl

+
+
    +
  • +

    Boolean

    +
    • +
+
+
+

Default: true +Displays pad text from right to left.

+
+
+
+

#L

+
+
    +
  • +

    Int

    +
    • +
+
+
+

Default: 0 +Focuses pad at specific line number and places caret at beginning of this line +Special note: Is not a URL parameter but instead of a Hash value

+
+
+
+
+
+

HTTP API

+
+
+

What can I do with this API?

+
+

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

+
+
+
    +
  • +

    create/delete pads

    +
    • +
  • +

    grant/forbid access to pads

    +
    • +
  • +

    get/set pad content

    +
    • +
+
+
+

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.

+
+
+

OpenAPI

+
+

OpenAPI (formerly swagger) definitions are exposed under /api/openapi.json (latest) and /api/2.2.7/openapi.json. You can use official tools like Swagger Editor to view and explore them.

+
+
+
+
+

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

+
+
+

The current version can be queried via /api.

+
+
+
+

Request Format

+
+

The API is accessible via HTTP. Starting from 1.8, API endpoints can be invoked indifferently via GET or POST.

+
+
+

The URL of the HTTP request is of the form: /api/$APIVERSION/$FUNCTIONNAME. $APIVERSION depends on the endpoint you want to use. Depending on the verb you use (GET or POST) parameters can be passed differently.

+
+
+

When invoking via GET (mandatory until 1.7.5 included), parameters must be included in the query string (example: /api/$APIVERSION/$FUNCTIONNAME?apikey=<APIKEY>&param1=value1). Please note that starting with nodejs 8.14+ the total size of HTTP request headers has been capped to 8192 bytes. This limits the quantity of data that can be sent in an API request.

+
+
+

Starting from Etherpad 1.8 it is also possible to invoke the HTTP API via POST. In this case, querystring parameters will still be accepted, but any parameter with the same name sent via POST will take precedence. If you need to send large chunks of text (for example, for setText()) it is advisable to invoke via POST.

+
+
+

Example with cURL using GET (toy example, no encoding):

+
+
+
+
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname&text=this_text_will_NOT_be_encoded_by_curl_use_next_example"
+
+
+
+

Example with cURL using GET (better example, encodes text):

+
+
+
+
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname" --get --data-urlencode "text=Text sent via GET with proper encoding. For big documents, please use POST"
+
+
+
+

Example with cURL using POST:

+
+
+
+
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname" --data-urlencode "text=Text sent via POST with proper encoding. For big texts (>8 KB), use this method"
+
+
+
+
+

Response Format

+
+

Responses are valid JSON in the following format:

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

    code a return code

    +
    • +
  • +

    0 everything ok

    +
    • +
  • +

    1 wrong parameters

    +
    • +
  • +

    2 internal error

    +
    • +
  • +

    3 no such function

    +
    • +
  • +

    4 no or wrong API Key

    +
    • +
  • +

    message a status message. It’s ok if everything is fine, else it contains an error message

    +
    • +
  • +

    data the payload

    +
    • +
+
+
+
+

Overview

+
+
+API Overview +
+
+
+
+
+

Data Types

+
+
    +
  • +

    groupID a string, the unique id of a group. Format is g.16RANDOMCHARS, for example g.s8oes9dhwrvt0zif

    +
    • +
  • +

    sessionID a string, the unique id of a session. Format is s.16RANDOMCHARS, for example s.s8oes9dhwrvt0zif

    +
    • +
  • +

    authorID a string, the unique id of an author. Format is a.16RANDOMCHARS, for example a.s8oes9dhwrvt0zif

    +
    • +
  • +

    readOnlyID a string, the unique id of a readonly relation to a pad. Format is r.16RANDOMCHARS, for example r.s8oes9dhwrvt0zif

    +
    • +
  • +

    padID a string, format is GROUPID$PADNAME, for example the pad test of group g.s8oes9dhwrvt0zif has padID g.s8oes9dhwrvt0zif$test

    +
    • +
+
+
+

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.

+
+
+
+
+

API Methods

+
+

Groups

+
+

Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test

+
+
+
createGroup()
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

creates a new group

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
+
+
+
+
createGroupIfNotExistsFor(groupMapper)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

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)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

deletes a group

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"groupID does not exist", data: null}

    +
    • +
+
+
+
+
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], [authorId])
+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

creates a new pad in this group

+
+
+

Example returns:

+
+
+
    +
  • +

    {code: 0, message:"ok", data: {padID: "g.s8oes9dhwrvt0zif$test"}

    +
    • +
  • +

    {code: 1, message:"padName does already exist", data: null}

    +
    • +
  • +

    {code: 1, message:"groupID does not exist", data: null}

    +
    • +
+
+
+
+
listAllGroups()
+
+
    +
  • +

    API >= 1.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])
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

creates a new author

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
+
+
+
+
createAuthorIfNotExistsFor(authorMapper [, name])
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

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)
+
+
    +
  • +

    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)
+
+
    +
  • +

    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

+
+
+
+
+

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)
+
+
    +
  • +

    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)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

deletes a session

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"sessionID does not exist", data: null}

    +
    • +
+
+
+
+
getSessionInfo(sessionID)
+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

returns information 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)
+
+
    +
  • +

    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)
+
+
    +
  • +

    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}

    +
    • +
+
+
+
+
+

Pad Content

+
+

Pad content can be updated and retrieved through the API

+
+
+
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, [authorId])
+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

Sets the text of a pad.

+
+
+

If your text is long (>8 KB), please invoke via POST and include text parameter in the body of the request, not in the URL (since Etherpad 1.8).

+
+
+

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, [authorId])
+
+
    +
  • +

    API >= 1.2.13

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

Appends text to a pad.

+
+
+

If your text is long (>8 KB), please invoke via POST and include text parameter in the body of the request, not in the URL (since Etherpad 1.8).

+
+
+

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])
+
+
    +
  • +

    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}

    +
    • +
+
+
+
+
setHTML(padID, html, [authorId])
+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

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

+
+
+

If html is long (>8 KB), please invoke via POST and include html parameter in the body of the request, not in the URL (since Etherpad 1.8).

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+
getAttributePool(padID)
+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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])
+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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 https://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)
+
+
    +
  • +

    API >= 1.2.7

    +
    • +
+
+
+

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://etherpad.org\">http://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, [authorId])
+
+
    +
  • +

    API >= 1.2.11

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

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])
+
+
    +
  • +

    API >= 1.2.7

    +
    • +
+
+
+

returns

+
+
+
    +
  • +

    a part of the chat history, when start and end are given

    +
    • +
  • +

    the whole chat history, when no extra parameters are given

    +
    • +
+
+
+

Example returns:

+
+
+
    +
  • +

    {"code":0,"message":"ok","data":{"messages":[{"text":"foo","userId":"a.foo","time":1359199533759,"userName":"test"},{"text":"bar","userId":"a.foo","time":1359199534622,"userName":"test"}]}}

    +
    • +
  • +

    {code: 1, message:"start is higher or equal to the current chatHead", data: null}

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+
getChatHead(padID)
+
+
    +
  • +

    API >= 1.2.7

    +
    • +
+
+
+

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

+
+
+

Example returns:

+
+
+
    +
  • +

    {code: 0, message:"ok", data: {chatHead: 42}}

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+
appendChatMessage(padID, text, authorID [, time])
+
+
    +
  • +

    API >= 1.2.12

    +
    • +
+
+
+

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

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"text is no string", data: null}

    +
    • +
+
+
+
+
+
+

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], [authorId])

+
+
    +
  • +

    API >= 1

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

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)

+
+
    +
  • +

    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}

    +
    • +
+
+
+
+

getSavedRevisionsCount(padID)

+
+
    +
  • +

    API >= 1.2.11

    +
    • +
+
+
+

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)

+
+
    +
  • +

    API >= 1.2.11

    +
    • +
+
+
+

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

+
+
    +
  • +

    API >= 1.2.11

    +
    • +
+
+
+

saves a revision

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+

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)

+
+
    +
  • +

    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,"id":"a.n4gEeMLsvg12452n"},{"colorId":"#d9a9cd","name":"Hmmm","timestamp":1345228796042,"id":"a.n4gEeMLsvg12452n"}]}}

    +
    • +
  • +

    {code: 0, message:"ok", data: {padUsers: []}}

    +
    • +
+
+
+
+

deletePad(padID)

+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

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

+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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}

    +
    • +
+
+
+
+

copyPadWithoutHistory(sourceID, destinationID, [force=false], [authorId])

+
+
    +
  • +

    API >= 1.2.15

    +
    • +
  • +

    authorId in API >= 1.3.0

    +
    • +
+
+
+

copies a pad without copying the history and chat. If force is true and the destination pad exists, it will be overwritten. +Note that all the revisions will be lost! In most of the cases one should use copyPad API instead.

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
+
+
+
+

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

+
+
    +
  • +

    API >= 1.2.8

    +
    • +
+
+
+

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)

+
+
    +
  • +

    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}

    +
    • +
+
+
+
+

getPadID(readOnlyID)

+
+
    +
  • +

    API >= 1.2.10

    +
    • +
+
+
+

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)

+
+
    +
  • +

    API >= 1

    +
    • +
+
+
+

sets a boolean for the public status of a group pad

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
  • +

    {code: 1, message:"padID does not exist", data: null}

    +
    • +
  • +

    {code: 1, message:"You can only get/set the publicStatus of pads that belong to a group", data: null}

    +
    • +
+
+
+
+

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}

    +
    • +
  • +

    {code: 1, message:"You can only get/set the publicStatus of pads that belong to a group", data: null}

    +
    • +
+
+
+
+

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)

+
+
    +
  • +

    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)

+
+
    +
  • +

    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}

    +
    • +
+
+
+
+

checkToken()

+
+
    +
  • +

    API >= 1.2

    +
    • +
+
+
+

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

+
+
    +
  • +

    API >= 1.2.1

    +
    • +
+
+
+

lists all pads on this epl instance

+
+
+

Example returns:

+
+
+
    +
  • +

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

    +
    • +
+
+
+
+

Global

+
+
getStats()
+
+
    +
  • +

    API >= 1.2.14

    +
    • +
+
+
+

get stats of the etherpad instance

+
+
+

Example returns:

+
+
+
    +
  • +

    {"code":0,"message":"ok","data":{"totalPads":3,"totalSessions": 2,"totalActivePads": 1}}

    +
    • +
+
+
+
+
+
+
+
+

Hooks

+
+
+

A hook function is registered with a hook via the plugin’s ep.json file. See +the Plugins section for details. A hook may have many registered functions from +different plugins.

+
+
+

Some hooks call their registered functions one at a time until one of them +returns a value. Others always call all of their registered functions and +combine the results (if applicable).

+
+
+

Registered hook functions

+
+

Note: The documentation in this section applies to every hook unless the +hook-specific documentation says otherwise.

+
+
+

Arguments

+
+

Hook functions are called with three arguments:

+
+
+
    +
  1. +

    hookName - The name of the hook being invoked.

    +
    2. +
  2. +

    context - An object with some relevant information about the context of the +call. See the hook-specific documentation for details.

    +
    3. +
  3. +

    cb - For asynchronous operations this callback can be called to signal +completion and optionally provide a return value. The callback takes a single +argument, the meaning of which depends on the hook (see the "Return values" +section for general information that applies to most hooks). This callback +always returns undefined.

    +
    4. +
+
+
+
+

Expected behavior

+
+

The presence of a callback parameter suggests that every hook function can run +asynchronously. While that is the eventual goal, there are some legacy hooks +that expect their hook functions to provide a value synchronously. For such +hooks, the hook functions must do one of the following:

+
+
+
    +
  • +

    Call the callback with a non-Promise value (undefined is acceptable) and +return undefined, in that order.

    +
    • +
  • +

    Return a non-Promise value other than undefined (null is acceptable) and +never call the callback. Note that async functions always return a +Promise, so they must never be used for synchronous hooks.

    +
    • +
  • +

    Only have two parameters (hookName and context) and return any non-Promise +value (undefined is acceptable).

    +
    • +
+
+
+

For hooks that permit asynchronous behavior, the hook functions must do one or +more of the following:

+
+
+
    +
  • +

    Return undefined and call the callback, in either order.

    +
    • +
  • +

    Return something other than undefined (null is acceptable) and never call +the callback. Note that async functions always return a Promise, so they +must never call the callback.

    +
    • +
  • +

    Only have two parameters (hookName and context).

    +
    • +
+
+
+

Note that the acceptable behaviors for asynchronous hook functions is a superset +of the acceptable behaviors for synchronous hook functions.

+
+
+ + + + + +
+
Warning
+		 +The number of parameters is determined by examining +Function.length, +which does not count default parameters +or "rest" parameters. +To avoid problems, do not use default or rest parameters when defining hook +functions. +
+
+
+
+

Return values

+
+

A hook function can provide a value to Etherpad in one of the following ways:

+
+
+
    +
  • +

    Pass the desired value as the first argument to the callback.

    +
    • +
  • +

    Return the desired value directly. The value must not be undefined unless +the hook function only has two parameters. (Hook functions with three +parameters that want to provide undefined should instead use the callback.)

    +
    • +
  • +

    For hooks that permit asynchronous behavior, return a Promise that resolves to +the desired value.

    +
    • +
  • +

    For hooks that permit asynchronous behavior, pass a Promise that resolves to +the desired value as the first argument to the callback.

    +
    • +
+
+
+

Examples:

+
+
+
+
exports.exampleOne = (hookName, context, callback) => {
+  return 'valueOne';
+};
+
+exports.exampleTwo = (hookName, context, callback) => {
+  callback('valueTwo');
+  return;
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleThree = (hookName, context, callback) => {
+  return new Promise('valueThree');
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleFour = (hookName, context, callback) => {
+  callback(new Promise('valueFour'));
+  return;
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleFive = async (hookName, context) => {
+  // Note that this function is async, so it actually returns a Promise that
+  // is resolved to 'valueFive'.
+  return 'valueFive';
+};
+
+
+
+

Etherpad collects the values provided by the hook functions into an array, +filters out all undefined values, then flattens the array one level. +Flattening one level makes it possible for a hook function to behave as if it +were multiple separate hook functions.

+
+
+

For example: Suppose a hook has eight registered functions that return the +following values: 1, [2], ['3a', '3b'] [[4]], undefined, +[undefined], [], and null. The value returned to the caller of the hook is +[1, 2, '3a', '3b', [4], undefined, null].

+
+
+
+
+
+
+

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. +
  2. +

    cls - The class of the current block element (useful for styling)

    +
    3. +
+
+
+

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. +
  2. +

    cls - The class of the current block element (useful for styling)

    +
    3. +
+
+
+

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. +
  2. +

    cls - The class of the current element (useful for styling)

    +
    3. +
+
+
+

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

    +
    2. +
+
+
+

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. +
  2. +

    key - the current attribute being processed

    +
    3. +
  3. +

    value - the value of the attribute being processed

    +
    4. +
+
+
+

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. +
  2. +

    browser - an object indicating which browser is accessing the page

    +
    3. +
+
+
+

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

    +
    2. +
+
+
+

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. +
  2. +

    editorInfo - information about the user who is making the change

    +
    3. +
  3. +

    rep - information about where the change is being made

    +
    4. +
  4. +

    documentAttributeManager - information about attributes in the document (this +is a mystery to me)

    +
    5. +
+
+
+

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. +
  2. +

    rep - information about where the user’s cursor is

    +
    3. +
  3. +

    documentAttributeManager - some kind of magic

    +
    4. +
+
+
+

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. +
  2. +

    clientVars - Object containing client-side configuration such as author ID +and plugin settings. Your plugin can manipulate this object via the +clientVars server-side hook.

    +
    3. +
  3. +

    pad - the pad object of the current pad.

    +
    4. +
+
+
+
+

postToolbarInit

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    ace - the ace object that is applied to this editor.

    +
    2. +
  2. +

    toolbar - Editbar instance. See below for the Editbar documentation.

    +
    3. +
+
+
+

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.

+
+
+
+

goToRevisionEvent

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    rev - The newRevision

    +
    2. +
+
+
+

This hook gets fired both on timeslider load (as timeslider shows a new +revision) and when the new revision is showed to a user. There doesn’t appear to +be any example available of this particular hook being used.

+
+
+
+

userJoinOrUpdate

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    info - the user information

    +
    2. +
+
+
+

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

+
+
+

This hook runs on the client side whenever a chat message is received from the +server. It can be used to create different notifications for chat messages. Hook +functions can modify the author, authorName, duration, rendered, +sticky, text, and timeStr context properties to change how the message is +processed. The text and timeStr properties may contain HTML and come +pre-sanitized; plugins should be careful to sanitize any added user input to +avoid introducing an XSS vulnerability.

+
+
+

Context properties:

+
+
+
    +
  • +

    authorName: The display name of the user that wrote the message.

    +
    • +
  • +

    author: The author ID of the user that wrote the message.

    +
    • +
  • +

    text: Sanitized message HTML, with URLs wrapped like <a +href="url">url</a>. (Note that message.text is not sanitized or processed +in any way.)

    +
    • +
  • +

    message: The raw message object as received from the server, except with +time correction and a default authorId property if missing. Plugins must not +modify this object. Warning: Unlike text, message.text is not +pre-sanitized or processed in any way.

    +
    • +
  • +

    rendered - Used to override the default message rendering. Initially set to +null. If the hook function sets this to a DOM element object or a jQuery +object, then that object will be used as the rendered message UI. Otherwise, +if this is set to null, then Etherpad will render a default UI for the +message using the other context properties.

    +
    • +
  • +

    sticky (boolean): Whether the gritter notification should fade out on its +own or just sit there until manually closed.

    +
    • +
  • +

    timestamp: When the chat message was sent (milliseconds since epoch), +corrected using the difference between the local clock and the server’s clock.

    +
    • +
  • +

    timeStr: The message timestamp as a formatted string.

    +
    • +
  • +

    duration: How long (in milliseconds) to display the gritter notification (0 +to disable).

    +
    • +
+
+
+
+

chatSendMessage

+
+

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

+
+
+

This hook runs on the client side whenever the user sends a new chat message. +Plugins can mutate the message object to change the message text or add metadata +to control how the message will be rendered by the chatNewMessage hook.

+
+
+

Context properties:

+
+
+
    +
  • +

    message: The message object that will be sent to the Etherpad server.

    +
    • +
+
+
+
+

collectContentPre

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    cc - the contentcollector object

    +
    2. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    styl - the style applied to the node (probably CSS) — Note the typo

    +
    5. +
  5. +

    cls - the HTML class string of the node

    +
    6. +
+
+
+

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. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    style - the style applied to the node (probably CSS)

    +
    5. +
  5. +

    cls - the HTML class string of the node

    +
    6. +
  6. +

    node - the node being modified

    +
    7. +
+
+
+

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. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    style - the style applied to the node (probably CSS)

    +
    5. +
  5. +

    cls - the HTML class string of the node

    +
    6. +
+
+
+

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)

    +
    2. +
+
+
+

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. +
  2. +

    editorInfo - information about the user who is making the change

    +
    3. +
  3. +

    rep - information about where the change is being made

    +
    4. +
  4. +

    root - the span element of the current line

    +
    5. +
  5. +

    point - the starting/ending element where the cursor highlights

    +
    6. +
  6. +

    documentAttributeManager - information about attributes in the document

    +
    7. +
+
+
+

This hook is provided to allow a plugin to turn DOM node selection into

+
+
+
+

aceKeyEvent

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    callstack - a bunch of information about the current action

    +
    2. +
  2. +

    editorInfo - information about the user who is making the change

    +
    3. +
  3. +

    rep - information about where the change is being made

    +
    4. +
  4. +

    documentAttributeManager - information about attributes in the document

    +
    5. +
  5. +

    evt - the fired event

    +
    6. +
+
+
+

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. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
  4. +

    text - the text for that line

    +
    5. +
+
+
+

This hook allows you to validate/manipulate the text before it’s sent to the +server side. To change the text, either:

+
+
+
    +
  • +

    Set the text context property to the desired value and return undefined.

    +
    • +
  • +

    (Deprecated) Return a string. If a hook function changes the text context +property, the return value is ignored. If no hook function changes text but +multiple hook functions return a string, the first one wins.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.collectContentLineText = (hookName, context) => {
+  context.text = tweakText(context.text);
+};
+
+
+
+
+

collectContentLineBreak

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    cc - the contentcollector object

    +
    2. +
  2. +

    state - the current state of the change being made

    +
    3. +
  3. +

    tname - the tag name of this node currently being processed

    +
    4. +
+
+
+

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. +
  2. +

    text - the line text

    +
    3. +
  3. +

    class - line class

    +
    4. +
+
+
+

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. +
  2. +

    outerDynamicCSS - css manager for outer ace

    +
    3. +
  3. +

    parentDynamicCSS - css manager for parent document

    +
    4. +
  4. +

    info - author style info

    +
    5. +
  5. +

    author - author info

    +
    6. +
  6. +

    authorSelector - css selector for author span in inner ace

    +
    7. +
+
+
+

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. +
  2. +

    documentAttributeManager - information about attributes in the document

    +
    3. +
+
+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    settings - the settings object

    +
    2. +
+
+
+

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

+
+
+
+

shutdown

+
+

Called from: src/node/server.ts

+
+
+

Things in context: None

+
+
+

This hook runs before shutdown. Use it to stop timers, close sockets and files, +flush buffers, etc. The database is not available while this hook is running. +The shutdown function must not block for long because there is a short timeout +before the process is forcibly terminated.

+
+
+

The shutdown function must return a Promise, which must resolve to undefined. +Returning callback(value) will return a Promise that is resolved to value.

+
+
+

Example:

+
+
+
+
// using an async function
+exports.shutdown = async (hookName, context) => {
+  await flushBuffers();
+};
+
+
+
+
+

pluginUninstall

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    plugin_name - self-explanatory

    +
    2. +
+
+
+

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

    +
    2. +
+
+
+

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

+
+
+

Run during startup after the named plugin is initialized.

+
+
+

Context properties:

+
+
+
    +
  • +

    logger: An object with the following console-like methods: debug, +info, log, warn, error.

    +
    • +
+
+
+
+

expressPreSession

+
+

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

+
+
+

Called during server startup just before the +express-session middleware is +added to the Express Application object. Use this hook to add route handlers or +middleware that executes before express-session state is created and +authentication is performed. This is useful for creating public endpoints that +don’t spam the database with new express-session records or trigger +authentication.

+
+
+

WARNING: All handlers registered during this hook run before the built-in +authentication checks, so any handled endpoints will be public unless the +handler itself authenticates the user.

+
+
+

Context properties:

+
+
+ +
+
+

Example:

+
+
+
+
exports.expressPreSession = async (hookName, {app}) => {
+  app.get('/hello-world', (req, res) => res.send('hello world'));
+};
+
+
+
+
+

expressConfigure

+
+

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

+
+
+

Called during server startup just after the +express-session middleware is +added to the Express Application object. Use this hook to add route handlers or +middleware that executes after express-session state is created and +authentication is performed.

+
+
+

Context properties:

+
+
+ +
+
+
+

expressCreateServer

+
+

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

+
+
+

Identical to the expressConfigure hook (the two run in parallel with each +other) except this hook’s context includes the HTTP Server object.

+
+
+

Context properties:

+
+
+ +
+
+
+

expressCloseServer

+
+

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

+
+
+

Things in context: Nothing

+
+
+

This hook is called when the HTTP server is closing, which happens during +shutdown (see the shutdown hook) and when the server restarts (e.g., when a +plugin is installed via the /admin/plugins page). The HTTP server may or may +not already be closed when this hook executes.

+
+
+

Example:

+
+
+
+
exports.expressCloseServer = async () => {
+  await doSomeCleanup();
+};
+
+
+
+
+

eejsBlock_`<name>`

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    content - the content of the block

    +
    2. +
+
+
+

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:

+
+
+
    +
  • +

    htmlHead - after <html> and immediately before the title tag

    +
    • +
  • +

    styles - the style `<link>`s

    +
    • +
  • +

    body - the contents of the body tag

    +
    • +
  • +

    editbarMenuLeft - the left tool bar (consider using the toolbar controller instead of manually adding html here)

    +
    • +
  • +

    editbarMenuRight - right tool bar

    +
    • +
  • +

    afterEditbar - allows you to add stuff immediately after the toolbar

    +
    • +
  • +

    userlist - the contents of the userlist dropdown

    +
    • +
  • +

    loading - the initial loading message

    +
    • +
  • +

    mySettings - the left column of the settings dropdown ("My view"); intended for adding checkboxes only

    +
    • +
  • +

    mySettings.dropdowns - add your dropdown settings here

    +
    • +
  • +

    globalSettings - the right column of the settings dropdown ("Global view")

    +
    • +
  • +

    importColumn - import form

    +
    • +
  • +

    exportColumn - export form

    +
    • +
  • +

    modals - Contains all connectivity messages

    +
    • +
  • +

    embedPopup - the embed dropdown

    +
    • +
  • +

    scripts - Add your script tags here, if you really have to (consider use client-side hooks instead)

    +
    • +
+
+
+

timeslider.html blocks:

+
+
+
    +
  • +

    timesliderStyles

    +
    • +
  • +

    timesliderScripts

    +
    • +
  • +

    timesliderBody

    +
    • +
  • +

    timesliderTop

    +
    • +
  • +

    timesliderEditbarRight

    +
    • +
  • +

    modals

    +
    • +
+
+
+

index.html blocks:

+
+
+
    +
  • +

    indexCustomStyles - contains the index.css <link> tag, allows you to add your own or to customize the one provided by the active skin

    +
    • +
  • +

    indexWrapper - contains the form for creating new pads

    +
    • +
  • +

    indexCustomScripts - contains the index.js <script> tag, allows you to add your own or to customize the one provided by the active skin

    +
    • +
+
+
+
+

padInitToolbar

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    toolbar - the toolbar controller that will render the toolbar eventually

    +
    2. +
+
+
+

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 real ID (never the read-only ID) of the pad the user wants to +access

    +
    2. +
  2. +

    token - the token of the author

    +
    3. +
  3. +

    sessionCookie - the session the use has

    +
    4. +
+
+
+

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

+
+
+
+

getAuthorId

+
+

Called from src/node/db/AuthorManager.js

+
+
+

Called when looking up (or creating) the author ID for a user, except for author +IDs obtained via the HTTP API. Registered hook functions are called until one +returns a non-undefined value. If a truthy value is returned by a hook +function, it is used as the user’s author ID. Otherwise, the value of the +dbKey context property is used to look up the author ID. If there is no such +author ID at that key, a new author ID is generated and associated with that +key.

+
+
+

Context properties:

+
+
+
    +
  • +

    dbKey: Database key to use when looking up the user’s author ID if no hook +function returns an author ID. This is initialized to the user-supplied token +value (see the token context property), but hook functions can modify this +to control how author IDs are allocated to users. If no author ID is +associated with this database key, a new author ID will be randomly generated +and associated with the key. For security reasons, if this is modified it +should be modified to not look like a valid token (see the token context +property) unless the plugin intentionally wants the user to be able to +impersonate another user.

    +
    • +
  • +

    token: The user-supplied token, or nullish for an anonymous user. Tokens are +secret values that must not be disclosed to others. If non-null, the token is +guaranteed to be a string with the form t.<base64url> where <base64url> is +any valid non-empty base64url string (RFC 4648 section 5 with padding). +Example: t.twim3X2_KGiRj8cJ-3602g==.

    +
    • +
  • +

    user: If the user has authenticated, this is an object from settings.users +(or similar from an authentication plugin). Etherpad core and all good +authentication plugins set the username property of this object to a string +that uniquely identifies the authenticated user. This object is nullish if the +user has not authenticated.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.getAuthorId = async (hookName, context) => {
+  const {username} = context.user || {};
+  // If the user has not authenticated, or has "authenticated" as the guest
+  // user, do the default behavior (try another plugin if any, falling through
+  // to using the token as the database key).
+  if (!username || username === 'guest') return;
+  // The user is authenticated and has a username. Give the user a stable author
+  // ID so that they appear to be the same author even after clearing cookies or
+  // accessing the pad from another device. Note that this string is guaranteed
+  // to never have the form of a valid token; without that guarantee an
+  // unauthenticated user might be able to impersonate an authenticated user.
+  context.dbKey = `username=${username}`;
+  // Return a falsy but non-undefined value to stop Etherpad from calling any
+  // more getAuthorId hook functions and look up the author ID using the
+  // username-derived database key.
+  return '';
+};
+
+
+
+
+

padCreate

+
+

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

+
+
+

Called when a new pad is created.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object.

    +
    • +
  • +

    authorId: The ID of the author who created the pad.

    +
    • +
  • +

    author (deprecated): Synonym of authorId.

    +
    • +
+
+
+
+

padDefaultContent

+
+

Called from src/node/db/Pad.js

+
+
+

Called to obtain a pad’s initial content, unless the pad is being created with +specific content. The return value is ignored; to change the content, modify the +content context property.

+
+
+

This hook is run asynchronously. All registered hook functions are run +concurrently (via Promise.all()), so be careful to avoid race conditions when +reading and modifying the context properties.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The newly created Pad object.

    +
    • +
  • +

    authorId: The author ID of the user that is creating the pad.

    +
    • +
  • +

    type: String identifying the content type. Currently this is 'text' and +must not be changed. Future versions of Etherpad may add support for HTML, +jsdom objects, or other formats, so plugins must assert that this matches a +supported content type before reading content.

    +
    • +
  • +

    content: The pad’s initial content. Change this property to change the pad’s +initial content. If the content type is changed, the type property must also +be updated to match. Plugins must check the value of the type property +before reading this value.

    +
    • +
+
+
+
+

padLoad

+
+

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

+
+
+

Called when a pad is loaded, including after new pad creation.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object.

    +
    • +
+
+
+
+

padUpdate

+
+

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

+
+
+

Called when an existing pad is updated.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object.

    +
    • +
  • +

    authorId: The ID of the author who updated the pad.

    +
    • +
  • +

    author (deprecated): Synonym of authorId.

    +
    • +
  • +

    revs: The index of the new revision.

    +
    • +
  • +

    changeset: The changeset of this revision (see padUpdate).

    +
    • +
+
+
+
+

padCopy

+
+

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

+
+
+

Called when a pad is copied so that plugins can copy plugin-specific database +records or perform some other plugin-specific initialization.

+
+
+

Order of events when a pad is copied:

+
+
+
    +
  1. +

    Destination pad is deleted if it exists and overwrite is permitted. This +causes the padRemove hook to run.

    +
    2. +
  2. +

    Pad-specific database records are copied in the database, except for +records with plugin-specific database keys.

    +
    3. +
  3. +

    A new Pad object is created for the destination pad. This causes the +padLoad hook to run.

    +
    4. +
  4. +

    This hook runs.

    +
    5. +
+
+
+

Context properties:

+
+
+
    +
  • +

    srcPad: The source Pad object.

    +
    • +
  • +

    dstPad: The destination Pad object.

    +
    • +
+
+
+

Usage examples:

+
+
+ +
+
+
+

padRemove

+
+

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

+
+
+

Called when an existing pad is removed/deleted. Plugins should use this to clean +up any plugin-specific pad records from the database.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: Pad object for the pad that is being deleted.

    +
    • +
+
+
+

Usage examples:

+
+
+ +
+
+
+

padCheck

+
+

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

+
+
+

Called when a consistency check is run on a pad, after the core checks have +completed successfully. An exception should be thrown if the pad is faulty in +some way.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The Pad object that is being checked.

    +
    • +
+
+
+
+

socketio

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    app - the application object

    +
    2. +
  2. +

    io - the socketio object

    +
    3. +
  3. +

    server - the http server object

    +
    4. +
+
+
+

I have no idea what this is useful for, someone else will have to add this description.

+
+
+
+

preAuthorize

+
+

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

+
+
+

Called for each HTTP request before any authentication checks are performed. The +registered preAuthorize hook functions are called one at a time until one +explicitly grants or denies the request by returning true or false, +respectively. If none of the hook functions return anything, the access decision +is deferred to the normal authentication and authorization checks.

+
+
+

Example uses:

+
+
+
    +
  • +

    Always grant access to static content.

    +
    • +
  • +

    Process an OAuth callback.

    +
    • +
  • +

    Drop requests from IP addresses that have failed N authentication checks +within the past X minutes.

    +
    • +
+
+
+

Return values:

+
+
+
    +
  • +

    undefined (or []) defers the access decision to the next registered +preAuthorize hook function, or to the normal authentication and +authorization checks if no more preAuthorize hook functions remain.

    +
    • +
  • +

    true (or [true]) immediately grants access to the requested resource, +unless the request is for an /admin page in which case it is treated the +same as returning undefined. (This prevents buggy plugins from accidentally +granting admin access to the general public.)

    +
    • +
  • +

    false (or [false]) immediately denies the request. The preAuthnFailure +hook will be called to handle the failure.

    +
    • +
+
+
+

Context properties:

+
+
+
    +
  • +

    req: The Express Request object.

    +
    • +
  • +

    res: The Express Response +object.

    +
    • +
  • +

    next: Callback to immediately hand off handling to the next Express +middleware/handler, or to the next matching route if 'route' is passed as +the first argument. Do not call this unless you understand the consequences.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.preAuthorize = async (hookName, {req}) => {
+  if (await ipAddressIsFirewalled(req)) return false;
+  if (requestIsForStaticContent(req)) return true;
+  if (requestIsForOAuthCallback(req)) return true;
+  // Defer the decision to the next step by returning undefined.
+};
+
+
+
+
+

authorize

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
  3. +

    next - ?

    +
    4. +
  4. +

    resource - the path being accessed

    +
    5. +
+
+
+

This hook is called to handle authorization. It is especially useful for +controlling access to specific paths.

+
+
+

A plugin’s authorize function is only called if all of the following are true:

+
+
+
    +
  • +

    The request is not for static content or an API endpoint. (Requests for static +content and API endpoints are always authorized, even if unauthenticated.)

    +
    • +
  • +

    The requireAuthentication and requireAuthorization settings are both true.

    +
    • +
  • +

    The user has already successfully authenticated.

    +
    • +
  • +

    The user is not an admin (admin users are always authorized).

    +
    • +
  • +

    The path being accessed is not an /admin path (/admin paths can only be +accessed by admin users, and admin users are always authorized).

    +
    • +
  • +

    An authorize function from a different plugin has not already caused +authorization to pass or fail.

    +
    • +
+
+
+

Note that the authorize hook cannot grant access to /admin pages. If admin +access is desired, the is_admin user setting must be set to true. This can be +set in the settings file or by the authenticate hook.

+
+
+

You can pass the following values to the provided callback:

+
+
+
    +
  • +

    [true] or ['create'] will grant access to modify or create the pad if the +request is for a pad, otherwise access is simply granted. Access to a pad will +be downgraded to modify-only if settings.editOnly is true or the user’s +canCreate setting is set to false, and downgraded to read-only if the +user’s readOnly setting is true.

    +
    • +
  • +

    ['modify'] will grant access to modify but not create the pad if the request +is for a pad, otherwise access is simply granted. Access to a pad will be +downgraded to read-only if the user’s readOnly setting is true.

    +
    • +
  • +

    ['readOnly'] will grant read-only access.

    +
    • +
  • +

    [false] will deny access.

    +
    • +
  • +

    [] or undefined will defer the authorization decision to the next +authorization plugin (if any, otherwise deny).

    +
    • +
+
+
+

Example:

+
+
+
+
exports.authorize = (hookName, context, cb) => {
+  const user = context.req.session.user;
+  const path = context.req.path;  // or context.resource
+  if (isExplicitlyProhibited(user, path)) return cb([false]);
+  if (isExplicitlyAllowed(user, path)) return cb([true]);
+  return cb([]);  // Let the next authorization plugin decide
+};
+
+
+
+
+

authenticate

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
  3. +

    users - the users object from settings.json (possibly modified by plugins)

    +
    4. +
  4. +

    next - ?

    +
    5. +
  5. +

    username - the username used (optional)

    +
    6. +
  6. +

    password - the password used (optional)

    +
    7. +
+
+
+

This hook is called to handle authentication.

+
+
+

Plugins that supply an authenticate function should probably also supply an +authnFailure function unless falling back to HTTP basic authentication is +appropriate upon authentication failure.

+
+
+

This hook is only called if either the requireAuthentication setting is true +or the request is for an /admin page.

+
+
+

Calling the provided callback with [true] or [false] will cause +authentication to succeed or fail, respectively. Calling the callback with [] +or undefined will defer the authentication decision to the next authentication +plugin (if any, otherwise fall back to HTTP basic authentication).

+
+
+

If you wish to provide a mix of restricted and anonymous access (e.g., some pads +are private, others are public), you can "authenticate" (as a guest account) +users that have not yet logged in, and rely on other hooks (e.g., authorize, +onAccessCheck, handleMessageSecurity) to authorize specific privileged actions.

+
+
+

If authentication is successful, the authenticate function MUST set +context.req.session.user to the user’s settings object. The username +property of this object should be set to the user’s username. The settings +object should come from global settings (context.users[username]).

+
+
+

Example:

+
+
+
+
exports.authenticate = (hook_name, context, cb) => {
+  if (notApplicableToThisPlugin(context)) {
+    return cb([]);  // Let the next authentication plugin decide
+  }
+  const username = authenticate(context);
+  if (!username) {
+    console.warn(`ep_myplugin.authenticate: Failed authentication from IP ${context.req.ip}`);
+    return cb([false]);
+  }
+  console.info(`ep_myplugin.authenticate: Successful authentication from IP ${context.req.ip} for user ${username}`);
+  const users = context.users;
+  if (!(username in users)) users[username] = {};
+  users[username].username = username;
+  context.req.session.user = users[username];
+  return cb([true]);
+};
+
+
+
+
+

authFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
  3. +

    next - ?

    +
    4. +
+
+
+

DEPRECATED: Use authnFailure or authzFailure instead.

+
+
+

This hook is called to handle an authentication or authorization failure.

+
+
+

Plugins that supply an authenticate function should probably also supply an +authnFailure function unless falling back to HTTP basic authentication is +appropriate upon authentication failure.

+
+
+

A plugin’s authFailure function is only called if all of the following are true:

+
+
+
    +
  • +

    There was an authentication or authorization failure.

    +
    • +
  • +

    The failure was not already handled by an authFailure function from another +plugin.

    +
    • +
  • +

    For authentication failures: The failure was not already handled by the +authnFailure hook.

    +
    • +
  • +

    For authorization failures: The failure was not already handled by the +authzFailure hook.

    +
    • +
+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to the next authFailure plugin (if +any, otherwise fall back to HTTP basic authentication for an authentication +failure or a generic 403 page for an authorization failure).

+
+
+

Example:

+
+
+
+
exports.authFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) {
+    return cb([]);  // Let the next plugin handle the error
+  }
+  context.res.redirect(makeLoginURL(context.req));
+  return cb([true]);
+};
+
+
+
+
+

preAuthzFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
+
+
+

This hook is called to handle a pre-authentication authorization failure.

+
+
+

A plugin’s preAuthzFailure function is only called if the pre-authentication +authorization failure was not already handled by a preAuthzFailure function from +another plugin.

+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to a preAuthzFailure function from +another plugin (if any, otherwise fall back to a generic 403 error page).

+
+
+

Example:

+
+
+
+
exports.preAuthzFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) return cb([]);
+  context.res.status(403).send(renderFancy403Page(context.req));
+  return cb([true]);
+};
+
+
+
+
+

authnFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
+
+
+

This hook is called to handle an authentication failure.

+
+
+

Plugins that supply an authenticate function should probably also supply an +authnFailure function unless falling back to HTTP basic authentication is +appropriate upon authentication failure.

+
+
+

A plugin’s authnFailure function is only called if the authentication failure +was not already handled by an authnFailure function from another plugin.

+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to an authnFailure function from +another plugin (if any, otherwise fall back to the deprecated authFailure hook).

+
+
+

Example:

+
+
+
+
exports.authnFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) return cb([]);
+  context.res.redirect(makeLoginURL(context.req));
+  return cb([true]);
+};
+
+
+
+
+

authzFailure

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    req - the request object

    +
    2. +
  2. +

    res - the response object

    +
    3. +
+
+
+

This hook is called to handle a post-authentication authorization failure.

+
+
+

A plugin’s authzFailure function is only called if the authorization failure was +not already handled by an authzFailure function from another plugin.

+
+
+

Calling the provided callback with [true] tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +[] or undefined defers error handling to an authzFailure function from +another plugin (if any, otherwise fall back to the deprecated authFailure hook).

+
+
+

Example:

+
+
+
+
exports.authzFailure = (hookName, context, cb) => {
+  if (notApplicableToThisPlugin(context)) return cb([]);
+  if (needsPremiumAccount(context.req) && !context.req.session.user.premium) {
+    context.res.status(200).send(makeUpgradeToPremiumAccountPage(context.req));
+    return cb([true]);
+  }
+  // Use the generic 403 forbidden response.
+  return cb([]);
+};
+
+
+
+
+

handleMessage

+
+

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

+
+
+

This hook allows plugins to drop or modify incoming socket.io messages from +clients, before Etherpad processes them. If any hook function returns null +then the message will not be subject to further processing.

+
+
+

Context properties:

+
+
+
    +
  • +

    message: The message being handled.

    +
    • +
  • +

    sessionInfo: Object describing the socket.io session with the following +properties:

    +
    • +
  • +

    authorId: The user’s author ID.

    +
    • +
  • +

    padId: The real (not read-only) ID of the pad.

    +
    • +
  • +

    readOnly: Whether the client has read-only access (true) or read/write +access (false).

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
  • +

    client: (Deprecated; use socket instead.) Synonym of socket.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.handleMessage = async (hookName, {message, socket}) => {
+  if (message.type === 'USERINFO_UPDATE') {
+    // Force the display name to the name associated with the account.
+    const user = socket.client.request.session.user || {};
+    if (user.name) message.data.userInfo.name = user.name;
+  }
+};
+
+
+
+
+

handleMessageSecurity

+
+

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

+
+
+

Called for each incoming message from a client. Allows plugins to grant +temporary write access to a pad.

+
+
+

Supported return values:

+
+
+
    +
  • +

    undefined: No change in access status.

    +
    • +
  • +

    'permitOnce': Override the user’s read-only access for the current +COLLABROOM message only. Has no effect if the current message is not a +COLLABROOM message, or if the user already has write access to the pad.

    +
    • +
  • +

    true: (Deprecated; return 'permitOnce' instead.) Override the user’s +read-only access for all COLLABROOM messages from the same socket.io +connection (including the current message, if applicable) until the client’s +next CLIENT_READY message. Has no effect if the user already has write +access to the pad. Read-only access is reset after each CLIENT_READY +message, so returning true has no effect for CLIENT_READY messages.

    +
    • +
+
+
+

Context properties:

+
+
+
    +
  • +

    message: The message being handled.

    +
    • +
  • +

    sessionInfo: Object describing the socket.io connection with the following +properties:

    +
    • +
  • +

    authorId: The user’s author ID.

    +
    • +
  • +

    padId: The real (not read-only) ID of the pad.

    +
    • +
  • +

    readOnly: Whether the client has read-only access (true) or read/write +access (false).

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
  • +

    client: (Deprecated; use socket instead.) Synonym of socket.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.handleMessageSecurity = async (hookName, context) => {
+  const {message, sessionInfo: {readOnly}} = context;
+  if (!readOnly || message.type !== 'COLLABROOM') return;
+  if (await messageIsBenign(message)) return 'permitOnce';
+};
+
+
+
+
+

clientVars

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    clientVars - the basic clientVars built by the core

    +
    2. +
  2. +

    pad - the pad this session is about

    +
    3. +
  3. +

    socket - the socket.io Socket object

    +
    4. +
+
+
+

This hook is called after a client connects but before the initial configuration +is sent to the client. Plugins can use this hook to manipulate the +configuration. (Example: Add a tracking ID for an external analytics tool that +is used client-side.)

+
+
+

You can manipulate clientVars in two different ways: +* Return an object. The object will be merged into clientVars via + Object.assign(), so any keys that already exist in clientVars will be + overwritten by the values in the returned object. +* Modify context.clientVars. Beware: Other plugins might also be reading or + manipulating the same context.clientVars object. To avoid race conditions, + you are encouraged to return an object rather than modify + context.clientVars.

+
+
+

If needed, you can access the user’s account information (if authenticated) via +context.socket.client.request.session.user.

+
+
+

Examples:

+
+
+
+
// Using an async function
+exports.clientVars = async (hookName, context) => {
+  const user = context.socket.client.request.session.user || {};
+  return {'accountUsername': user.username || '<unknown>'}
+};
+
+// Using a regular function
+exports.clientVars = (hookName, context, callback) => {
+  const user = context.socket.client.request.session.user || {};
+  return callback({'accountUsername': user.username || '<unknown>'});
+};
+
+
+
+
+

getLineHTMLForExport

+
+

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

+
+
+

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

+
+
+

Context properties:

+
+
+
    +
  • +

    apool: Pool object.

    +
    • +
  • +

    attribLine: Line attributes.

    +
    • +
  • +

    line:

    +
    • +
  • +

    lineContent:

    +
    • +
  • +

    text: Line text.

    +
    • +
  • +

    padId: Writable (not read-only) pad identifier.

    +
    • +
+
+
+

Example:

+
+
+
+
const AttributeMap = require('ep_etherpad-lite/static/js/AttributeMap');
+const Changeset = require('ep_etherpad-lite/static/js/Changeset');
+
+exports.getLineHTMLForExport = async (hookName, context) => {
+  if (!context.attribLine) return;
+  const [op] = Changeset.deserializeOps(context.attribLine);
+  if (op == null) return;
+  const heading = AttributeMap.fromString(op.attribs, context.apool).get('heading');
+  if (!heading) return;
+  context.lineContent = `<${heading}>${context.lineContent}</${heading}>`;
+};
+
+
+
+
+

exportHTMLAdditionalContent

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    padId

    +
    2. +
+
+
+

This hook will allow a plug-in developer to include additional HTML content in +the body of the exported HTML.

+
+
+

Example:

+
+
+
+
exports.exportHTMLAdditionalContent = async (hookName, {padId}) => {
+  return 'I am groot in ' + padId;
+};
+
+
+
+
+

stylesForExport

+
+

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

+
+
+

Things in context:

+
+
+
    +
  1. +

    padId - The Pad Id

    +
    2. +
+
+
+

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

+
+
+

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.

+
+
+

An attributes object is passed to the aceAttribClasses hook functions instead of +the usual context object. A hook function can either modify this object directly +or provide an object whose properties will be assigned to the attributes object.

+
+
+

Example:

+
+
+
+
exports.aceAttribClasses = (hookName, attrs, cb) => {
+  return cb([{
+    sub: 'tag:sub',
+  }]);
+};
+
+
+
+
+

exportFileName

+
+

Called from src/node/handler/ExportHandler.js

+
+
+

Things in context:

+
+
+
    +
  1. +

    padId

    +
    2. +
+
+
+

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

    +
    2. +
+
+
+

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

    +
    2. +
+
+
+

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"]]);
+};
+
+
+
+
+

exportEtherpadAdditionalContent

+
+

Called from src/node/utils/ExportEtherpad.js and +src/node/utils/ImportEtherpad.js.

+
+
+

Called when exporting to an .etherpad file or when importing from an +.etherpad file. The hook function should return prefixes for pad-specific +records that should be included in the export/import. On export, all +${prefix}:${padId} and ${prefix}:${padId}:* records are included in the +generated .etherpad file. On import, all ${prefix}:${padId} and +${prefix}:${padId}:* records are loaded into the database.

+
+
+

Context properties: None.

+
+
+

Example:

+
+
+
+
// Add support for exporting comments metadata
+exports.exportEtherpadAdditionalContent = () => ['comments'];
+
+
+
+
+

exportEtherpad

+
+

Called from src/node/utils/ExportEtherpad.js.

+
+
+

Called when exporting to an .etherpad file.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: The exported pad’s Pad object.

    +
    • +
  • +

    data: JSONable output object. This is pre-populated with records from core +Etherpad as well as pad-specific records with prefixes from the +exportEtherpadAdditionalContent hook. Registered hook functions can modify +this object (but not replace the object) to perform any desired +transformations to the exported data (such as the inclusion of +plugin-specific records). All registered hook functions are executed +concurrently, so care should be taken to avoid race conditions with other +plugins.

    +
    • +
  • +

    dstPadId: The pad ID that should be used when writing pad-specific records +to data (instead of pad.id). This avoids leaking the writable pad ID +when a user exports a read-only pad. This might be a dummy value; plugins +should not assume that it is either the pad’s real writable ID or its +read-only ID.

    +
    • +
+
+
+
+

importEtherpad

+
+

Called from src/node/utils/ImportEtherpad.js.

+
+
+

Called when importing from an .etherpad file.

+
+
+

Context properties:

+
+
+
    +
  • +

    pad: Temporary Pad object containing the pad’s data read from the imported +.etherpad file. The pad.db object is a temporary in-memory database +whose records will be copied to the real database after they are validated +(see the padCheck hook). Registered hook functions MUST NOT use the real +database to access (read or write) pad-specific records; they MUST instead +use pad.db. All registered hook functions are executed concurrently, so +care should be taken to avoid race conditions with other plugins.

    +
    • +
  • +

    data: Raw JSONable object from the .etherpad file. This data must not be +modified.

    +
    • +
  • +

    srcPadId: The pad ID used for the pad-specific information in data.

    +
    • +
+
+
+
+

import

+
+

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

+
+
+

Called when a user submits a document for import, before the document is +converted to HTML. The hook function should return a truthy value if the hook +function elected to convert the document to HTML.

+
+
+

Context properties:

+
+
+
    +
  • +

    destFile: The destination HTML filename.

    +
    • +
  • +

    fileEnding: The lower-cased filename extension from srcFile with leading +period (examples: '.docx', '.html', '.etherpad').

    +
    • +
  • +

    padId: The identifier of the destination pad.

    +
    • +
  • +

    srcFile: The document to convert.

    +
    • +
  • +

    ImportError: Subclass of Error that can be thrown to provide a specific +error message to the user. The constructor’s first argument must be a string +matching one of the known error identifiers.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.import = async (hookName, {fileEnding, ImportError}) => {
+  // Reject all *.etherpad imports with a permission denied message.
+  if (fileEnding === '.etherpad') throw new ImportError('permission');
+};
+
+
+
+
+

userJoin

+
+

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

+
+
+

Called after users have been notified that a new user has joined the pad.

+
+
+

Context properties:

+
+
+
    +
  • +

    authorId: The user’s author identifier.

    +
    • +
  • +

    displayName: The user’s display name.

    +
    • +
  • +

    padId: The real (not read-only) identifier of the pad the user joined. This +MUST NOT be shared with any users that are connected with read-only access.

    +
    • +
  • +

    readOnly: Whether the user only has read-only access.

    +
    • +
  • +

    readOnlyPadId: The read-only identifier of the pad the user joined.

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.userJoin = async (hookName, {authorId, displayName, padId}) => {
+  console.log(`${authorId} (${displayName}) joined pad ${padId});
+};
+
+
+
+
+

userLeave

+
+

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

+
+
+

Called when a user disconnects from a pad. This is useful if you want to perform +certain actions after a pad has been edited.

+
+
+

Context properties:

+
+
+
    +
  • +

    authorId: The user’s author ID.

    +
    • +
  • +

    padId: The pad’s real (not read-only) identifier.

    +
    • +
  • +

    readOnly: If truthy, the user only has read-only access.

    +
    • +
  • +

    readOnlyPadId: The pad’s read-only identifier.

    +
    • +
  • +

    socket: The socket.io Socket object.

    +
    • +
+
+
+

Example:

+
+
+
+
exports.userLeave = async (hookName, {author, padId}) => {
+  console.log(`${author} left pad ${padId}`);
+};
+
+
+
+
+

chatNewMessage

+
+

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

+
+
+

Called when a user (or plugin) generates a new chat message, just before it is +saved to the pad and relayed to all connected users.

+
+
+

Context properties:

+
+
+
    +
  • +

    message: The chat message object. Plugins can mutate this object to change +the message text or add custom metadata to control how the message will be +rendered by the chatNewMessage client-side hook. The message’s authorId +property can be trusted (the server overwrites any client-provided author ID +value with the user’s actual author ID before this hook runs).

    +
    • +
  • +

    padId: The pad’s real (not read-only) identifier.

    +
    • +
  • +

    pad: The pad’s Pad object.

    +
    • +
+
+
+
+
+
+

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

+
+
+

The changeset +library +provides tools to create, read, and apply changesets.

+
+
+

Changeset

+
+
+
const Changeset = require('ep_etherpad-lite/static/js/Changeset');
+
+
+
+

A changeset describes the difference between two revisions of a document. When a +user edits a pad, the browser generates and sends a changeset to the server, +which relays it to the other users and saves a copy (so that every past revision +is accessible).

+
+
+

A transmitted changeset looks like this:

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

Attribute Pool

+
+
+
const AttributePool = require('ep_etherpad-lite/static/js/AttributePool');
+
+
+
+

Changesets do not include any attribute key–value pairs. Instead, they use +numeric identifiers that reference attributes kept in an attribute pool. +This attribute interning reduces the transmission overhead of attributes that +are used many times.

+
+
+

There is one attribute pool per pad, and it includes every current and +historical attribute used in the pad.

+
+
+
+

Further Reading

+
+

Detailed information about the changesets & Easysync protocol:

+
+
+ +
+
+
+
+
+

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)

+
+
    +
  • +

    {Object} opts

    +
    • +
  • +

    command - this command fill be fired on the editbar on click

    +
    • +
  • +

    localizationId - will be set as data-l10-id

    +
    • +
  • +

    class - here you can add additional classes to the button

    +
    • +
+
+
+

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)

+
+
    +
  • +

    {Object} opts

    +
    • +
  • +

    id - id of the menu item

    +
    • +
  • +

    selectId - id of the select element

    +
    • +
  • +

    command - this command fill be fired on the editbar on change

    +
    • +
+
+
+

Returns: {SelectButton}

+
+
+
+

SelectButton.addOption(value, text, attributes)

+
+
    +
  • +

    {String} value - The value of this option

    +
    • +
  • +

    {String} text - the label text used for this option

    +
    • +
  • +

    {Object} attributes - any additional html attributes go here (e.g. data-l10n-id)

    +
    • +
+
+
+
+

registerButton(name, item)

+
+
    +
  • +

    {String} name - used to reference the item in the toolbar config in settings.json

    +
    • +
  • +

    {Button|SelectButton} item - the button to add

    +
    • +
+
+
+
+
+
+

Editbar

+
+
+

src/static/js/pad_editbar.js

+
+
+

isEnabled()

+ +
+
+

disable()

+ +
+
+

toggleDropDown(dropdown)

+
+

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 to +execute its own functionality based on these events.

+
+
+

Publicly available plugins can be found in the npm registry (see +https://npmjs.org). Etherpad’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 --no-save --legacy-peer-deps +ep_flubberworm in Etherpad’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

+
+

Ideally a plugin has the following folder structure:

+
+
+
+
ep_<plugin>/
+ ├ .github/
+ │  └ workflows/
+ │     └ npmpublish.yml  ◄─ GitHub workflow to auto-publish on push
+ ├ static/
+ │  ├ css/               ◄─ static .css files
+ │  ├ images/            ◄─ static image files
+ │  ├ js/
+ │  │  └ index.js        ◄─ static client-side code
+ │  └ tests/
+ │     ├ backend/
+ │     │  └ specs/       ◄─ backend (server) tests
+ │     └ frontend/
+ │        └ specs/       ◄─ frontend (client) tests
+ ├ templates/            ◄─ EJS templates (.html, .js, .css, etc.)
+ ├ locales/
+ │  ├ en.json            ◄─ English (US) strings
+ │  └ qqq.json           ◄─ optional hints for translators
+ ├ .travis.yml           ◄─ Travis CI config
+ ├ LICENSE
+ ├ README.md
+ ├ ep.json               ◄─ Etherpad plugin definition
+ ├ index.js              ◄─ server-side code
+ ├ package.json
+ â”” package-lock.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/. Tests go in static/tests/backend/specs/ and +static/tests/frontend/specs/.

+
+
+

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 hook +functions, 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 +Server-side hooks.)

+
+
+
+
{
+  "parts": [
+    {
+      "name": "nameThisPartHoweverYouWant",
+      "hooks": {
+        "authenticate": "ep_<plugin>/<file>:functionName1",
+        "expressCreateServer": "ep_<plugin>/<file>:functionName2"
+      },
+      "client_hooks": {
+        "acePopulateDOMLine": "ep_<plugin>/<file>:functionName3"
+      }
+    }
+  ]
+}
+
+
+
+

A hook function registration maps a hook name to a hook function specification. +The hook function specification looks like ep_example/file.js:functionName. It +consists of two parts separated by a colon: a module name to require() and the +name of a function exported by the named module. See +module.exports +for how to export a function.

+
+
+

For the module name you can omit the .js suffix, and if the file is index.js +you can use just the directory name. You can also omit the module name entirely, +in which case it defaults to the plugin name (e.g., ep_example).

+
+
+

You can also omit the function name. If you do, Etherpad will look for an +exported function whose name matches the name of the hook (e.g., +authenticate).

+
+
+

If either the module name or the function name is omitted (or both), the colon +may also be omitted unless the provided module name contains a colon. (So if the +module name is C:\foo.js then the hook function specification with the +function name omitted would be "C:\\foo.js:".)

+
+
+

Examples: Suppose the plugin name is ep_example. All of the following are +equivalent, and will cause the authorize hook to call the exports.authorize +function in index.js from the ep_example plugin:

+
+
+
    +
  • +

    "authorize": "ep_example/index.js:authorize"

    +
    • +
  • +

    "authorize": "ep_example/index.js:"

    +
    • +
  • +

    "authorize": "ep_example/index.js"

    +
    • +
  • +

    "authorize": "ep_example/index:authorize"

    +
    • +
  • +

    "authorize": "ep_example/index:"

    +
    • +
  • +

    "authorize": "ep_example/index"

    +
    • +
  • +

    "authorize": "ep_example:authorize"

    +
    • +
  • +

    "authorize": "ep_example:"

    +
    • +
  • +

    "authorize": "ep_example"

    +
    • +
  • +

    "authorize": ":authorize"

    +
    • +
  • +

    "authorize": ":"

    +
    • +
  • +

    "authorize": ""

    +
    • +
+
+
+

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 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": ">=12.17.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. +
  2. +

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

    +
    3. +
  3. +

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

    +
    4. +
+
+
+
+
+
+

Cookies

+
+
+

Cookies used by Etherpad.

+
+ ++++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Name

Sample value

Domain

Path

Expires/max-age

Http-only

Secure

Usage description

express_sid

s%3A7yCNjRmTW8ylGQ53I2IhOwYF9…​

example.org

/

Session

true

true

Session ID of the Express web framework. When Etherpad is behind a reverse proxy, and an administrator wants to use session stickiness, he may use this cookie. If you are behind a reverse proxy, please remember to set trustProxy: true in settings.json. Set in webaccess.js#L131.

language

en

example.org

/

Session

false

true

The language of the UI (e.g.: en-GB, it). Set in pad_editor.js#L111.

prefs / prefsHttp

%7B%22epThemesExtTheme%22…​

example.org

/p

year 3000

false

true

Client-side preferences (e.g.: font family, chat always visible, show authorship colors, …​). Set in pad_cookie.js#L49. prefs is used if Etherpad is accessed over HTTPS, prefsHttp if accessed over HTTP. For more info see https://github.com/ether/etherpad-lite/issues/3179.

token

t.tFzkihhhBf4xKEpCK3PU

example.org

/

60 days

false

true

A random token representing the author, of the form t.randomstring_of_lenght_20. The random string is generated by the client, at pad.js#L55-L66. This cookie is always set by the client at pad.js#L153-L158 without any solicitation from the server. It is used for all the pads accessed via the web UI (not used for the HTTP API). On the server side, its value is accessed at SecurityManager.js#L33.

+
+

For more info, visit the related discussion at https://github.com/ether/etherpad-lite/issues/3563.

+
+
+

Etherpad HTTP API clients may make use (if they choose so) to send another cookie:

+
+ +++++ + + + + + + + + + + + + +

Name

Sample value

Domain

Usage description

sessionID

s.1c70968b333b25476a2c7bdd0e0bed17

+
+
+
+

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

+
+
+
    +
  • +

    atext - the latest attributed text

    +
    • +
  • +

    pool - the attribute pool

    +
    • +
  • +

    head - the number of the latest revision

    +
    • +
  • +

    chatHead - the number of the latest chat entry

    +
    • +
  • +

    public - flag that disables security for this pad

    +
    • +
  • +

    passwordHash - string that contains a salted sha512 sum of this pad’s password

    +
    • +
+
+
+
+

pad:$PADID:revs:$REVNUM

+
+

Saves a revision $REVNUM of pad $PADID

+
+
+
    +
  • +

    meta

    +
    • +
  • +

    author - the autorID of this revision

    +
    • +
  • +

    timestamp - the timestamp of when this revision was created

    +
    • +
  • +

    changeset - the changeset of this revision

    +
    • +
+
+
+
+

pad:$PADID:chat:$CHATNUM

+
+

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

+
+
+
    +
  • +

    text - the text of this chat entry

    +
    • +
  • +

    userId - the authorID of this chat entry

    +
    • +
  • +

    time - the timestamp of this chat entry

    +
    • +
+
+
+
+

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

+
+
+
    +
  • +

    name - the name of this author as shown in the pad

    +
    • +
  • +

    colorID - the colorID of this author as shown in the pad

    +
    • +
+
+
+
+

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

+
+
+
    +
  • +

    pads - object with pad names in it, values are 1 +==== session:$SESSIONID +a session between an author and a group

    +
    • +
  • +

    groupID - the groupID the session belongs too

    +
    • +
  • +

    authorID - the authorID the session belongs too

    +
    • +
  • +

    validUntil - the timestamp until this session is valid

    +
    • +
+
+
+
+

author2sessions:$AUTHORID

+
+

saves the sessions of an author

+
+
+
    +
  • +

    sessionsIDs - object with sessionIDs in it, values are 1

    +
    • +
+
+
+
+

group2sessions:$GROUPID

+
+
    +
  • +

    sessionsIDs - object with sessionIDs in it, values are 1

    +
    • +
+
+
+
+
+
+
+ + + + + \ No newline at end of file diff --git a/public/doc/v2.2.7/localization.html b/public/doc/v2.2.7/localization.html new file mode 100644 index 0000000..2118cf2 --- /dev/null +++ b/public/doc/v2.2.7/localization.html @@ -0,0 +1,641 @@ + + + + + + + +Localization + + + + + +
+
+

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. +
  2. +

    Visit our TWN project page

    +
    3. +
  3. +

    Click on Translate Etherpad lite interface

    +
    4. +
  4. +

    Choose a target language, you’d like to translate our interface to, and hit Fetch

    +
    5. +
  5. +

    Start translating!

    +
    6. +
+
+
+

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

+
+
    +
  • +

    The name of the file must be the language code of the language it contains translations for (see supported lang codes; e.g. en ? English, es ? Spanish…​)

    +
    • +
  • +

    The extension of the file must be .json

    +
    • +
  • +

    The default language is English, so your plugin should always provide en.json

    +
    • +
  • +

    In order to avoid naming conflicts, your message keys should start with the name of your plugin followed by a dot (see below)

    +
    • +
+
+
+

ep_your-plugin/locales/en.json

+
+
+
+
{
+  "ep_your-plugin.h1": "Heading 1"
+}
+
+
+
+

ep_your-plugin/locales/es.json

+
+
+
+
{
+  "ep_your-plugin.h1": "Título 1"
+}
+
+
+
+

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"
+}
+
+
+
+
+
+

Customization for Administrators

+
+

As an Etherpad administrator, it is possible to overwrite core messages as well as messages in plugins. These include error messages, labels, and user instructions. Whereas the localization in the source code is in separate files separated by locale, an administrator’s custom localizations are in settings.json under the customLocaleStrings key, with each locale separated by a sub-key underneath.

+
+
+

For example, let’s say you want to change the text on the "New Pad" button on Etherpad’s home page. If you look in locales/en.json (or locales/en-gb.json) you’ll see the key for this text is "index.newPad". You could add the following to settings.json:

+
+
+
+
  "customLocaleStrings": {
+    "fr": {
+      "index.newPad": "Créer un document"
+    },
+    "en-gb": {
+      "index.newPad": "Create a document"
+    },
+    "en": {
+      "index.newPad": "Create a document"
+    }
+  }
+
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/plugins.html b/public/doc/v2.2.7/plugins.html new file mode 100644 index 0000000..998618a --- /dev/null +++ b/public/doc/v2.2.7/plugins.html @@ -0,0 +1,776 @@ + + + + + + + +Plugins + + + + + +
+
+

Plugins

+
+
+

Etherpad allows you to extend its functionality with plugins. A plugin registers +hooks (functions) for certain events (thus certain features) in Etherpad to +execute its own functionality based on these events.

+
+
+

Publicly available plugins can be found in the npm registry (see +https://npmjs.org). Etherpad’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 --no-save --legacy-peer-deps +ep_flubberworm in Etherpad’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

+
+

Ideally a plugin has the following folder structure:

+
+
+
+
ep_<plugin>/
+ ├ .github/
+ │  └ workflows/
+ │     └ npmpublish.yml  ◄─ GitHub workflow to auto-publish on push
+ ├ static/
+ │  ├ css/               ◄─ static .css files
+ │  ├ images/            ◄─ static image files
+ │  ├ js/
+ │  │  └ index.js        ◄─ static client-side code
+ │  └ tests/
+ │     ├ backend/
+ │     │  └ specs/       ◄─ backend (server) tests
+ │     └ frontend/
+ │        └ specs/       ◄─ frontend (client) tests
+ ├ templates/            ◄─ EJS templates (.html, .js, .css, etc.)
+ ├ locales/
+ │  ├ en.json            ◄─ English (US) strings
+ │  └ qqq.json           ◄─ optional hints for translators
+ ├ .travis.yml           ◄─ Travis CI config
+ ├ LICENSE
+ ├ README.md
+ ├ ep.json               ◄─ Etherpad plugin definition
+ ├ index.js              ◄─ server-side code
+ ├ package.json
+ â”” package-lock.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/. Tests go in static/tests/backend/specs/ and +static/tests/frontend/specs/.

+
+
+

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 hook +functions, 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 +[Server-side hooks].)

+
+
+
+
{
+  "parts": [
+    {
+      "name": "nameThisPartHoweverYouWant",
+      "hooks": {
+        "authenticate": "ep_<plugin>/<file>:functionName1",
+        "expressCreateServer": "ep_<plugin>/<file>:functionName2"
+      },
+      "client_hooks": {
+        "acePopulateDOMLine": "ep_<plugin>/<file>:functionName3"
+      }
+    }
+  ]
+}
+
+
+
+

A hook function registration maps a hook name to a hook function specification. +The hook function specification looks like ep_example/file.js:functionName. It +consists of two parts separated by a colon: a module name to require() and the +name of a function exported by the named module. See +module.exports +for how to export a function.

+
+
+

For the module name you can omit the .js suffix, and if the file is index.js +you can use just the directory name. You can also omit the module name entirely, +in which case it defaults to the plugin name (e.g., ep_example).

+
+
+

You can also omit the function name. If you do, Etherpad will look for an +exported function whose name matches the name of the hook (e.g., +authenticate).

+
+
+

If either the module name or the function name is omitted (or both), the colon +may also be omitted unless the provided module name contains a colon. (So if the +module name is C:\foo.js then the hook function specification with the +function name omitted would be "C:\\foo.js:".)

+
+
+

Examples: Suppose the plugin name is ep_example. All of the following are +equivalent, and will cause the authorize hook to call the exports.authorize +function in index.js from the ep_example plugin:

+
+
+
    +
  • +

    "authorize": "ep_example/index.js:authorize"

    +
    • +
  • +

    "authorize": "ep_example/index.js:"

    +
    • +
  • +

    "authorize": "ep_example/index.js"

    +
    • +
  • +

    "authorize": "ep_example/index:authorize"

    +
    • +
  • +

    "authorize": "ep_example/index:"

    +
    • +
  • +

    "authorize": "ep_example/index"

    +
    • +
  • +

    "authorize": "ep_example:authorize"

    +
    • +
  • +

    "authorize": "ep_example:"

    +
    • +
  • +

    "authorize": "ep_example"

    +
    • +
  • +

    "authorize": ":authorize"

    +
    • +
  • +

    "authorize": ":"

    +
    • +
  • +

    "authorize": ""

    +
    • +
+
+
+

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 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": ">=12.17.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. +
  2. +

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

    +
    3. +
  3. +

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

    +
    4. +
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/skins.html b/public/doc/v2.2.7/skins.html new file mode 100644 index 0000000..084f836 --- /dev/null +++ b/public/doc/v2.2.7/skins.html @@ -0,0 +1,500 @@ + + + + + + + +Skins + + + + + +
+
+

Skins

+
+
+

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

+
+
+
    +
  • +

    index.js: javascript that will be run in /

    +
    • +
  • +

    index.css: stylesheet affecting /

    +
    • +
  • +

    pad.js: javascript that will be run in /p/:padid

    +
    • +
  • +

    pad.css: stylesheet affecting /p/:padid

    +
    • +
  • +

    timeslider.js: javascript that will be run in /p/:padid/timeslider

    +
    • +
  • +

    timeslider.css: stylesheet affecting /p/:padid/timeslider

    +
    • +
  • +

    favicon.ico: overrides the default favicon

    +
    • +
  • +

    robots.txt: overrides the default robots.txt

    +
    • +
+
+
+

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

+
+
+

Since Etherpad 1.7.5, two skins are included:

+
+
+
    +
  • +

    no-skin: an empty skin, leaving the default Etherpad appearance unchanged, that you can use as a guidance to develop your own.

    +
    • +
  • +

    colibris: a new, experimental skin, that will become the default in Etherpad 2.0.

    +
    • +
+
+
+
+
+ + + \ No newline at end of file diff --git a/public/doc/v2.2.7/stats.html b/public/doc/v2.2.7/stats.html new file mode 100644 index 0000000..8028773 --- /dev/null +++ b/public/doc/v2.2.7/stats.html @@ -0,0 +1,495 @@ + + + + + + + +Statistics + + + + + +
+
+

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:

+
+
+
    +
  • +

    totalUsers (counter)

    +
    • +
  • +

    connects (meter)

    +
    • +
  • +

    disconnects (meter)

    +
    • +
  • +

    pendingEdits (counter)

    +
    • +
  • +

    edits (timer)

    +
    • +
  • +

    failedChangesets (meter)

    +
    • +
  • +

    httpRequests (timer)

    +
    • +
  • +

    http500 (meter)

    +
    • +
  • +

    memoryUsage (gauge)

    +
    • +
+
+
+

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.

+
+
+
+
+ + + \ No newline at end of file