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 lite. Means: Your web application still has to do authentication, but you can tell etherpad lite via the api, which visitors should get which permissions. This allows etherpad lite to fit into any web application and extend it with real-time functionality. You can embed the pads via an iframe into your website.
-
-
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:
-
-
The API is accessible via HTTP. HTTP Requests are in the format /api/$APIVERSION/$FUNCTIONNAME. Parameters are transmitted via HTTP GET. $APIVERSION depends on the endpoints you want to use.
-
-
Authentication works via a token that is sent with each request as a post parameter. There is a single token per Etherpad-Lite deployment. This token will be random string, generated by Etherpad-Lite at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad Lite. Only Etherpad Lite and the requesting application knows this key. Token management will not be exposed through this API.
-
-
Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-seperated sessionIDs, allowing a user to edit pads in different groups at the same time. Only users with a valid session for this group, can access group pads. You can create a session after you authenticated the user at your web application, to give them access to the pads. You should save the sessionID of this session and delete it after the user logged out.
-
-
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}
-
-
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}
-
-
Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security manager controls access of them and its forbidden for normal pads to include a $ in the name.
-
-
A hook should always return a list or undefined. Returning undefined is equivalent to returning an empty list.
-All the returned lists are appended to each other, so if the return values where [1, 2], undefined, [3, 4,], undefined and [5], the value returned by callHook would be [1, 2, 3, 4, 5].
-
-
-
This is, because it should never matter if you have one plugin or several plugins doing some work - a single plugin should be able to make callHook return the same value a set of plugins are able to return collectively. So, any plugin can return a list of values, of any length, not just one value.
-
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.
-
-
-
The return value of this hook should have the following structure:
-
-
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.
-
-
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 and extraCloseTags will be added before and after the element in question, and cls will be the new class of the element going forward.
-
-
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.
-
-
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).
-
-
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.
-
-
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.
-
-
The return value of this hook will add elements into the "lineMarkerAttribute" category, making the aceDomLineProcessLineAttributes hook (documented below) call for those elements.
-
-
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.
-
-
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 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.
-
-
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.
-
-
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.
-
-
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.
-The return value should be the validated/manipulated text.
-
-
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.
-
-
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.
-
-
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!
-
-
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.
-
-
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.
-
-
app - the main express application object (helpful for adding new paths and such)
-
server - the http server object
-
-
This hook gets called after the application object has been created, but before it starts listening. This is similar to the expressConfigure hook, but it's not guaranteed that the application object will have all relevant configuration variables.
-
-
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.
-
-
-
Have a look at src/templates/pad.html and src/templates/timeslider.html to see which blocks are available.
-
-
Called from: src/node/handler/PadMessageHandler.js
-
-
-
Things in context:
-
-
-
-
message - the message being handled
-
client - the client object from socket.io
-
-
This hook will be called once a message arrive. If a plugin calls callback(null) the message will be dropped. However it is not possible to modify the message.
-
-
-
Plugins may also decide to implement custom behavior once a message arrives.
-
-
-
WARNING: handleMessage will be called, even if the client is not authorized to send this message. It's up to the plugin to check permissions.
-
-
-
Example:
-
-
-
function handleMessage ( hook, context, callback ) {
- if ( context.message.type == 'USERINFO_UPDATE' ) {
- // If the message type is USERINFO_UPDATE, drop the message
- callback(null);
- }else{
- callback();
- }
-};
Called from: src/node/handler/PadMessageHandler.js
-
-
-
Things in context:
-
-
-
-
clientVars - the basic clientVars built by the core
-
pad - the pad this session is about
-
-
This hook will be called once a client connects and the clientVars are being sent. Plugins can use this hook to give the client a initial configuriation, like the tracking-id of an external analytics-tool that is used on the client-side. You can also overwrite values from the original clientVars.
-
-
-
Example:
-
-
-
exports.clientVars = function(hook, context, callback)
-{
- // tell the client which year we are in
- return callback({ "currentYear": new Date().getFullYear() });
-};
-
This can be accessed on the client-side using clientVars.currentYear.
-
-
This is a Changeset. Its just a string and its 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. This Changesets gets also saved into the history of a pad. Which allows us to go back to every revision from the past.
-
-
opsString 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 type
-
chars {Number} the length of the text changed by this operator.
-
lines {Number} the number of lines changed by this operator.
This creates an empty apool. A 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. Lets fill this apool with some values
-
-
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. A attribute is always a key value pair. For stuff like bold and italic its just 'italic':'true'. For authors its 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
-
-
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
-
-
The attribs are again a bunch of operators like .ops in the changeset was. But these operators are only + operators. They describe which part of the text has which attributes
-
-
-
For more information see /doc/easysync/easysync-notes.txt in the source.
-
-
require("ep_etherpad-lite/static/js/plugingfw/plugins").update() will use npm to list all installed modules and read their ep.json files, registering the contained hooks.
-A hook registration is a pairs of a hook name and a function reference (filename for require() plus function name)
-
-
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}.
-
-
This is a Changeset. Its just a string and its 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. This Changesets gets also saved into the history of a pad. Which allows us to go back to every revision from the past.
-
-
opsString 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 type
-
chars {Number} the length of the text changed by this operator.
-
lines {Number} the number of lines changed by this operator.
This creates an empty apool. A 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. Lets fill this apool with some values
-
-
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. A attribute is always a key value pair. For stuff like bold and italic its just 'italic':'true'. For authors its 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
-
-
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
-
-
The attribs are again a bunch of operators like .ops in the changeset was. But these operators are only + operators. They describe which part of the text has which attributes
-
-
-
For more information see /doc/easysync/easysync-notes.txt in the source.
-
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.
-
-
-
The return value of this hook should have the following structure:
-
-
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.
-
-
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 and extraCloseTags will be added before and after the element in question, and cls will be the new class of the element going forward.
-
-
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.
-
-
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).
-
-
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.
-
-
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.
-
-
The return value of this hook will add elements into the "lineMarkerAttribute" category, making the aceDomLineProcessLineAttributes hook (documented below) call for those elements.
-
-
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.
-
-
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 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.
-
-
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.
-
-
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.
-
-
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.
-The return value should be the validated/manipulated text.
-
-
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.
-
-
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.
-
A hook should always return a list or undefined. Returning undefined is equivalent to returning an empty list.
-All the returned lists are appended to each other, so if the return values where [1, 2], undefined, [3, 4,], undefined and [5], the value returned by callHook would be [1, 2, 3, 4, 5].
-
-
-
This is, because it should never matter if you have one plugin or several plugins doing some work - a single plugin should be able to make callHook return the same value a set of plugins are able to return collectively. So, any plugin can return a list of values, of any length, not just one value.
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!
-
-
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.
-
-
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.
-
-
app - the main express application object (helpful for adding new paths and such)
-
server - the http server object
-
-
This hook gets called after the application object has been created, but before it starts listening. This is similar to the expressConfigure hook, but it's not guaranteed that the application object will have all relevant configuration variables.
-
-
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.
-
-
-
Have a look at src/templates/pad.html and src/templates/timeslider.html to see which blocks are available.
-
-
Called from: src/node/handler/PadMessageHandler.js
-
-
-
Things in context:
-
-
-
-
message - the message being handled
-
client - the client object from socket.io
-
-
This hook will be called once a message arrive. If a plugin calls callback(null) the message will be dropped. However it is not possible to modify the message.
-
-
-
Plugins may also decide to implement custom behavior once a message arrives.
-
-
-
WARNING: handleMessage will be called, even if the client is not authorized to send this message. It's up to the plugin to check permissions.
-
-
-
Example:
-
-
-
function handleMessage ( hook, context, callback ) {
- if ( context.message.type == 'USERINFO_UPDATE' ) {
- // If the message type is USERINFO_UPDATE, drop the message
- callback(null);
- }else{
- callback();
- }
-};
Called from: src/node/handler/PadMessageHandler.js
-
-
-
Things in context:
-
-
-
-
clientVars - the basic clientVars built by the core
-
pad - the pad this session is about
-
-
This hook will be called once a client connects and the clientVars are being sent. Plugins can use this hook to give the client a initial configuriation, like the tracking-id of an external analytics-tool that is used on the client-side. You can also overwrite values from the original clientVars.
-
-
-
Example:
-
-
-
exports.clientVars = function(hook, context, callback)
-{
- // tell the client which year we are in
- return callback({ "currentYear": new Date().getFullYear() });
-};
-
This can be accessed on the client-side using clientVars.currentYear.
-
-
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 lite. Means: Your web application still has to do authentication, but you can tell etherpad lite via the api, which visitors should get which permissions. This allows etherpad lite to fit into any web application and extend it with real-time functionality. You can embed the pads via an iframe into your website.
-
-
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:
-
-
The API is accessible via HTTP. HTTP Requests are in the format /api/$APIVERSION/$FUNCTIONNAME. Parameters are transmitted via HTTP GET. $APIVERSION depends on the endpoints you want to use.
-
-
Authentication works via a token that is sent with each request as a post parameter. There is a single token per Etherpad-Lite deployment. This token will be random string, generated by Etherpad-Lite at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad Lite. Only Etherpad Lite and the requesting application knows this key. Token management will not be exposed through this API.
-
-
Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-seperated sessionIDs, allowing a user to edit pads in different groups at the same time. Only users with a valid session for this group, can access group pads. You can create a session after you authenticated the user at your web application, to give them access to the pads. You should save the sessionID of this session and delete it after the user logged out.
-
-
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}
-
-
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}
-
-
Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security manager controls access of them and its forbidden for normal pads to include a $ in the name.
-
-
require("ep_etherpad-lite/static/js/plugingfw/plugins").update() will use npm to list all installed modules and read their ep.json files, registering the contained hooks.
-A hook registration is a pairs of a hook name and a function reference (filename for require() plus function name)
-
-
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}.
-
-
The goal of this documentation is to comprehensively explain Etherpad-Lite,
-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
-.markdown file in the doc/api/ folder in the source tree. The
-documentation is generated using the tools/doc/generate.js program.
-The HTML template is located at doc/template.html.
The goal of this documentation is to comprehensively explain Etherpad-Lite,
-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
-.markdown file in the doc/api/ folder in the source tree. The
-documentation is generated using the tools/doc/generate.js program.
-The HTML template is located at doc/template.html.
-
Etherpad lite 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.
-
-
-
/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. Now, that we know your preferred language this information is feeded into a very nice library called html10n.js, which loads the appropriate translations and applies them to our templates, providing translation params, pluralization, include rules and even a nice javascript API along the way.
-
-
-
-
In the javascript files of your plugin, chaneg all hardcoded messages/strings...
-
-
-
from:
-
-
alert ('Chat');
-
to:
-
-
alert(window._('pad.chat'));
-
2. Create translate files in the locales directory of your plugin#
-
-
The name of the file must be the language code of the language it contains translations for (see supported lang codes; e.g. en ? English, es ? Spanish...)
-
The extension of the file must be .json
-
The default language is English, so your plugin should always provide en.json
-
In order to avoid naming conflicts, your message keys should start with the name of your plugin followed by a dot (see below)
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 lite. Means: Your web application still has to do authentication, but you can tell etherpad lite via the api, which visitors should get which permissions. This allows etherpad lite to fit into any web application and extend it with real-time functionality. You can embed the pads via an iframe into your website.
-
-
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:
-
-
The API is accessible via HTTP. HTTP Requests are in the format /api/$APIVERSION/$FUNCTIONNAME. Parameters are transmitted via HTTP GET. $APIVERSION depends on the endpoints you want to use.
-
-
Authentication works via a token that is sent with each request as a post parameter. There is a single token per Etherpad-Lite deployment. This token will be random string, generated by Etherpad-Lite at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad Lite. Only Etherpad Lite and the requesting application knows this key. Token management will not be exposed through this API.
-
-
Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-seperated sessionIDs, allowing a user to edit pads in different groups at the same time. Only users with a valid session for this group, can access group pads. You can create a session after you authenticated the user at your web application, to give them access to the pads. You should save the sessionID of this session and delete it after the user logged out.
-
-
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}
-
-
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}
-
-
Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security manager controls access of them and its forbidden for normal pads to include a $ in the name.
-
-
A hook should always return a list or undefined. Returning undefined is equivalent to returning an empty list.
-All the returned lists are appended to each other, so if the return values where [1, 2], undefined, [3, 4,], undefined and [5], the value returned by callHook would be [1, 2, 3, 4, 5].
-
-
-
This is, because it should never matter if you have one plugin or several plugins doing some work - a single plugin should be able to make callHook return the same value a set of plugins are able to return collectively. So, any plugin can return a list of values, of any length, not just one value.
-
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.
-
-
-
The return value of this hook should have the following structure:
-
-
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.
-
-
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 and extraCloseTags will be added before and after the element in question, and cls will be the new class of the element going forward.
-
-
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.
-
-
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).
-
-
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.
-
-
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.
-
-
The return value of this hook will add elements into the "lineMarkerAttribute" category, making the aceDomLineProcessLineAttributes hook (documented below) call for those elements.
-
-
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.
-
-
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 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.
-
-
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.
-
-
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.
-
-
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.
-The return value should be the validated/manipulated text.
-
-
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.
-
-
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.
-
-
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!
-
-
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.
-
-
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.
-
-
app - the main express application object (helpful for adding new paths and such)
-
server - the http server object
-
-
This hook gets called after the application object has been created, but before it starts listening. This is similar to the expressConfigure hook, but it's not guaranteed that the application object will have all relevant configuration variables.
-
-
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.
-
-
-
Have a look at src/templates/pad.html and src/templates/timeslider.html to see which blocks are available.
-
-
Called from: src/node/handler/PadMessageHandler.js
-
-
-
Things in context:
-
-
-
-
message - the message being handled
-
client - the client object from socket.io
-
-
This hook will be called once a message arrive. If a plugin calls callback(null) the message will be dropped. However it is not possible to modify the message.
-
-
-
Plugins may also decide to implement custom behavior once a message arrives.
-
-
-
WARNING: handleMessage will be called, even if the client is not authorized to send this message. It's up to the plugin to check permissions.
-
-
-
Example:
-
-
-
function handleMessage ( hook, context, callback ) {
- if ( context.message.type == 'USERINFO_UPDATE' ) {
- // If the message type is USERINFO_UPDATE, drop the message
- callback(null);
- }else{
- callback();
- }
-};
Called from: src/node/handler/PadMessageHandler.js
-
-
-
Things in context:
-
-
-
-
clientVars - the basic clientVars built by the core
-
pad - the pad this session is about
-
-
This hook will be called once a client connects and the clientVars are being sent. Plugins can use this hook to give the client a initial configuriation, like the tracking-id of an external analytics-tool that is used on the client-side. You can also overwrite values from the original clientVars.
-
-
-
Example:
-
-
-
exports.clientVars = function(hook, context, callback)
-{
- // tell the client which year we are in
- return callback({ "currentYear": new Date().getFullYear() });
-};
-
This can be accessed on the client-side using clientVars.currentYear.
-
-
This is a Changeset. Its just a string and its 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. This Changesets gets also saved into the history of a pad. Which allows us to go back to every revision from the past.
-
-
opsString 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 type
-
chars {Number} the length of the text changed by this operator.
-
lines {Number} the number of lines changed by this operator.
This creates an empty apool. A 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. Lets fill this apool with some values
-
-
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. A attribute is always a key value pair. For stuff like bold and italic its just 'italic':'true'. For authors its 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
-
-
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
-
-
The attribs are again a bunch of operators like .ops in the changeset was. But these operators are only + operators. They describe which part of the text has which attributes
-
-
-
For more information see /doc/easysync/easysync-notes.txt in the source.
-
-
require("ep_etherpad-lite/static/js/plugingfw/plugins").update() will use npm to list all installed modules and read their ep.json files, registering the contained hooks.
-A hook registration is a pairs of a hook name and a function reference (filename for require() plus function name)
-
-
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}.
-
-
Etherpad-Lite allows you to extend its functionality with plugins. A plugin registers hooks (functions) for certain events (thus certain features) in Etherpad-lite to execute its own functionality based on these events.
-
-
-
Publicly available plugins can be found in the npm registry (see http://npmjs.org). Etherpad-lite's naming convention for plugins is to prefix your plugins with ep_. So, e.g. it's ep_flubberworms. Thus you can install plugins from npm, using npm install ep_flubberworm in etherpad-lite's root directory.
-
-
-
You can also browse to http://yourEtherpadInstan.ce/admin/plugins, which will list all installed plugins and those available on npm. It even provides functionality to search through all available plugins.
-
-
If your plugin includes client-side hooks, put them in static/js/. If you're adding in CSS or image files, you should put those files in static/css/ and static/image/, respectively, and templates go into templates/. Translations go into locales/
-
-
-
A Standard directory structure like this makes it easier to navigate through your code. That said, do note, that this is not actually required to make your plugin run. If you want to make use of our i18n system, you need to put your translations into locales/, though, in order to have them intergated. (See "Localization" for more info on how to localize your plugin)
-
-
Your plugin definition goes into ep.json. In this file you register your hooks, indicate the parts of your plugin and the order of execution. (A documentation of all available events to hook into can be found in chapter hooks.)
-
-
-
A hook registration is a pairs of a hook name and a function reference (filename to require() + exported function name)
-
-
Etherpad-lite will expect the part of the hook definition before the colon to be a javascript file and will try to require it. The part after the colon is expected to be a valid function identifier of that module. So, you have to export your hooks, using module.exports and register it in ep.json as ep_<plugin>/path/to/<file>:FUNCTIONNAME.
-You can omit the FUNCTIONNAME part, if the exported function has got the same name as the hook. So "authorize" : "ep_flubberworm/foo" will call the function exports.authorize in ep_flubberworm/foo.js
-
-
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...
-
-
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:
-
-
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-lite plugins, even if you don't publish your plugin.
-
-
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-Lite uses EJS for HTML templating. See the following link for more information about EJS: https://github.com/visionmedia/ejs.
-
-
-
Writing and running front-end tests for your plugin#
-
Etherpad allows you to easily create front-end tests for plugins.
-
-
-
-
Create a new folder
%your_plugin%/static/tests/frontend/specs
-
-
Put your spec file in here (Example spec files are visible in %etherpad_root_folder%/frontend/tests/specs)
Etherpad lite 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.
-
-
-
/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. Now, that we know your preferred language this information is feeded into a very nice library called html10n.js, which loads the appropriate translations and applies them to our templates, providing translation params, pluralization, include rules and even a nice javascript API along the way.
-
-
-
-
In the javascript files of your plugin, chaneg all hardcoded messages/strings...
-
-
-
from:
-
-
alert ('Chat');
-
to:
-
-
alert(window._('pad.chat'));
-
2. Create translate files in the locales directory of your plugin#
-
-
The name of the file must be the language code of the language it contains translations for (see supported lang codes; e.g. en ? English, es ? Spanish...)
-
The extension of the file must be .json
-
The default language is English, so your plugin should always provide en.json
-
In order to avoid naming conflicts, your message keys should start with the name of your plugin followed by a dot (see below)
Etherpad-Lite allows you to extend its functionality with plugins. A plugin registers hooks (functions) for certain events (thus certain features) in Etherpad-lite to execute its own functionality based on these events.
-
-
-
Publicly available plugins can be found in the npm registry (see http://npmjs.org). Etherpad-lite's naming convention for plugins is to prefix your plugins with ep_. So, e.g. it's ep_flubberworms. Thus you can install plugins from npm, using npm install ep_flubberworm in etherpad-lite's root directory.
-
-
-
You can also browse to http://yourEtherpadInstan.ce/admin/plugins, which will list all installed plugins and those available on npm. It even provides functionality to search through all available plugins.
-
-
If your plugin includes client-side hooks, put them in static/js/. If you're adding in CSS or image files, you should put those files in static/css/ and static/image/, respectively, and templates go into templates/. Translations go into locales/
-
-
-
A Standard directory structure like this makes it easier to navigate through your code. That said, do note, that this is not actually required to make your plugin run. If you want to make use of our i18n system, you need to put your translations into locales/, though, in order to have them intergated. (See "Localization" for more info on how to localize your plugin)
-
-
Your plugin definition goes into ep.json. In this file you register your hooks, indicate the parts of your plugin and the order of execution. (A documentation of all available events to hook into can be found in chapter hooks.)
-
-
-
A hook registration is a pairs of a hook name and a function reference (filename to require() + exported function name)
-
-
Etherpad-lite will expect the part of the hook definition before the colon to be a javascript file and will try to require it. The part after the colon is expected to be a valid function identifier of that module. So, you have to export your hooks, using module.exports and register it in ep.json as ep_<plugin>/path/to/<file>:FUNCTIONNAME.
-You can omit the FUNCTIONNAME part, if the exported function has got the same name as the hook. So "authorize" : "ep_flubberworm/foo" will call the function exports.authorize in ep_flubberworm/foo.js
-
-
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...
-
-
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:
-
-
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-lite plugins, even if you don't publish your plugin.
-
-
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-Lite uses EJS for HTML templating. See the following link for more information about EJS: https://github.com/visionmedia/ejs.
-
-
-
Writing and running front-end tests for your plugin#
-
Etherpad allows you to easily create front-end tests for plugins.
-
-
-
-
Create a new folder
%your_plugin%/static/tests/frontend/specs
-
-
Put your spec file in here (Example spec files are visible in %etherpad_root_folder%/frontend/tests/specs)