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:
++ ++++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:
++ ++++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:
++ ++++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>¶m1=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
+
+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
+
+ -
+
+authorIdin 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
+
+ -
+
+authorIdin 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
+
+ -
+
+authorIdin 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
+
+ -
+
+authorIdin 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
+
+ -
+
+authorIdin 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
+startandendare 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
+
+ -
+
+authorIdin 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
+
+ -
+
+authorIdin 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:
+-
+
-
+
+hookName- The name of the hook being invoked.
+ -
+
+context- An object with some relevant information about the context of the +call. See the hook-specific documentation for details.
+ -
+
+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 returnsundefined.
+
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 (
+undefinedis acceptable) and +returnundefined, in that order.
+ -
+
Return a non-Promise value other than
+undefined(nullis acceptable) and +never call the callback. Note thatasyncfunctions always return a +Promise, so they must never be used for synchronous hooks.
+ -
+
Only have two parameters (
+hookNameandcontext) and return any non-Promise +value (undefinedis acceptable).
+
For hooks that permit asynchronous behavior, the hook functions must do one or +more of the following:
+-
+
-
+
Return
+undefinedand call the callback, in either order.
+ -
+
Return something other than
+undefined(nullis acceptable) and never call +the callback. Note thatasyncfunctions always return a Promise, so they +must never call the callback.
+ -
+
Only have two parameters (
+hookNameandcontext).
+
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
+undefinedunless +the hook function only has two parameters. (Hook functions with three +parameters that want to provideundefinedshould 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:
+-
+
-
+
domline - The current DOM line being processed
+
+ -
+
cls - The class of the current block element (useful for styling)
+
+
This hook is called for elements in the DOM that have the "lineMarkerAttribute" +set. You can add elements into this category with the aceRegisterBlockElements +hook above. This hook is run BEFORE the numbered and ordered lists logic is +applied.
+The return value of this hook should have the following structure:
+{ preHtml: String, postHtml: String, processedMarker: Boolean }
The preHtml and postHtml values will be added to the HTML display of the +element, and if processedMarker is true, the engine won’t try to process it any +more.
+aceDomLineProcessLineAttributes
+Called from: src/static/js/domline.js
Things in context:
+-
+
-
+
domline - The current DOM line being processed
+
+ -
+
cls - The class of the current block element (useful for styling)
+
+
This hook is called for elements in the DOM that have the "lineMarkerAttribute" +set. You can add elements into this category with the aceRegisterBlockElements +hook above. This hook is run AFTER the ordered and numbered lists logic is +applied.
+The return value of this hook should have the following structure:
+{ preHtml: String, postHtml: String, processedMarker: Boolean }
The preHtml and postHtml values will be added to the HTML display of the +element, and if processedMarker is true, the engine won’t try to process it any +more.
+aceCreateDomLine
+Called from: src/static/js/domline.js
Things in context:
+-
+
-
+
domline - the current DOM line being processed
+
+ -
+
cls - The class of the current element (useful for styling)
+
+
This hook is called for any line being processed by the formatting engine, +unless the aceDomLineProcessLineAttributes hook from above returned true, in +which case this hook is skipped.
+The return value of this hook should have the following structure:
+{ extraOpenTags: String, extraCloseTags: String, cls: String }
extraOpenTags and extraCloseTags will be added before and after the element in +question, and cls will be the new class of the element going forward.
+acePostWriteDomLineHTML
+Called from: src/static/js/domline.js
Things in context:
+-
+
-
+
node - the DOM node that just got written to the page
+
+
This hook is for right after a node has been fully formatted and written to the +page.
+aceAttribsToClasses
+Called from: src/static/js/linestylefilter.js
Things in context:
+-
+
-
+
linestylefilter - the JavaScript object that’s currently processing the ace +attributes
+
+ -
+
key - the current attribute being processed
+
+ -
+
value - the value of the attribute being processed
+
+
This hook is called during the attribute processing procedure, and should be +used to translate key, value pairs into valid HTML classes that can be inserted +into the DOM.
+The return value for this function should be a list of classes, which will then +be parsed into a valid class string.
+aceAttribClasses
+Called from: src/static/js/linestylefilter.js
Things in context: +1. Attributes - Object of Attributes
+This hook is called when attributes are investigated on a line. It is useful if +you want to add another attribute type or property type to a pad.
+Example:
+exports.aceAttribClasses = function(hook_name, attr, cb){
+ attr.sub = 'tag:sub';
+ cb(attr);
+}aceGetFilterStack
+Called from: src/static/js/linestylefilter.js
Things in context:
+-
+
-
+
linestylefilter - the JavaScript object that’s currently processing the ace +attributes
+
+ -
+
browser - an object indicating which browser is accessing the page
+
+
This hook is called to apply custom regular expression filters to a set of
+styles. The one example available is the ep_linkify plugin, which adds internal
+links. They use it to find the telltale [[ ]] syntax that signifies internal
+links, and finding that syntax, they add in the internalHref attribute to be
+later used by the aceCreateDomLine hook (documented above).
aceEditorCSS
+Called from: src/static/js/ace.js
Things in context: None
+This hook is provided to allow custom CSS files to be loaded. The return value +should be an array of resource urls or paths relative to the plugins directory.
+aceInitInnerdocbodyHead
+Called from: src/static/js/ace.js
Things in context:
+-
+
-
+
iframeHTML - the HTML of the editor iframe up to this point, in array format
+
+
This hook is called during the creation of the editor HTML. The array should
+have lines of HTML added to it, giving the plugin author a chance to add in
+meta, script, link, and other tags that go into the <head> element of the
+editor HTML document.
aceEditEvent
+Called from: src/static/js/ace2_inner.js
Things in context:
+-
+
-
+
callstack - a bunch of information about the current action
+
+ -
+
editorInfo - information about the user who is making the change
+
+ -
+
rep - information about where the change is being made
+
+ -
+
documentAttributeManager - information about attributes in the document (this +is a mystery to me)
+
+
This hook is made available to edit the edit events that might occur when +changes are made. Currently you can change the editor information, some of the +meanings of the edit, and so on. You can also make internal changes (internal to +your plugin) that use the information provided by the edit event.
+aceRegisterNonScrollableEditEvents
+Called from: src/static/js/ace2_inner.js
Things in context: None
+When aceEditEvent (documented above) finishes processing the event, it scrolls +the viewport to make caret visible to the user, but if you don’t want that +behavior to happen you can use this hook to register which edit events should +not scroll viewport. The return value of this hook should be a list of event +names.
+Example:
+exports.aceRegisterNonScrollableEditEvents = function(){
+ return [ 'repaginate', 'updatePageCount' ];
+}aceRegisterBlockElements
+Called from: src/static/js/ace2_inner.js
Things in context: None
+The return value of this hook will add elements into the "lineMarkerAttribute" +category, making the aceDomLineProcessLineAttributes hook (documented below) +call for those elements.
+aceInitialized
+Called from: src/static/js/ace2_inner.js
Things in context:
+-
+
-
+
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)
+
+ -
+
rep - information about where the user’s cursor is
+
+ -
+
documentAttributeManager - some kind of magic
+
+
This hook is for inserting further information into the ace engine, for later +use in formatting hooks.
+postAceInit
+Called from: src/static/js/pad.js
Things in context:
+-
+
-
+
ace - the ace object that is applied to this editor.
+
+ -
+
clientVars - Object containing client-side configuration such as author ID +and plugin settings. Your plugin can manipulate this object via the +
+clientVarsserver-side hook.
+ -
+
pad - the pad object of the current pad.
+
+
postToolbarInit
+Called from: src/static/js/pad_editbar.js
Things in context:
+-
+
-
+
ace - the ace object that is applied to this editor.
+
+ -
+
toolbar - Editbar instance. See below for the Editbar documentation.
+
+
Can be used to register custom actions to the toolbar.
+Usage examples:
+postTimesliderInit
+Called from: src/static/js/timeslider.js
There doesn’t appear to be any example available of this particular hook being +used, but it gets fired after the timeslider is all set up.
+goToRevisionEvent
+Called from: src/static/js/broadcast.js
Things in context:
+-
+
-
+
rev - The newRevision
+
+
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:
+-
+
-
+
info - the user information
+
+
This hook is called on the client side whenever a user joins or changes. This +can be used to create notifications or an alternate user list.
+chatNewMessage
+Called from: src/static/js/chat.js
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 thatmessage.textis not sanitized or processed +in any way.)
+ -
+
+message: The raw message object as received from the server, except with +time correction and a defaultauthorIdproperty if missing. Plugins must not +modify this object. Warning: Unliketext,message.textis 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 tonull, 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:
+-
+
-
+
cc - the contentcollector object
+
+ -
+
state - the current state of the change being made
+
+ -
+
tname - the tag name of this node currently being processed
+
+ -
+
styl - the style applied to the node (probably CSS) — Note the typo
+
+ -
+
cls - the HTML class string of the node
+
+
This hook is called before the content of a node is collected by the usual +methods. The cc object can be used to do a bunch of things that modify the +content of the pad. See, for example, the heading1 plugin for etherpad original.
+E.g. if you need to apply an attribute to newly inserted characters, call +cc.doAttrib(state, "attributeName") which results in an attribute +attributeName=true.
+If you want to specify also a value, call cc.doAttrib(state, +"attributeName::value") which results in an attribute attributeName=value.
+collectContentImage
+Called from: src/static/js/contentcollector.js
+Things in context:
+-
+
-
+
cc - the contentcollector object
+
+ -
+
state - the current state of the change being made
+
+ -
+
tname - the tag name of this node currently being processed
+
+ -
+
style - the style applied to the node (probably CSS)
+
+ -
+
cls - the HTML class string of the node
+
+ -
+
node - the node being modified
+
+
This hook is called before the content of an image node is collected by the +usual methods. The cc object can be used to do a bunch of things that modify the +content of the pad.
+Example:
+exports.collectContentImage = function(name, context){
+ context.state.lineAttributes.img = context.node.outerHTML;
+}collectContentPost
+Called from: src/static/js/contentcollector.js
+Things in context:
+-
+
-
+
cc - the contentcollector object
+
+ -
+
state - the current state of the change being made
+
+ -
+
tname - the tag name of this node currently being processed
+
+ -
+
style - the style applied to the node (probably CSS)
+
+ -
+
cls - the HTML class string of the node
+
+
This hook is called after the content of a node is collected by the usual +methods. The cc object can be used to do a bunch of things that modify the +content of the pad. See, for example, the heading1 plugin for etherpad original.
+handleClientMessage_`name`
+Called from: src/static/js/collab_client.js
Things in context:
+-
+
-
+
payload - the data that got sent with the message (use it for custom message +content)
+
+
This hook gets called every time the client receives a message of type name.
+This can most notably be used with the new HTTP API call, "sendClientsMessage",
+which sends a custom message type to all clients connected to a pad. You can
+also use this to handle existing types.
collab_client.js has a pretty extensive list of message types, if you want to
+take a look.
aceStartLineAndCharForPoint-aceEndLineAndCharForPoint
+Called from: src/static/js/ace2_inner.js
+Things in context:
+-
+
-
+
callstack - a bunch of information about the current action
+
+ -
+
editorInfo - information about the user who is making the change
+
+ -
+
rep - information about where the change is being made
+
+ -
+
root - the span element of the current line
+
+ -
+
point - the starting/ending element where the cursor highlights
+
+ -
+
documentAttributeManager - information about attributes in the document
+
+
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:
+-
+
-
+
callstack - a bunch of information about the current action
+
+ -
+
editorInfo - information about the user who is making the change
+
+ -
+
rep - information about where the change is being made
+
+ -
+
documentAttributeManager - information about attributes in the document
+
+ -
+
evt - the fired event
+
+
This hook is provided to allow a plugin to handle key events. +The return value should be true if you have handled the event.
+collectContentLineText
+Called from: src/static/js/contentcollector.js
+Things in context:
+-
+
-
+
cc - the contentcollector object
+
+ -
+
state - the current state of the change being made
+
+ -
+
tname - the tag name of this node currently being processed
+
+ -
+
text - the text for that line
+
+
This hook allows you to validate/manipulate the text before it’s sent to the +server side. To change the text, either:
+-
+
-
+
Set the
+textcontext property to the desired value and returnundefined.
+ -
+
(Deprecated) Return a string. If a hook function changes the
+textcontext +property, the return value is ignored. If no hook function changestextbut +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:
+-
+
-
+
cc - the contentcollector object
+
+ -
+
state - the current state of the change being made
+
+ -
+
tname - the tag name of this node currently being processed
+
+
This hook is provided to allow whether the br tag should induce a new magic +domline or not. The return value should be either true(break the line) or false.
+disableAuthorColorsForThisLine
+Called from: src/static/js/linestylefilter.js
+Things in context:
+-
+
-
+
linestylefilter - the JavaScript object that’s currently processing the ace +attributes
+
+ -
+
text - the line text
+
+ -
+
class - line class
+
+
This hook is provided to allow whether a given line should be deliniated with +multiple authors. Multiple authors in one line cause the creation of magic span +lines. This might not suit you and now you can disable it and handle your own +deliniation. The return value should be either true(disable) or false.
+aceSetAuthorStyle
+Called from: src/static/js/ace2_inner.js
+Things in context:
+-
+
-
+
dynamicCSS - css manager for inner ace
+
+ -
+
outerDynamicCSS - css manager for outer ace
+
+ -
+
parentDynamicCSS - css manager for parent document
+
+ -
+
info - author style info
+
+ -
+
author - author info
+
+ -
+
authorSelector - css selector for author span in inner ace
+
+
This hook is provided to allow author highlight style to be modified. Registered +hooks should return 1 if the plugin handles highlighting. If no plugin returns +1, the core will use the default background-based highlighting.
+aceSelectionChanged
+Called from: src/static/js/ace2_inner.js
+Things in context:
+-
+
-
+
rep - information about where the user’s cursor is
+
+ -
+
documentAttributeManager - information about attributes in the document
+
+
This hook allows a plugin to react to a cursor or selection change, +perhaps to update a UI element based on the style at the cursor location.
+Server-side hooks
+These hooks are called on server-side.
+loadSettings
+Called from: src/node/server.ts
Things in context:
+-
+
-
+
settings - the settings object
+
+
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:
+-
+
-
+
plugin_name - self-explanatory
+
+
If this hook returns an error, the callback to the uninstall function gets an error as well. This mostly seems useful for handling additional features added in based on the installation of other plugins, which is pretty cool!
+pluginInstall
+Called from: src/static/js/pluginfw/installer.js
Things in context:
+-
+
-
+
plugin_name - self-explanatory
+
+
If this hook returns an error, the callback to the install function gets an error, too. This seems useful for adding in features when a particular plugin is installed.
+init_<plugin name>
+Called from: src/static/js/pluginfw/plugins.js
Run during startup after the named plugin is initialized.
+Context properties:
+-
+
-
+
+logger: An object with the followingconsole-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:
+-
+
-
+
+app: The Express Application +object.
+
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:
+-
+
-
+
+app: The Express Application +object.
+
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:
+-
+
-
+
+app: The Express Application +object.
+ -
+
+server: The http.Server +or https.Server object.
+
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:
+-
+
-
+
content - the content of the block
+
+
This hook gets called upon the rendering of an ejs template block. For any specific kind of block, you can change how that block gets rendered by modifying the content object passed in.
+Available blocks in pad.html are:
-
+
-
+
+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 theindex.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 theindex.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:
+-
+
-
+
toolbar - the toolbar controller that will render the toolbar eventually
+
+
Here you can add custom toolbar items that will be available in the toolbar config in settings.json. For more about the toolbar controller see the API section.
Usage examples:
+onAccessCheck
+Called from: src/node/db/SecurityManager.js
+Things in context:
+-
+
-
+
padID - the real ID (never the read-only ID) of the pad the user wants to +access
+
+ -
+
token - the token of the author
+
+ -
+
sessionCookie - the session the use has
+
+
This hook gets called when the access to the concrete pad is being checked.
+Return false to deny access.
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 thetokencontext 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 thetokencontext +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 formt.<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 fromsettings.users+(or similar from an authentication plugin). Etherpad core and all good +authentication plugins set theusernameproperty 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 ofauthorId.
+
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 readingcontent.
+ -
+
+content: The pad’s initial content. Change this property to change the pad’s +initial content. If the content type is changed, thetypeproperty must also +be updated to match. Plugins must check the value of thetypeproperty +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 ofauthorId.
+ -
+
+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:
+-
+
-
+
Destination pad is deleted if it exists and overwrite is permitted. This +causes the
+padRemovehook to run.
+ -
+
Pad-specific database records are copied in the database, except for +records with plugin-specific database keys.
+
+ -
+
A new Pad object is created for the destination pad. This causes the +
+padLoadhook to run.
+ -
+
This hook runs.
+
+
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:
+-
+
-
+
app - the application object
+
+ -
+
io - the socketio object
+
+ -
+
server - the http server object
+
+
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 +preAuthorizehook function, or to the normal authentication and +authorization checks if no morepreAuthorizehook functions remain.
+ -
+
+true(or[true]) immediately grants access to the requested resource, +unless the request is for an/adminpage in which case it is treated the +same as returningundefined. (This prevents buggy plugins from accidentally +granting admin access to the general public.)
+ -
+
+false(or[false]) immediately denies the request. ThepreAuthnFailure+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:
+-
+
-
+
req - the request object
+
+ -
+
res - the response object
+
+ -
+
next - ?
+
+ -
+
resource - the path being accessed
+
+
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
+requireAuthenticationandrequireAuthorizationsettings 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
+/adminpath (/adminpaths 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 ifsettings.editOnlyis true or the user’s +canCreatesetting is set tofalse, and downgraded to read-only if the +user’sreadOnlysetting istrue.
+ -
+
+['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’sreadOnlysetting istrue.
+ -
+
+['readOnly']will grant read-only access.
+ -
+
+[false]will deny access.
+ -
+
+[]orundefinedwill 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:
+-
+
-
+
req - the request object
+
+ -
+
res - the response object
+
+ -
+
users - the users object from settings.json (possibly modified by plugins)
+
+ -
+
next - ?
+
+ -
+
username - the username used (optional)
+
+ -
+
password - the password used (optional)
+
+
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:
+-
+
-
+
req - the request object
+
+ -
+
res - the response object
+
+ -
+
next - ?
+
+
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:
+-
+
-
+
req - the request object
+
+ -
+
res - the response object
+
+
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:
+-
+
-
+
req - the request object
+
+ -
+
res - the response object
+
+
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:
+-
+
-
+
req - the request object
+
+ -
+
res - the response object
+
+
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; usesocketinstead.) Synonym ofsocket.
+
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 +COLLABROOMmessage only. Has no effect if the current message is not a +COLLABROOMmessage, or if the user already has write access to the pad.
+ -
+
+true: (Deprecated; return'permitOnce'instead.) Override the user’s +read-only access for allCOLLABROOMmessages from the same socket.io +connection (including the current message, if applicable) until the client’s +nextCLIENT_READYmessage. Has no effect if the user already has write +access to the pad. Read-only access is reset after eachCLIENT_READY+message, so returningtruehas no effect forCLIENT_READYmessages.
+
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; usesocketinstead.) Synonym ofsocket.
+
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:
+-
+
-
+
clientVars - the basic
+clientVarsbuilt by the core
+ -
+
pad - the pad this session is about
+
+ -
+
socket - the socket.io Socket object
+
+
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:
+-
+
-
+
padId
+
+
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:
+-
+
-
+
padId - The Pad Id
+
+
This hook will allow a plug-in developer to append Styles to the Exported HTML.
+Example:
+exports.stylesForExport = function(hook, padId, cb){
+ cb("body{font-size:13.37em !important}");
+}aceAttribClasses
+Called from: src/static/js/linestylefilter.js
+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:
+-
+
-
+
padId
+
+
This hook will allow a plug-in developer to modify the file name of an exported pad. This is useful if you want to export a pad under another name and/or hide the padId under export. Note that the doctype or file extension cannot be modified for security reasons.
+Example:
+exports.exportFileName = function(hook, padId, callback){
+ callback("newFileName"+padId);
+}exportHtmlAdditionalTags
+Called from src/node/utils/ExportHtml.js
+Things in context:
+-
+
-
+
Pad object
+
+
This hook will allow a plug-in developer to include more properties and attributes to support during HTML Export. If tags are stored as ['color', 'red'] on the attribute pool, use exportHtmlAdditionalTagsWithData instead. An Array should be returned.
Example:
+// Add the props to be supported in export
+exports.exportHtmlAdditionalTags = function(hook, pad, cb){
+ var padId = pad.id;
+ cb(["massive","jugs"]);
+};exportHtmlAdditionalTagsWithData
+Called from src/node/utils/ExportHtml.js
+Things in context:
+-
+
-
+
Pad object
+
+
Identical to exportHtmlAdditionalTags, but for tags that are stored with a specific value (not simply true) on the attribute pool. For example ['color', 'red'], instead of ['bold', true]. This hook will allow a plug-in developer to include more properties and attributes to support during HTML Export. An Array of arrays should be returned. The exported HTML will contain tags like <span data-color="red"> for the content where attributes are ['color', 'red'].
Example:
+// Add the props to be supported in export
+exports.exportHtmlAdditionalTagsWithData = function(hook, pad, cb){
+ var padId = pad.id;
+ cb([["color", "red"], ["color", "blue"]]);
+};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 +exportEtherpadAdditionalContenthook. 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 +todata(instead ofpad.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 +.etherpadfile. Thepad.dbobject is a temporary in-memory database +whose records will be copied to the real database after they are validated +(see thepadCheckhook). Registered hook functions MUST NOT use the real +database to access (read or write) pad-specific records; they MUST instead +usepad.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.etherpadfile. This data must not be +modified.
+ -
+
+srcPadId: The pad ID used for the pad-specific information indata.
+
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 fromsrcFilewith 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 thechatNewMessageclient-side hook. The message’sauthorId+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 asdata-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).
+