🚇Filters

Filters are functions that BlueBase passes data through, at certain points in execution, just before taking some action with the data (such as adding it to the database or rendering some views). Most input and output in BlueBase pass through at least one filter. BlueBase does some filtering by default, and your plugin can add its own filtering.

The basic steps to add your own filters to BlueBase (described in more detail below) are:

1. Create the JavaScript function that filters the data.

2. Hook to the filter in BlueBase, by any of the following methods:

   1. Put your JavaScript function in the filters object of your plugin.

   2. Call BB.Filters.register() function.

The BlueBase Filters feature is heavily inspired by WordPress Filters.

Create a Filter Function

A filter function takes as input the unmodified data and returns modified data (or in some cases, a null value to indicate the data should be deleted or disregarded). If the data is not modified by your filter, then the original data must be returned so that subsequent plugins can continue to modify the value if necessary.

So, the first step in creating a filter in your plugin is to create a JavaScript function to do the filtering, and put it in your plugin file. For example, if you want to make sure that your posts and comments contain no profanity, you might define a variable with a list of forbidden words, and then create the following function:

function filter_profanity(content: string) {
	const profanities = array('badword','alsobad','...');
	return content.replace(profanities, '{censored}');
}

Register your Filter

After your function is defined, the next step is to register it with BlueBase. There are two ways to do this:

1. Put the function in the filters property of the plugin

createPlugin({
	// ... Other properties

	filters: {
		'post.comment': [{
			key: 'post-comment-profanity-remover',
			value: filter_profanity,
			priority: 2,
		}]
	},
});

2 Call BB.Filters.register() function

await BB.Filters.register({
	event: 'post.comment',
	key: 'post-comment-profanity-remover',
	value: filter_profanity,
	priority: 2,
});

where:

• event The name of a filter event that is provided by the developer. Defines when your filter should be applied.

• key A unique ID of the function that you want to use for filtering. Keep in mind that other plugins or the BlueBase core may already be using the function key you have thought of, in that case, one filter will overwrite the other.

• value The filter function. This function may or may not be an async function. The function will always have 3 params:

  1. value: The value that is being filtered

  2. context: An object that may have extra arguments or data, passed at the time of execution.

  3. BB: The BlueBase instance.

• priority An optional integer argument that can be used to specify the order in which the functions associated with a particular filter are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter.

• Return Value The (optionally modified) value of the first argument is passed to the filter function.

You can also remove filters from filter hooks using the BB.Filters.delete() function. See Removing Actions and Filters.

Executing a Filter

BB.Filters.run function

You may define and execute your own filters by calling the following method

const newValue = await BB.Filters.run(event, value, [context])

where

• event The name of a filter event

• value The value that is being filtered

• context An optional object that may have extra arguments or data

In the example above, we would put the following params in the function:

await BB.Filters.run(
    'post.comment',
    'A comment with profanity',
    { postId: '123' }
);

useFilter hook

Since BB.Filters.run() function returns a Promise, it gets a bit tricky to handle in a component. For this reason we provide a useFilter hook as well:

const { value, loading, error } = useFilter(
    'post.comment',
    'A comment with profanity',
    { postId: '123' }
);

where the return value is an object with following properties:

• value The (optionally modified) value of the first argument is passed to the filter function.

• loading A flag that indicates if data is currently loading.

• error If an error occurs, it will be set in this variable.

Removing Filters

In some cases, you may find that you want your plugin to disable one of the actions or filters built into BlueBase, or added by another plugin. You can do that by calling BB.Filters.delete('key').

Note that in general, you shouldn't remove anything unless you know what it does and why it does it -- check the BlueBase or other plugin source code to be sure.