pad.pub0.org/doc/api/hooks_overview.md

# Hooks

A hook function is registered with a hook via the plugin's `ep.json` file. See
the Plugins section for details. A hook may have many registered functions from
different plugins.

When a hook is invoked, its registered functions are called with three
arguments:

1. hookName - The name of the hook being invoked.
2. context - An object with some relevant information about the context of the
   call. See the hook-specific documentation for details.
3. callback - Function to call when done. This 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. The value returned by this
   callback must be returned by the hook function unless otherwise specified.

## Return values

Note: This section applies to every hook unless the hook-specific documentation
says otherwise.

Hook functions return zero or more values to Etherpad by passing an array to the
provided callback. Hook functions typically provide a single value (array of
length one). If the function does not want to or need to provide a value, it may
pass an empty array or `undefined` (which is treated the same as an empty
array). Hook functions may also provide more than one value (array of length two
or more).

Some hooks concatenate the arrays provided by its registered functions. For
example, if a hook's registered functions pass `[1, 2]`, `undefined`, `[3, 4]`,
`[]`, and `[5]` to the provided callback, then the hook's return value is `[1,
2, 3, 4, 5]`.

Other hooks only use the first non-empty array provided by a registered
function. In this case, each of the hook's registered functions is called one at
a time until one provides a non-empty array. The remaining functions are
skipped. If none of the functions provide a non-empty array, or there are no
registered functions, the hook's return value is `[]`.

Example:

```
exports.abstractHook = (hookName, context, callback) => {
  if (notApplicableToThisPlugin(context)) {
    return callback();
  }
  const value = doSomeProcessing(context);
  return callback([value]);
};
```