# Hooks
A lightweight & efficient EventManager for JavaScript.
## Installation
Install the module
```bash
npm install @wordpress/hooks --save
```
_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._
### Usage
In your JavaScript project, use hooks as follows:
```javascript
import { createHooks } from '@wordpress/hooks';
myObject.hooks = createHooks();
myObject.hooks.addAction(); //etc...
```
#### The global instance
In the above example, we are creating a custom instance of the `Hooks` object and registering hooks there. The package also creates a default global instance that's accessible through the `defaultHooks` named exports, and its methods are also separately exported one-by-one.
In the WordPress context, that enables API functions to be called via the global `wp.hooks` object, like `wp.hooks.addAction()`, etc.
One notable difference between the JS and PHP hooks API is that in the JS version, `addAction()` and `addFilter()` also need to include a namespace as the second argument. Namespace uniquely identifies a callback in the form `vendor/plugin/function`.
### API Usage
- `createHooks()`
- `addAction( 'hookName', 'namespace', callback, priority )`
- `addFilter( 'hookName', 'namespace', callback, priority )`
- `removeAction( 'hookName', 'namespace' )`
- `removeFilter( 'hookName', 'namespace' )`
- `removeAllActions( 'hookName' )`
- `removeAllFilters( 'hookName' )`
- `doAction( 'hookName', arg1, arg2, moreArgs, finalArg )`
- `doActionAsync( 'hookName', arg1, arg2, moreArgs, finalArg )`
- `applyFilters( 'hookName', content, arg1, arg2, moreArgs, finalArg )`
- `applyFiltersAsync( 'hookName', content, arg1, arg2, moreArgs, finalArg )`
- `doingAction( 'hookName' )`
- `doingFilter( 'hookName' )`
- `didAction( 'hookName' )`
- `didFilter( 'hookName' )`
- `hasAction( 'hookName', 'namespace' )`
- `hasFilter( 'hookName', 'namespace' )`
- `actions`
- `filters`
- `defaultHooks`
## Parameters
### hookName
Should be a non empty string containing only numbers, letters, dashes, periods and underscores. Also, the hook name cannot begin with `__`.
- Type: `String`
- Required: Yes
### namespace
Should be a non empty string containing only numbers, letters, dashes, periods, underscores and slashes. It should take the form `vendor/plugin/function`.
- Type: `String`
- Required: Yes
### Events on action/filter add or remove
Whenever an action or filter is added or removed, a matching `hookAdded` or `hookRemoved` action is triggered.
- `hookAdded` action is triggered when `addFilter()` or `addAction()` method is called, passing values for `hookName`, `functionName`, `callback` and `priority`.
- `hookRemoved` action is triggered when `removeFilter()` or `removeAction()` method is called, passing values for `hookName` and `functionName`.
### The `all` hook
In non-minified builds developers can register a filter or action that will be called on _all_ hooks, for example: `addAction( 'all', 'namespace', callbackFunction );`. Useful for debugging, the code supporting the `all` hook is stripped from the production code for performance reasons.
## Contributing to this package
This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.
To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).
