@wordpress/hooks

What is @wordpress/hooks?

@wordpress/hooks is a library that provides a way to manage and trigger custom actions and filters in JavaScript. It is inspired by the WordPress PHP hooks system and allows developers to add, remove, and execute custom hooks in their JavaScript applications.

What are @wordpress/hooks's main functionalities?

Adding Actions

This feature allows you to add custom actions that can be triggered at specific points in your application. The code sample demonstrates how to add an action named 'myCustomAction' in the 'myNamespace' namespace.

const { addAction } = require('@wordpress/hooks');

addAction('myCustomAction', 'myNamespace', () => {
  console.log('Action triggered!');
});

Doing Actions

This feature allows you to trigger actions that have been added. The code sample demonstrates how to trigger the 'myCustomAction' action, which will execute any functions hooked to it.

const { doAction } = require('@wordpress/hooks');

doAction('myCustomAction');

Adding Filters

This feature allows you to add custom filters that can modify data at specific points in your application. The code sample demonstrates how to add a filter named 'myCustomFilter' in the 'myNamespace' namespace, which appends ' filtered' to the input value.

const { addFilter } = require('@wordpress/hooks');

addFilter('myCustomFilter', 'myNamespace', (value) => {
  return value + ' filtered';
});

Applying Filters

This feature allows you to apply filters to data, modifying it according to the functions hooked to the filter. The code sample demonstrates how to apply the 'myCustomFilter' filter to the string 'original value', resulting in 'original value filtered'.

const { applyFilters } = require('@wordpress/hooks');

const result = applyFilters('myCustomFilter', 'original value');
console.log(result); // Outputs: 'original value filtered'

Other packages similar to @wordpress/hooks

eventemitter3

EventEmitter3 is a high-performance event emitter for Node.js and the browser. It provides a similar mechanism for managing events but does not include the concept of filters. It is more focused on emitting and listening to events.

mitt

Mitt is a tiny functional event emitter. It provides a simple API for emitting and listening to events, similar to the action functionality in @wordpress/hooks, but does not include filtering capabilities.

hookable

Hookable is a lightweight library for creating hooks in JavaScript. It provides a similar API for adding and triggering hooks, including both actions and filters, making it a closer alternative to @wordpress/hooks.

README

Hooks

A lightweight & efficient EventManager for JavaScript.

Installation

Install the module

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 ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

Usage

In your JavaScript project, use hooks as follows:

import { createHooks } from '@wordpress/hooks';

myObject.hooks = createHooks();
myObject.hooks.addAction(); //etc...

In the WordPress context, API functions can be called via the global wp.hooks like this wp.hooks.addAction(), etc. One notable difference from the PHP API is that addAction() and addFilter() also need to include a namespace as the second argument.

API Usage

• createHooks()
• addAction( 'hookName', 'namespace', 'functionName', callback, priority )
• addFilter( 'hookName', 'namespace', 'functionName', callback, priority )
• removeAction( 'hookName', 'namespace', 'functionName' )
• removeFilter( 'hookName', 'namespace', 'functionName' )
• removeAllActions( 'hookName' )
• removeAllFilters( 'hookName' )
• doAction( 'hookName', arg1, arg2, moreArgs, finalArg )
• applyFilters( 'hookName', content, arg1, arg2, moreArgs, finalArg )
• doingAction( 'hookName' )
• doingFilter( 'hookName' )
• didAction( 'hookName' )
• didFilter( 'hookName' )
• hasAction( 'hookName' )
• hasFilter( 'hookName' )
• actions
• filters

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.