Skip to content

Plugin API Hooks

Jump to bottom Edit New page
Matic Potočnik edited this page Aug 20, 2017 · 26 revisions

All hooks registered to these events are called with two arguments:

  1. name - the name of the hook being called
  2. context - an object with some relevant information about the context of the call

Please note: The following information only applies to v1.1.1, for newer versions, check out the doc folder.

Ace hooks

These hooks are called during or in order to set up the formatting process.

aceDomLineProcessLineAttributes

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

Things in context:

  1. domline - The current DOM line being processed
  2. 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:

{ preHtml: String, postHtml: String, processedMarker: Boolean }

The preHtml and postHtml values will be added to the HTML display of the element, and if processedMarker is true, the engine won't try to process it any more.

aceCreateDomLine

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

Things in context:

  1. domline - the current DOM line being processed
  2. cls - The class of the current element (useful for styling)

This hook is called for any line being processed by the formatting engine, unless the aceDomLineProcessLineAttributes hook from above returned true, in which case this hook is skipped.

The return value of this hook should have the following structure:

{ extraOpenTags: String, extraCloseTags: String, cls: String }

extraOpenTags and extraCloseTags will be added before and after the element in question, and cls will be the new class of the element going forward.

acePostWriteDomLineHTML

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

Things in context:

  1. node - the DOM node that just got written to the page

This hook is for right after a node has been fully formatted and written to the page.

aceAttribsToClasses

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

Things in context:

  1. linestylefilter - the JavaScript object that's currently processing the ace attributes
  2. key - the current attribute being processed
  3. 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.

aceGetFilterStack

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

Things in context:

  1. linestylefilter - the JavaScript object that's currently processing the ace attributes
  2. browser - an object indicating which browser is accessing the page

This hook is called to apply custom regular expression filters to a set of styles. The one example available is the ep_linkify plugin, which adds internal links. They use it to find the telltale [[ ]] syntax that signifies internal links, and finding that syntax, they add in the internalHref attribute to be later used by the aceCreateDomLine hook (documented above).

aceEditorCSS

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

Things in context: None

This hook is provided to allow custom CSS files to be loaded. The return value should be an array of paths relative to the plugins directory.

aceInitInnerdocbodyHead

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

Things in context:

  1. iframeHTML - the HTML of the editor iframe up to this point, in array format

This hook is called during the creation of the editor HTML. The array should have lines of HTML added to it, giving the plugin author a chance to add in meta, script, link, and other tags that go into the <head> element of the editor HTML document.

aceEditEvent

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

Things in context:

  1. callstack - a bunch of information about the current action
  2. editorInfo - information about the user who is making the change
  3. rep - information about where the change is being made
  4. 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.

aceRegisterBlockElements

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

Things in context: None

The return value of this hook will add elements into the "lineMarkerAttribute" category, making the aceDomLineProcessLineAttributes hook (documented below) call for those elements.

aceInitialized

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

Things in context:

  1. editorInfo - information about the user who will be making changes through the interface, and a way to insert functions into the main ace object (see ep_headings)
  2. rep - information about where the user's cursor is
  3. documentAttributeManager - some kind of magic

This hook is for inserting further information into the ace engine, for later use in formatting hooks.

postAceInit

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

Things in context:

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

There doesn't appear to be any example available of this particular hook being used, but it gets fired after the editor is all set up.

Other client hooks

These hooks are for other parts of the software on the client side, that is, when the editor is being used.

userJoinOrUpdate

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

Things in context:

  1. info - the user information

This hook is called on the client side whenever a user joins or changes. This can be used to create notifications or an alternate user list.

collectContentPre

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

Things in context:

  1. cc - the contentcollector object
  2. state - the current state of the change being made
  3. tname - the tag name of this node currently being processed
  4. style - the style applied to the node (probably CSS)
  5. 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.

collectContentPost

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

Things in context:

  1. cc - the contentcollector object
  2. state - the current state of the change being made
  3. tname - the tag name of this node currently being processed
  4. style - the style applied to the node (probably CSS)
  5. 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.

pluginUninstall

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

Things in context:

  1. plugin_name - self-explanatory

