DiviArea.addFilter()

DiviArea.addFilter(hook, callback, priority, context)

// Alias:
DiviArea.Hooks.addFilter(hook, callback, priority, context)

The JS API uses an action/filter system that is very similar to the WordPress actions/filters. The API applies filters at certain points, which you can tap into to customize the default behavior.

The addFilter() function registers a callback function that is executed when the specified filter is applied.

Your callback must return either the default value (provided in the first parameter) or a new value that replaces the default value.

When more than one callback is registered for the same filter, the second callback receives the return value of the first callback function, and so on.

Params

hook – string, required

Name of the filter to observe.

callback – function, required

The callback function to execute when the filter is applied. The return value of the callback function defines the new (aka “filtered”) value.

priority – int, optional

Used to specify the order, in which callbacks are executed. Callbacks with a lower priority are called first.
Default: 10

context – object, optional

Used to define a custom value for the scope-variable this in the callback function.
Default: <code>window</code>

Returns

The function does not return anything.

Examples

DiviArea.addFilter('hide_ids_before_show', function(ids) {
  console.log('Hide those areas:', ids);
  return ids;
});

// How the response value is changed in multiple callbacks:

DiviArea.addFilter('esc_key_pressed', function(ignore) {
  console.log('Ignore ESC key?', ignore); // ignore is FALSE.

  // Change the value of ignore:
  return !ignore;
}, 10);

DiviArea.addFilter('esc_key_pressed', function(ignore) {
  console.log('Ignore ESC key?', ignore); // ignore is TRUE.
  return ignore;
}, 20);

Notes

To see the exact names and execution order of all the JS API actions and filters on your website, simply enable the Debugging Output, then open your browsers JS console and visit a page with an Area/Popup. Look for the “Apply Filters” and “Do Action” entries: