Hooks

Hooks

A simple event framework used throughout Foundry Virtual Tabletop. When key actions or events occur, a "hook" is defined where user-defined callback functions can execute. This class manages the registration and execution of hooked callback functions.

Constructor

new Hooks()

Methods

(static) call(hook, …args) → {boolean}

Call hook listeners in the order in which they were registered. Continue calling hooks until either all have been called or one returns false.

Hook listeners which return false denote that the original event has been adequately handled and no further hooks should be called.

Parameters:
Name Type Attributes Description
hook string

The hook being triggered

args * <repeatable>

Arguments passed to the hook callback functions

Returns:

Were all hooks called without execution being prevented?

Type
boolean

(static) callAll(hook, …args) → {boolean}

Call all hook listeners in the order in which they were registered Hooks called this way can not be handled by returning false and will always trigger every hook callback.

Parameters:
Name Type Attributes Description
hook string

The hook being triggered

args * <repeatable>

Arguments passed to the hook callback functions

Returns:

Were all hooks called without execution being prevented?

Type
boolean

(static) off(hook, fn)

Unregister a callback handler for a particular hook event

Parameters:
Name Type Description
hook string

The unique name of the hooked event

fn function | number

The function, or ID number for the function, that should be turned off

(static) on(hook, fn) → {number}

Register a callback handler which should be triggered when a hook is triggered.

Parameters:
Name Type Description
hook string

The unique name of the hooked event

fn function

The callback function which should be triggered when the hook event occurs

Returns:

An ID number of the hooked function which can be used to turn off the hook later

Type
number

(static) once(hook, fn) → {number}

Register a callback handler for an event which is only triggered once the first time the event occurs. After a "once" hook is triggered the hook is automatically removed.

Parameters:
Name Type Description
hook string

The unique name of the hooked event

fn function

The callback function which should be triggered when the hook event occurs

Returns:

An ID number of the hooked function which can be used to turn off the hook later

Type
number

(static) onError(location, err, optionsopt)

Notify subscribers that an error has occurred within foundry.

Parameters:
Name Type Attributes Default Description
location string

The method where the error was caught.

err Error

The error.

options object <optional>
{}

Additional options to configure behaviour.

Properties
Name Type Attributes Default Description
msg string <optional>
""

A message to prefix the caught error with and/or to use in the notification.

log string <optional>
<nullable>
null

The level at which to log the error to console (if at all).

notify string <optional>
<nullable>
null

The level at which to spawn a notification in the UI (if at all).

data object <optional>
{}

Additional data to pass to the hook subscribers.