If this hook returns an error, the callback to the uninstall function gets an error as well. This mostly seems useful for handling additional features added in based on the installation of other plugins, which is pretty cool!

pluginInstall

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

Things in context:

  1. plugin_name - self-explanatory

If this hook returns an error, the callback to the install function gets an error, too. This seems useful for adding in features when a particular plugin is installed.

init_<plugin name>

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

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.

Server Hooks

These hooks get called on the server-side, so they're probably not helpful for showing things to the user.

expressConfigure

Called from: src/node/server.js

Things in context:

  1. app - the main application object

This is a helpful hook for changing the behavior and configuration of the application. It's called right after the application gets configured.

expressCreateServer

Called from: src/node/server.js

Things in context:

  1. app - the main application object (helpful for adding new paths and such)

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.

eejsBlock_<name>

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

Things in context:

  1. content - the content of the block

This hook gets called (I think) 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.

socketio

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

Things in context:

  1. app - the application object
  2. io - the socketio object

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

authorize

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

Things in context:

  1. req - the request object
  2. res - the response object
  3. next - ?
  4. resource - the path being accessed

This is useful for modifying the way authentication is done, especially for specific paths.

authenticate

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

Things in context:

  1. req - the request object
  2. res - the response object
  3. next - ?
  4. username - the username used (optional)
  5. password - the password used (optional)

This is useful for modifying the way authentication is done.

authFailure

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

Things in context:

  1. req - the request object
  2. res - the response object
  3. next - ?

This is useful for modifying the way authentication is done.

handleMessage

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

Things in context:

  1. message - the message being handled
  2. 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();
  }
};

Common things in context

editorInfo

editorInfo.ace_replaceRange(start, end, text)

This function replaces a range (from start to end) with text.

editorInfo.ace_getRep()

Returns the rep object.

editorInfo.ace_getAuthor()

editorInfo.ace_inCallStack()

editorInfo.ace_inCallStackIfNecessary(?)

editorInfo.ace_focus(?)

editorInfo.ace_importText(?)

editorInfo.ace_importAText(?)

editorInfo.ace_exportText(?)

editorInfo.ace_editorChangedSize(?)

editorInfo.ace_setOnKeyPress(?)

editorInfo.ace_setOnKeyDown(?)

editorInfo.ace_setNotifyDirty(?)

editorInfo.ace_dispose(?)

editorInfo.ace_getFormattedCode(?)

editorInfo.ace_setEditable(bool)

editorInfo.ace_execCommand(?)

editorInfo.ace_replaceRange(?)

editorInfo.ace_callWithAce(fn, callStack, normalize)

editorInfo.ace_setProperty(key, value)

editorInfo.ace_setBaseText(txt)

editorInfo.ace_setBaseAttributedText(atxt, apoolJsonObj)

editorInfo.ace_applyChangesToBase(c, optAuthor, apoolJsonObj)

editorInfo.ace_prepareUserChangeset()

editorInfo.ace_applyPreparedChangesetToBase()

editorInfo.ace_setUserChangeNotificationCallback(f)

editorInfo.ace_setAuthorInfo(author, info)

editorInfo.ace_setAuthorSelectionRange(author, start, end)

editorInfo.ace_getUnhandledErrors()

editorInfo.ace_getDebugProperty(prop)

editorInfo.ace_fastIncorp(?)

editorInfo.ace_isCaret(?)

editorInfo.ace_getLineAndCharForPoint(?)

editorInfo.ace_performDocumentApplyAttributesToCharRange(?)

editorInfo.ace_setAttributeOnSelection(?)

editorInfo.ace_toggleAttributeOnSelection(?)

editorInfo.ace_performSelectionChange(?)

editorInfo.ace_doIndentOutdent(?)

editorInfo.ace_doUndoRedo(?)

editorInfo.ace_doInsertUnorderedList(?)

editorInfo.ace_doInsertOrderedList(?)

editorInfo.ace_performDocumentApplyAttributesToRange()

Add a custom footer

General

Resources

For Developers

How to's

Set up

Advanced steps

Integrating Etherpad in your web app

for Developers

Clone this wiki locally