Using WordPress Filters to Customize Outputs
WordPress filters can be a confusing topic to explore, but once learned, they are a powerful way to build customized themes and plugins, requiring only small code changes to make a big impact.
If you’re not familiar with WordPress’ inner workings, then you’re probably wondering what filters are in the first place. The main idea behind filters is a way to modify the output of functions before it is sent to the browser. Basically, it lets you inject custom code or modify the output on the fly. This applies to both WP core functions (if you edit these directly, changes would be lost with an update anyway) and also plugins and other custom functions.
With that in mind, you can imagine the various ways filters could be used, like showing different content based on the post or page, or creating plugins that are easily customized without a need to edit the core files.
Add_filter, remove_filter, and apply_filters
Each of these functions plays a role in the process. First, let’s define each function and how it works, and then we will walk through an example that shows how each function works in practice.
Apply_filters – Designated a filter within content. This function is used to set text or other elements within the code that can later be changed with the other two functions.
Add_filter – This function allows you to alter existing apply_filters function that are already in place.
Remove_filter – Used to remove add_filter statements.
Apply_filters first
The apply_filters function is the easiest of the three to use, as it basically acts like an echo statement. The formatting works like this:
echo apply_filters( ‘some_action’,’some default text’, 0);
The function takes three parameters, the action id, a default value, and the priority (this can be any number). If all you did was this, then the output would be “some default text”. If you were building a plugin with output, using apply_filters (rather than hard-coding text or classes) in strategic spots allows users to override this content remotely by using a different function.
Cue the add_filter statement
With add_filter you can override previously defined apply_filters statements. We will use the previously defined filter in the example above, and override it. In the functions.php file of your theme, place this code:
add_filter( ‘some_action’, ‘change_some_action’, 0 ); function change_some_action( $val ) { return ‘changed text’; }
There are a few things to note here:
- The add_filter function takes the ID we placed in apply_filters (some_action) and uses that as its own ID.
- We provide a custom function name in quotes, which we will be calling.
- We set the priority, which must be the same value as the apply_filters statement.
After the add_filter statement, we setup our custom function change_some_action, and set a parameter of $val. We then return a custom string “changed text”, which will override the “some default text” string returned by default.
What exactly is the purpose of that $val parameter, which we didn’t use? The $val parameter gets the currently set string on the filter, which we could pass back through like so:
function change_some_action( $val ) { return $val . ‘ which is now changed.’; }
This would return “some default text which is now changed”. This type of filtering is perfect if the initial apply_filters statement is for passing classes to an element. You would normally want to keep the default classes, and then add you own if necessary.
Removing filters
Add_filter and apply_filters work well together, but what if someone has already added an add_filter statement to the apply_filters item? Remove_filter is perfect for this as it will remove the attached add_filter, allowing you to add your own. The easy way to use remove_filter is to copy the add_filter statement and then change the add to remove.
add_filter( ‘some_action’, ‘change_some_action’, 0 );
Becomes:
remove_filter( ‘some_action’, ‘change_some_action’, 0 );
The only thing to keep in mind with changing add to remove in the statement is that if there is a fourth optional parameter in the add_filter statement, it needs to be deleted when removing the filter.
Wrap up
Filters can be a lot of fun and offer great functionality. There are various built-in filters that WordPress uses. Once you have mastered filters, make sure to check out the hooks functionality in WordPress as well. Combined, these two features can really shift the way you view WordPress development.
Top image via Flickr user Bob Duran.