One of the most valuable features integrated into Genesis is the ease of customization. There are numerous methods to modify and extend your website’s functionality. Although hooks and actions are one way to achieve this, sometimes it is not the most efficient approach to add or remove actions and supply new functions just to modify an existing function’s output. Filters come into play in these situations. Similar to actions, filters can be used to adjust your child themes without modifying the core Genesis Framework files.
It is important to be acquainted with hooks and actions before diving into filters.
What is a Filter? Filters can be viewed as a specialized type of hooks that enable you to modify a function during its execution. You can consider it a hook within a function, where you can input your own directives for what to alter. Alongside the standard hooks, the Genesis Framework includes its unique set of filters, in addition to those that come with every WordPress installation.
What Do Filters Look Like? Filters consist of several components. To utilize a filter, you initially need a function. The filter is positioned within that function, and a callback function (the function that changes the original) can be applied to the filter. The different components appear as follows:
add_action( 'hook', 'my_function' ); // This code executes the original function at the 'hook' hook.
function my_function() { // This is the original function that you want to modify.
echo apply_filters('filter_hook', 'Hello world!'); // This is the apply_filters() function within the original function that creates the filter.
}
add_filter( 'filter_hook', 'callback_function'); // This code adds your callback function to the filter created with apply_filters() in the original function.
function callback_function() { // This code is your callback function that actually does the modification of the original function.
return 'This is my new text!';
}
How do Filters Work and How do I Create One? #
Let’s examine the entire process of a filter’s operation. Assume you have the following code in your child theme:
add_action( 'hook', 'my_function' );
function my_function() {
echo 'Hello world!';
}
In the aforementioned code snippet, the ‘my_function’ function displays the text “Hello world!” at the ‘hook’ position. But what if you wish to modify the text to “This is my new text!”? You will need to implement a filter within the function. Filters are employed using apply_filters(). This should be placed in your function, replacing the original value you want to change. The apply_filters() function appears as follows:
apply_filters( $tag, $value, $var1, $var2, ... );
apply_filters(): To utilize a filter in a function, the function must incorporate apply_filters(). Consider this as a “hook” within the function you aim to filter. It comprises these parameters:
$tag: the “name” of the callback function you plan to implement. You will need to create the callback function later. $value: the existing data you want to modify. $var1, $var2…: any number of extra parameters that can be passed into your filter function to adjust the $value. These are optional. Certain functions integrated into Genesis and WordPress already contain apply_filters(). To leverage these filters, all you need to do is compose the callback function. Refer to the Pre-Applied Genesis Filters section below for more details.
Thus, when you include apply_filters() in your original function, it appears as follows:
add_action( 'hook', 'my_function' );
function my_function() {
echo apply_filters('filter_hook', 'Hello world!', 'var 1', 'var 2');
}
In the code snippet above, our filter is implemented using apply_filters(), where the filter tag is ‘filter_hook’, the value to be altered is ‘Hello world!’, and any additional variables that can be utilized are ‘var 1’ and ‘var 2’. The variables can also be dynamic values denoted by some $var defined in your original function.
If you were to save your files now and refresh the page, what would be different? Nothing! By employing apply_filters(), you’ve just established the hook that your callback function will eventually use, but you haven’t created the callback function itself yet.
Now, let’s develop a callback function. In your functions.php file, you’ll need to compose your callback function and then attach it to the hook you’ve created using add_filter(). It functions similarly to add_action() with hooks. It might resemble the following:
add_filter( 'filter_hook', 'callback_function');
function callback_function($value, $var1) {
if( $var1 == 'var 1' ) {
$value = 'This is my new text!';
}
return $value;
}
In the code snippet above, the add_filter() function targets the $tag we established with apply_filters(), called ‘filter_hook’. It then incorporates the callback function ‘callback_function’, defined right below it.
The callback function comprises the code that modifies the original function’s $value. In this example, it accepts the $value and $var1 from the original function. It verifies whether $var1 is equal to ‘var 1’ (it is) and updates $value to “This is my new text!” Subsequently, it returns $value to the original function.
Keep in mind that the callback function should always return a value rather than echo it. Echoing a value sends it to the browser, preventing any other filters or processes within the original function from utilizing the modified data from your callback function. Returning a value ensures that the data can be passed on to other filters or further modified down the line.
That’s It! #
You’ve successfully employed apply_filters() to create a “function hook” in your original function, composed a callback function, and integrated that function into the hook using add_filter(). Once you save all your files and refresh your site, the modified text should be displayed on the page!
Pre-Applied Genesis Filters #
The Genesis Framework includes several functions where apply_filters() is already integrated, with a $tag predefined for each. These instances are offered for your convenience, so if you wish to modify some output, all you need to do is write your callback function and incorporate it using add_filter() and the supplied $tag. It’s a fantastic shortcut for adjusting output on your website without modifying any of the Genesis core files.
Refer to the Filter Reference for a list of filters and tags that are built into Genesis.