name
<plugin name>
<name>
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
.
Etherpad keeps track of the goings-on inside the edit machinery. If you'd like to have a look at this, just point your browser to /stats
.
We currently measure:
Under the hood, we are happy to rely on measured for all our metrics needs.
To modify or simply access our stats in your plugin, simply require('ep_etherpad-lite/stats')
which is a measured.Collection
.
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.
We rely on https://translatewiki.net to handle the translation process for us, so if you'd like to help...
Translate Etherpad lite interface
Fetch
Translations will be send back to us regularly and will eventually appear in the next release.
/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.
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.
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'));
.json
en.json
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.
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"
}
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"
}
}
The official Docker image is available on https://hub.docker.com/r/etherpad/etherpad.
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
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.
Edit <BASEDIR>/settings.json.docker
at your will. When rebuilding the image, this file will be copied inside your image and renamed to setting.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
.
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
.
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.
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
.
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
.
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 .
To run your instance:
docker run --detach --publish <DESIRED_PORT>:9001 <YOUR_USERNAME>/etherpad
And point your browser to http://<YOUR_IP>:<DESIRED_PORT>
The settings.json.docker
available by default allows to control almost every setting via environment variables.
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) |
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).
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 |
false |
|
PAD_OPTIONS_USER_COLOR |
false |
|
PAD_OPTIONS_RTL |
false |
|
PAD_OPTIONS_ALWAYS_SHOW_CHAT |
false |
|
PAD_OPTIONS_CHAT_AND_USERS |
false |
|
PAD_OPTIONS_LANG |
en-gb |
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 |
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:
For each of the 3 containers you can choose 4 color combinations:
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 |
Variable | Description | Default |
---|---|---|
LOGLEVEL |
valid values are DEBUG , INFO , WARN and ERROR |
INFO |
DISABLE_IP_LOGGING |
Privacy: disable IP logging | false |
Variable | Description | Default |
---|---|---|
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 |
TIDY_HTML |
Path to the Tidy executable. Tidy is used to improve the quality of exported pads. Setting it to null disables Tidy. | 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 |
LOAD_TEST |
Allow Load Testing tools to hit the Etherpad Instance. WARNING: this will disable security on the instance. | false |
EXPOSE_VERSION |
Expose Etherpad version in the web interface and in the Server http header. Do not enable on production machines. | false |
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
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 faviconrobots.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.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>
Default: true
Default: true
Default: true
Default: false
Default: "unnamed"
Example: userName=Etherpad%20User
Default: randomly chosen by pad server
Example: userColor=%23ff9900
Default: false
Default: false
Default: en
Example: lang=ar
(translates the interface into Arabic)
Default: true Displays pad text from right to left.
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
The API gives another web application control of the pads. The basic functions are
The API is designed in a way, so you can reuse your existing user system with their permissions, and map it to Etherpad. Means: Your web application still has to do authentication, but you can tell Etherpad via the api, which visitors should get which permissions. This allows Etherpad to fit into any web application and extend it with real-time functionality. You can embed the pads via an iframe into your website.
Take a look at HTTP API client libraries to check if a library in your favorite programming language is available.
OpenAPI (formerly swagger) definitions are exposed under /api/openapi.json
(latest) and /api/{version}/openapi.json
. You can use official tools like Swagger Editor to view and explore them.
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.
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)
The latest version is 1.2.14
The current version can be queried via /api.
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"
Responses are valid JSON in the following format:
{
"code": number,
"message": string,
"data": obj
}
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.
All functions will also be available through a node module accessible from other node.js applications.
Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test
creates a new group
Example returns:
{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}
this functions helps you to map your application group ids to Etherpad group ids
Example returns:
{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}
deletes a group
Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"groupID does not exist", data: null}
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}
creates a new pad in this group
Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"pad does already exist", data: null}
{code: 1, message:"groupID does not exist", data: null}
lists all existing groups
Example returns:
{code: 0, message:"ok", data: {groupIDs: ["g.mKjkmnAbSMtCt8eL", "g.3ADWx6sbGuAiUmCy"]}}
{code: 0, message:"ok", data: {groupIDs: []}}
These authors are bound to the attributes the users choose (color and name).
creates a new author
Example returns:
{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}
this functions helps you to map your application author ids to Etherpad author ids
Example returns:
{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}
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}
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
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.
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}
deletes a session
Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"sessionID does not exist", data: null}
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}
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}
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 can be updated and retrieved through the API
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}
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}
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}
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}
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}
returns the attribute pool of a pad
Example returns:
"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}
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}
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}
Restores revision from past as new changeset
Example returns:
returns
start
and end
are givenExample 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}
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}
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}
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.
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}
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}
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}
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}
saves a revision
Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
returns the number of user that are currently editing this pad
Example returns:
{code: 0, message:"ok", data: {padUsersCount: 5}}
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: []}}
deletes a pad
Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
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}
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}
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}
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}
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}
sets a boolean for the public status of a pad
Example returns:
{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
return true of false
Example returns:
{code: 0, message:"ok", data: {publicStatus: true}}
{code: 1, message:"padID does not exist", data: null}
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}
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}
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}
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}
lists all pads on this epl instance
Example returns:
{code: 0, message:"ok", data: {padIDs: ["testPad", "thePadsOfTheOthers"]}}
get stats of the etherpad instance
Example returns
{"code":0,"message":"ok","data":{"totalPads":3,"totalSessions": 2,"totalActivePads": 1}}
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).
Note: The documentation in this section applies to every hook unless the hook-specific documentation says otherwise.
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 returns undefined
.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:
undefined
is acceptable) and
return undefined
, in that order.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.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:
undefined
and call the callback, in either order.undefined
(null
is acceptable) and never call
the callback. Note that async
functions always return a Promise, so they
must never call the callback.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.
A hook function can provide a value to Etherpad in one of the following ways:
undefined
unless
the hook function only has two parameters. (Hook functions with three
parameters that want to provide undefined
should instead use 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]
.
Most of these hooks are called during or in order to set up the formatting process.
Called from: src/templates/pad.html
Things in context:
nothing
This hook proxies the functionality of jQuery's $(document).ready
event.
Called from: src/static/js/domline.js
Things in context:
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.
Called from: src/static/js/domline.js
Things in context:
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.
Called from: src/static/js/domline.js
Things in context:
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.
Called from: src/static/js/domline.js
Things in context:
This hook is for right after a node has been fully formatted and written to the page.
Called from: src/static/js/linestylefilter.js
Things in context:
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.
Called from: src/static/js/linestylefilter.js
Things in context:
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);
}
Called from: src/static/js/linestylefilter.js
Things in context:
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).
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.
Called from: src/static/js/ace.js
Things in context:
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.
Called from: src/static/js/ace2_inner.js
Things in context:
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.
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' ];
}
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.
Called from: src/static/js/ace2_inner.js
Things in context:
This hook is for inserting further information into the ace engine, for later use in formatting hooks.
Called from: src/static/js/pad.js
Things in context:
Called from: src/static/js/pad_editbar.js
Things in context:
Can be used to register custom actions to the toolbar.
Usage examples:
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.
Called from: src/static/js/broadcast.js
Things in context:
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.
Called from: src/static/js/pad_userlist.js
Things in context:
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.
Called from: src/static/js/chat.js
Things in context:
This hook is called on the client side whenever a chat message is received from
the server. It can be used to create different notifications for chat messages.
Hoook functions can modify the author
, authorName
, duration
, sticky
,
text
, and timeStr
context properties to change how the message is processed.
The text
and timeStr
properties may contain HTML, but plugins should be
careful to sanitize any added user input to avoid introducing an XSS
vulnerability.
Called from: src/static/js/contentcollector.js
Things in context:
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.
Called from: src/static/js/contentcollector.js
Things in context:
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;
}
Called from: src/static/js/contentcollector.js
Things in context:
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.
name
Called from: src/static/js/collab_client.js
Things in context:
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.
Called from: src/static/js/ace2_inner.js
Things in context:
This hook is provided to allow a plugin to turn DOM node selection into [line,char] selection. The return value should be an array of [line,char]
Called from: src/static/js/ace2_inner.js
Things in context:
This hook is provided to allow a plugin to handle key events. The return value should be true if you have handled the event.
Called from: src/static/js/contentcollector.js
Things in context:
This hook allows you to validate/manipulate the text before it's sent to the server side. To change the text, either:
text
context property to the desired value and return undefined
.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);
};
Called from: src/static/js/contentcollector.js
Things in context:
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.
Called from: src/static/js/linestylefilter.js
Things in context:
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.
Called from: src/static/js/ace2_inner.js
Things in context:
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.
Called from: src/static/js/ace2_inner.js
Things in context:
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.
These hooks are called on server-side.
Called from: src/node/server.js
Things in context:
Use this hook to receive the global settings in your plugin.
Called from: src/node/server.js
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();
};
Called from: src/static/js/pluginfw/installer.js
Things in context:
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!
Called from: src/static/js/pluginfw/installer.js
Things in context:
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.
<plugin name>
Called from: src/static/js/pluginfw/plugins.js
Things in context: None
This function is called after a specific plugin is initialized. This would probably be more useful than the previous two functions if you only wanted to add in features to one specific plugin.
Called from: src/node/hooks/express.js
Things in context:
This is a helpful hook for changing the behavior and configuration of the application. It's called right after the application gets configured.
Called from: src/node/hooks/express.js
Things in context:
This hook gets called after the application object has been created, but before it starts listening. This is similar to the expressConfigure hook, but it's not guaranteed that the application object will have all relevant configuration variables.
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();
};
<name>
Called from: src/node/eejs/index.js
Things in context:
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 tagstyles
- the style <link>
sbody
- the contents of the body tageditbarMenuLeft
- the left tool bar (consider using the toolbar controller instead of manually adding html here)editbarMenuRight
- right tool barafterEditbar
- allows you to add stuff immediately after the toolbaruserlist
- the contents of the userlist dropdownloading
- the initial loading messagemySettings
- the left column of the settings dropdown ("My view"); intended for adding checkboxes onlymySettings.dropdowns
- add your dropdown settings hereglobalSettings
- the right column of the settings dropdown ("Global view")importColumn
- import formexportColumn
- export formmodals
- Contains all connectivity messagesembedPopup
- the embed dropdownscripts
- 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 skinindexWrapper
- contains the form for creating new padsindexCustomScripts
- contains the index.js
<script>
tag, allows you to add your own or to customize the one provided by the active skinCalled from: src/node/hooks/express/specialpages.js
Things in context:
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:
Called from: src/node/db/SecurityManager.js
Things in context:
This hook gets called when the access to the concrete pad is being checked.
Return false
to deny access.
Called from: src/node/db/Pad.js
Things in context:
This hook gets called when a new pad was created.
Called from: src/node/db/Pad.js
Things in context:
This hook gets called when a pad was loaded. If a new pad was created and loaded this event will be emitted too.
Called from: src/node/db/Pad.js
Things in context:
This hook gets called when an existing pad was updated.
Called from: src/node/db/Pad.js
Things in context:
This hook gets called when an existing pad was copied.
Usage examples:
Called from: src/node/db/Pad.js
Things in context:
This hook gets called when an existing pad was removed/deleted.
Usage examples:
Called from: src/node/hooks/express/socketio.js
Things in context:
I have no idea what this is useful for, someone else will have to add this description.
Called from: src/node/hooks/express/webaccess.js
Things in context:
This hook is called for each HTTP request before any authentication checks are performed. Example uses:
A preAuthorize function is always called for each request unless a preAuthorize function from another plugin (if any) has already explicitly granted or denied the request.
You can pass the following values to the provided callback:
[]
defers the access decision to the normal authentication and authorization
checks (or to a preAuthorize function from another plugin, if one exists).[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 []
.
(This prevents buggy plugins from accidentally granting admin access to the
general public.)[false]
immediately denies the request. The preAuthnFailure hook will be
called to handle the failure.Example:
exports.preAuthorize = (hookName, context, cb) => {
if (ipAddressIsFirewalled(context.req)) return cb([false]);
if (requestIsForStaticContent(context.req)) return cb([true]);
if (requestIsForOAuthCallback(context.req)) return cb([true]);
return cb([]);
};
Called from: src/node/hooks/express/webaccess.js
Things in context:
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:
requireAuthentication
and requireAuthorization
settings are both true./admin
path (/admin
paths can only be
accessed by admin users, and admin users are always authorized).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
};
Called from: src/node/hooks/express/webaccess.js
Things in context:
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]);
};
Called from: src/node/hooks/express/webaccess.js
Things in context:
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:
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]);
};
Called from: src/node/hooks/express/webaccess.js
Things in context:
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]);
};
Called from: src/node/hooks/express/webaccess.js
Things in context:
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]);
};
Called from: src/node/hooks/express/webaccess.js
Things in context:
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([]);
};
Called from: src/node/handler/PadMessageHandler.js
Things in context:
This hook allows plugins to drop or modify incoming socket.io messages from clients, before Etherpad processes them.
The handleMessage function must return a Promise. If the Promise resolves to
null
, the message is dropped. Returning callback(value)
will return a
Promise that is resolved to value
.
Examples:
// Using an async function:
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;
}
};
// Using a regular function:
exports.handleMessage = (hookName, {message, socket}, callback) => {
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;
}
return callback();
};
Called from: src/node/handler/PadMessageHandler.js
Things in context:
This hook allows plugins to grant temporary write access to a pad. It is called
for each incoming message from a client. If write access is granted, it applies
to the current message and all future messages from the same socket.io
connection until the next CLIENT_READY
or SWITCH_TO_PAD
message. Read-only
access is reset after each CLIENT_READY
or SWITCH_TO_PAD
message, so
granting write access has no effect for those message types.
The handleMessageSecurity function must return a Promise. If the Promise
resolves to true
, write access is granted as described above. Returning
callback(value)
will return a Promise that is resolved to value
.
Examples:
// Using an async function:
exports.handleMessageSecurity = async (hookName, {message, socket}) => {
if (shouldGrantWriteAccess(message, socket)) return true;
return;
};
// Using a regular function:
exports.handleMessageSecurity = (hookName, {message, socket}, callback) => {
if (shouldGrantWriteAccess(message, socket)) return callback(true);
return callback();
};
Called from: src/node/handler/PadMessageHandler.js
Things in context:
clientVars
built by the coreThis 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:
clientVars
via
Object.assign()
, so any keys that already exist in clientVars
will be
overwritten by the values in the returned object.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>'});
};
Called from: src/node/utils/ExportHtml.js
Things in context:
This hook will allow a plug-in developer to re-write each line when exporting to HTML.
Example:
var Changeset = require("ep_etherpad-lite/static/js/Changeset");
exports.getLineHTMLForExport = function (hook, context) {
var header = _analyzeLine(context.attribLine, context.apool);
if (header) {
return "<" + header + ">" + context.lineContent + "</" + header + ">";
}
}
function _analyzeLine(alineAttrs, apool) {
var header = null;
if (alineAttrs) {
var opIter = Changeset.opIterator(alineAttrs);
if (opIter.hasNext()) {
var op = opIter.next();
header = Changeset.opAttributeValue(op, 'heading', apool);
}
}
return header;
}
Called from: src/node/utils/ExportHtml.js
Things in context:
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;
};
Called from: src/node/utils/ExportHtml.js
Things in context:
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}");
}
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',
}]);
};
Called from src/node/handler/ExportHandler.js
Things in context:
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);
}
Called from src/node/utils/ExportHtml.js
Things in context:
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"]);
};
Called from src/node/utils/ExportHtml.js
Things in context:
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"]]);
};
Called from src/node/utils/ExportEtherpad.js and src/node/utils/ImportEtherpad.js
Things in context: Nothing
Useful for exporting and importing pad metadata that is stored in the database
but not in the pad's content or attributes. For example, in ep_comments_page the
comments are stored as comments:padId:uniqueIdOfComment
so a complete export
of all pad data to an .etherpad
file must include the comments:padId:*
records.
Example:
// Add support for exporting comments metadata
exports.exportEtherpadAdditionalContent = () => ['comments'];
Called from src/node/handler/PadMessageHandler.js
This in context:
This hook gets called when an author leaves a pad. This is useful if you want to perform certain actions after a pad has been edited
Example:
exports.userLeave = function(hook, session, callback) {
console.log('%s left pad %s', session.author, session.padId);
};
Called from src/node/handler/PadMessageHandler.js
This in context:
This hook gets called when handling a CLIENT_READY which is the first message from the client to the server.
Example:
exports.clientReady = function(hook, message) {
console.log('Client has entered the pad' + message.padId);
};
This function replaces a range (from start
to end
) with text
.
Returns the rep
object.
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
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.
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.
This function replaces a range (from [x1,y1] to [x2,y2]) with newText
.
This function replaces a range (from y1 to y2) with newText
.
If you delete a line, calling this method will fix the line numbering.
Forces a return key at the current caret position.
Returns true if your passed element is registered as a block element
Returns the line's html list type.
Returns X position of the caret.
Returns Y position of the caret.
Returns the Y offset starting from [x=0,y=0]
"Z:z>1|2=m=b*0|1+1$\n"
This is a Changeset. It's just a string and it's very difficult to read in this form. But the Changeset Library gives us some tools to read it.
A changeset describes the diff between two revisions of the document. The Browser sends changesets to the server and the server sends them to the clients to update them. These Changesets also get saved into the history of a pad. This allows us to go back to every revision from the past.
changeset
{String}This function returns an object representation of the changeset, similar to this:
{ oldLen: 35, newLen: 36, ops: '|2=m=b*0|1+1', charBank: '\n' }
oldLen
{Number} the original length of the document.newLen
{Number} the length of the document after the changeset is applied.ops
{String} the actual changes, introduced by this changeset.charBank
{String} All characters that are added by this changeset.ops
{String} The operators, returned by Changeset.unpack()
Returns an operator iterator. This iterator allows us to iterate over all operators that are in the changeset.
You can iterate with an opIterator using its next()
and hasNext()
methods. Next returns the next()
operator object and hasNext()
indicates, whether there are any operators left.
There are 3 types of operators: +
,-
and =
. These operators describe different changes to the document, beginning with the first character of the document. A =
operator doesn't change the text, but it may add or remove text attributes. A -
operator removes text. And a +
Operator adds text and optionally adds some attributes to it.
opcode
{String} the operator typechars
{Number} the length of the text changed by this operator.lines
{Number} the number of lines changed by this operator.attribs
{attribs} attributes set on this text.{ opcode: '+',
chars: 1,
lines: 1,
attribs: '*0' }
> var AttributePoolFactory = require("./utils/AttributePoolFactory");
> var apool = AttributePoolFactory.createAttributePool();
> console.log(apool)
{ numToAttrib: {},
attribToNum: {},
nextNum: 0,
putAttrib: [Function],
getAttrib: [Function],
getAttribKey: [Function],
getAttribValue: [Function],
eachAttrib: [Function],
toJsonable: [Function],
fromJsonable: [Function] }
This creates an empty apool. An apool saves which attributes were used during the history of a pad. There is one apool for each pad. It only saves the attributes that were really used, it doesn't save unused attributes. Let's fill this apool with some values
> apool.fromJsonable({"numToAttrib":{"0":["author","a.kVnWeomPADAT2pn9"],"1":["bold","true"],"2":["italic","true"]},"nextNum":3});
> console.log(apool)
{ numToAttrib:
{ '0': [ 'author', 'a.kVnWeomPADAT2pn9' ],
'1': [ 'bold', 'true' ],
'2': [ 'italic', 'true' ] },
attribToNum:
{ 'author,a.kVnWeomPADAT2pn9': 0,
'bold,true': 1,
'italic,true': 2 },
nextNum: 3,
putAttrib: [Function],
getAttrib: [Function],
getAttribKey: [Function],
getAttribValue: [Function],
eachAttrib: [Function],
toJsonable: [Function],
fromJsonable: [Function] }
We used the fromJsonable function to fill the empty apool with values. the fromJsonable and toJsonable functions are used to serialize and deserialize an apool. You can see that it stores the relation between numbers and attributes. So for example the attribute 1 is the attribute bold and vise versa. An attribute is always a key value pair. For stuff like bold and italic it's just 'italic':'true'. For authors it's author:$AUTHORID. So a character can be bold and italic. But it can't belong to multiple authors
> apool.getAttrib(1)
[ 'bold', 'true' ]
Simple example of how to get the key value pair for the attribute 1
> var atext = {"text":"bold text\nitalic text\nnormal text\n\n","attribs":"*0*1+9*0|1+1*0*1*2+b|1+1*0+b|2+2"};
> console.log(atext)
{ text: 'bold text\nitalic text\nnormal text\n\n',
attribs: '*0*1+9*0|1+1*0*1*2+b|1+1*0+b|2+2' }
This is an atext. An atext has two parts: text and attribs. The text is just the text of the pad as a string. We will look closer at the attribs at the next steps
> var opiterator = Changeset.opIterator(atext.attribs)
> console.log(opiterator)
{ next: [Function: next],
hasNext: [Function: hasNext],
lastIndex: [Function: lastIndex] }
> opiterator.next()
{ opcode: '+',
chars: 9,
lines: 0,
attribs: '*0*1' }
> opiterator.next()
{ opcode: '+',
chars: 1,
lines: 1,
attribs: '*0' }
> opiterator.next()
{ opcode: '+',
chars: 11,
lines: 0,
attribs: '*0*1*2' }
> opiterator.next()
{ opcode: '+',
chars: 1,
lines: 1,
attribs: '' }
> opiterator.next()
{ opcode: '+',
chars: 11,
lines: 0,
attribs: '*0' }
> opiterator.next()
{ opcode: '+',
chars: 2,
lines: 2,
attribs: '' }
The attribs are again a bunch of operators like .ops in the changeset was. But these operators are only + operators. They describe which part of the text has which attributes
Detailed information about the changesets & Easysync protocol:
require("ep_etherpad-lite/static/js/plugingfw/plugins")
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)
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}
.
?
src/node/utils/toolbar.js
opts
command
- this command fill be fired on the editbar on clicklocalizationId
- will be set as data-l10-id
class
- here you can add additional classes to the buttonReturns: {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"
})
opts
id
- id of the menu itemselectId
- id of the select elementcommand
- this command fill be fired on the editbar on changeReturns: {SelectButton}
data-l10n-id
)Shows the dropdown div.popup
whose id
equals dropdown
.
Register a handler for a specific command. Commands are fired if the corresponding button is clicked or the corresponding select is changed.
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();
});
Ties a div.popup
where id
equals dropdown
to a command
fired by clicking a button.
Triggers a command (optionally with some internal representation of the toolbar item that triggered it).
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.
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.)
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
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": ""
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...
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.
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.
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.
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.13.0"}
}
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.
Etherpad allows you to easily create front-end tests for plugins.
%your_plugin%/static/tests/frontend/specs
%etherpad_root_folder%/frontend/tests/specs
.)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 | example.org | 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. More info - https://github.com/ether/etherpad-lite/blob/develop/doc/api/http_api.md#session |
A list of all existing groups (a JSON object with groupIDs as keys and 1
as values).
Contains all information about pads
Saves a revision $REVNUM of pad $PADID
Saves a chat entry with num $CHATNUM of pad $PADID
Translates a padID to a readonlyID
Translates a readonlyID to a padID
Translates a token to an authorID
Information about an author
Maps an external application identifier to an internal group
Maps an external application identifier to an internal author
a group of pads
pads - object with pad names in it, values are 1
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
saves the sessions of an author