Ease of customization is one of the most useful features built into Genesis. There are many ways to alter and expand functionality on your website. Hooks and actions are one way of accomplishing this, but sometimes adding/removing actions and providing new functions simply to change an existing function’s output is not the most efficient method. This is where filters come in. Just like with actions, you can use filters to modify your child themes without editing the core Genesis Framework files.
You should be familiar with hooks and actions before exploring filters.
What is a Filter?
Filters are really just a specialized form of hooks that allow you to modify a function as it executes. You can think of it as a hook inside of a function where you can insert your own instructions on what to change. As with regular hooks, the Genesis Framework contains its own unique set of filters in addition to the ones included with every WordPress® installation.1
What Do Filters Look Like?
“Filters” as a whole are made up of several parts. In order to use a filter, you need a function to start out with. The filter is placed inside that function, and you can apply a callback function (the function that alters the original) to the filter. The different parts look like this:
How do Filters Work and How do I Create One?
Let’s take a look at how a filter works from start to finish. Say you have this code somewhere in your child theme:
In the above block of code, the function called ‘my_function’ outputs the text “Hello world!” at the ‘hook’ location. Now, what if you want to change the text to “This is my new text!” instead? You’ll have to apply a filter within the function. Filters are applied with apply_filters(). This goes into your function in place of the original value that you want to alter. The apply_filters() function looks like this:
apply_filters(): If you want to filter a function, that function must include apply_filters(). Think of this as a “hook” inside of the function you are trying to filter. It contains these parameters:
- $tag: the “name” of the callback function you intend to apply. You’ll have to create the callback function later.
- $value: the existing data that you wish to alter.
- $var1, $var2…: any number of additional parameters you can pass into your filter function to modify the $value. These are optional.
There are some functions built into Genesis and into WordPress that already include apply_filters(). To use these filters, all you’ll have to do is write the callback function. See Pre-Applied Genesis Filters below for more information.
So when you add apply_filters() to your original function, it looks like this:
In the above block of code, our filter has been applied using apply_filters(), where the the filter tag is ‘filter_hook’, the value to be modified is ‘Hello world!’, and any additional variables that can be used are ‘var 1’ and ‘var 2’. The variables can also be dynamic values represented by some $var defined in your original function.
So, if you were to save your files now and refresh the page, what would change? Nothing! By using apply_filters(), you’ve just created the hook that that your callback function will eventually use, but you haven’t created the callback function itself yet.
So let’s create a callback function. In your functions.php file, you’ll need to write your callback function and then add it to the hook you’ve created using add_filter(). It works similarly to add_action() with hooks. It might look something like this:
In the above code, the add_filter() function targets the $tag we created with apply_filters() called ‘filter_hook’. It then adds the callback function ‘callback_function’, defined immediately below it.
The callback function contains the code that alters the original function’s $value. The example here takes in the $value and $var1 from the original function. It checks whether $var1 is equivalent to ‘var 1’ (it is) and changes $value to “This is my new text!” It then returns $value into the original function.
Note that the callback function should always return a value, not echo it. Echoing something outputs that value to the browser, which stops any other filters or processes in the original function from using the altered data from your callback function. Returning a value ensures that the data can be passed along to any other filters, or altered further down the line.
That’s It!
You’ve now used apply_filters() to create a “function hook” in your original function, written a callback function, and added that function to the hook with add_filter(). When you save all of your files and refresh your site, your altered text should appear on the page!
Pre-Applied Genesis Filters
The Genesis Framework contains a number of functions where apply_filters() is already built-in with a $tag for each already defined. These instances are provided for your convenience, so that if you want to alter some output, all you have to do is write your callback function and add it using add_filter() and the provided $tag. It’s an excellent shortcut for modifying output on your website without altering any of the Genesis core files.
See the Filter Reference for a list of the filters and tags that are built into Genesis.