doc/api/hooks_client-side.md
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.ts
Things in context: None
Tells Etherpad which line attributes should be preserved when a user presses Enter to split a line. Without this hook, custom line attributes (such as headings or alignment) are lost when a line is split.
The return value should be an array of attribute names:
exports.aceRegisterLineAttributes = function(){
return [ 'heading' ];
}
When Enter is pressed on a line that has a registered attribute:
This is backwards compatible — on Etherpad versions that do not have this hook, the registration is silently ignored.
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:
clientVars server-side hook.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.
chatNewMessageCalled from: src/static/js/chat.js
This hook runs on the client side whenever a chat message is received from the
server. It can be used to create different notifications for chat messages. Hook
functions can modify the author, authorName, duration, rendered,
sticky, text, and timeStr context properties to change how the message is
processed. The text and timeStr properties may contain HTML and come
pre-sanitized; plugins should be careful to sanitize any added user input to
avoid introducing an XSS vulnerability.
Context properties:
authorName: The display name of the user that wrote the message.author: The author ID of the user that wrote the message.text: Sanitized message HTML, with URLs wrapped like <a href="url">url</a>. (Note that message.text is not sanitized or processed
in any way.)message: The raw message object as received from the server, except with
time correction and a default authorId property if missing. Plugins must not
modify this object. Warning: Unlike text, message.text is not
pre-sanitized or processed in any way.rendered - Used to override the default message rendering. Initially set to
null. If the hook function sets this to a DOM element object or a jQuery
object, then that object will be used as the rendered message UI. Otherwise,
if this is set to null, then Etherpad will render a default UI for the
message using the other context properties.sticky (boolean): Whether the gritter notification should fade out on its
own or just sit there until manually closed.timestamp: When the chat message was sent (milliseconds since epoch),
corrected using the difference between the local clock and the server's clock.timeStr: The message timestamp as a formatted string.duration: How long (in milliseconds) to display the gritter notification (0
to disable).chatSendMessageCalled from: src/static/js/chat.js
This hook runs on the client side whenever the user sends a new chat message.
Plugins can mutate the message object to change the message text or add metadata
to control how the message will be rendered by the chatNewMessage hook.
Context properties:
message: The message object that will be sent to the Etherpad server.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.
nameCalled 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.