Actions, Filters and Hooks (oh my)
In this article, we're going to explain how to use action filters and hooks
What is a Hook in WordPress
If you've worked with WordPress for even a short amount of time, it is very likely that you've heard of hooks (i.e. actions and filters). Hooks are an incredibly important part of the WordPress ecosystem as modifying core files is a big no-no. However, properly placed actions and filters can allow a user to easily overwrite or output some new content to a page or post with ease. Essentially, they're what make customizations in WordPress easy and keep your updates from getting overwritten every time you need to update core files or your theme.
Not only does WordPress have its own native hooks for users to tap into, it also provides a useful API for theme developers to add their own actions and filters as needed. X and Pro have a lot of useful hooks placed throughout the theme that you might not know about, and they're just waiting there for you to do cool stuff with them and to make your life easier!
The aim of this article is to give a brief overview of what hooks are in WordPress and how to use them. Then we'll provide some examples of X/Pro's specific hooks and how to use them, as well as a complete list of all hooks and filters implemented throughout the theme. Whether you're a complete beginner or an experienced dev, we think everyone will find something useful in this article.
Please keep in mind that when making any modifications to a theme, this should always be done using a child theme. If you are unfamiliar with this method or are getting started with X and Pro for the first time, please consult this article as it goes into detail on how to setup our provided child themes with X and Pro. Note that all of the examples provided below will need to go in the functions.php file in the root directory of the child theme.
The Difference Between Actions and Filters
The biggest difference between actions and filters is their purpose for how they are used:
- Actions: used when something needs to be added.
- Example: outputting a piece of content at the end of every post (we didn't change anything since we are adding new content).
- Declared with the add_action() function.
- Used with the do_action() function.
- Filters: used when something needs to be changed.
- Example: overwriting the content of your
<title>tag on a particular page or post (nothing is added, we're changing something that was already there). - Declared with the add_filter() function.
- Used with the apply_filters() function.
For the sake of this article, we'll focus primarily on the add_action() and add_filter() functions, as these are what will allow you to tap into various parts of WordPress or the theme as needed. do_action() and apply_filters() are primarily used by the WordPress core team or theme developers so that they can add hooks which will later be utilized by users for customization.
Declaring Actions
To declare an action (i.e. add some content), you will use the add_action() function. Doing so looks something like the following:
function my_new_action() {
// Things the new action does.
}
add_action( 'action_name', 'my_new_action', 10 );What we have here is the bare minimum you need to declare an action. A newly created function labeled anything we'd like it to be which will perform a specific task, and the add_action call, which hooks our function into the specific action we're looking to target. The 10 in the third parameter spot is optional and is the action's priority. Lower numbers will result in earlier execution, while higher numbers will result in later execution. 10 is the default that is used if nothing is provided for this parameter.
As stated previously, WordPress has some of its own native actions that are used regularly throughout themes and plugins. One such action, wp_head, is very well known and incredibly useful. This hook will output content to the head section of your website, allowing you to easily place markup there if needed for a specific task (i.e. social media meta information, analytics scripts, et cetera).
For example, let's say that you had a custom tracking code from a software provider that they have asked you to place in the header('
') of your website.<?php
function third_party_tracking_code() { ?>
<script>
// Third party tracking code.
</script>
<?php }
add_action( 'wp_head', 'third_party_tracking_code' );We can see that we're hooking our third_party_tracking_code() function into wp_head hook above using add_action(). Sometimes it is easier to use a closing PHP tag (?>) at the beginning of your function, which will allow you to write standard HTML without needing to wrap it in quotes as a string. If you do this, make sure that you use the opening PHP tag (<?php) again before starting to use PHP.
Declaring Filters
Similarly to actions, to declare a filter (i.e. change some content), you will use the add_filter() function. WordPress filters are a little more difficult to understand compared to actions because you will most likely be manipulating data that is already present, so there are a few more "moving parts" in the works. Doing so looks something like the following:
function my_new_filter( $args ) {
$args = 'My new value.';
return $args;
}
add_filter('filter_name', 'my_new_filter', 10, 1);What we have here is the bare minimum you need to declare a filter. The add_filter() function is used mostly like add_action() with an additional parameter at the end to specify the number of arguments the function accepts. This is optional and can most likely be left out, but might cause some issues in other cases if left out.
The main difference to note here is that we are passing in some data from the filter (i.e. $args), updating that value in the function, then returning that updated value at the end of the function.
As stated previously, WordPress has some of its own native filters that are used regularly throughout themes and plugins. One such filter, wp_title, is used to update the output of the tag on a user's website. For example, let's say that you wanted to update this tag on the homepage of your website, but leave it the same everywhere else, you might use something like the following:
function custom_homepage_title( $title ) {
if ( is_front_page() ) {
$title = 'My Super Awesome Homepage Title!';
}
return $title;
}
add_filter( 'wp_title', 'custom_homepage_title' );Here, we're using WordPress' native is_front_page() conditional to check whether or not the page we're viewing is the home page; if it is, we output My Super Awesome Homepage Title! instead of the standard output. Notice that we've passed in the appropriate data to ensure that the title can be overwritten correctly. Finding out information on these pieces of data can usually be found in the official WordPress documentation, but it might occasionally require rooting around in the source code of WordPress itself.
As stated previously, filters are a little more involved than actions and there aren't really many filters to utilize in X and Pro that are specific to the theme. If you ever need to modify a specific filter in WordPress, a quick Google search will usually yield plenty of information on how to modify it based on community input.
X and Pro Specific Actions and Filters
Below is a list of various hooks utilized throughout X and Pro along with a reference on where to find them in the theme. This list is subject to change but is meant to be as comprehensive as possible to assist in your theme development (all file locations are relative to the /framework/ directory). Make sure to view the file directly to see exactly how these hooks are implemented so that you can have a better idea of how they will function:
Actions
x_before_site_begin x_after_site_begin | legacy/cranium/headers/views/global/_header.php |
x_before_site_end x_after_site_end | legacy/cranium/footers/views/global/_footer.php |
x_before_the_content_begin x_after_the_content_begin x_before_the_content_end x_after_the_content_end | views/global/_content-the-content.php |
x_before_the_excerpt_begin x_after_the_excerpt_begin x_before_the_excerpt_end x_after_the_excerpt_end | views/global/_content-the-excerpt.php |
x_before_masthead_begin x_after_masthead_begin x_masthead x_before_masthead_end x_after_masthead_end | framework/views/header/masthead.php |
x_before_colophon_begin x_after_colophon_begin x_colophon x_before_colophon_end x_after_colophon_end | framework/views/footer/colophon.php |
x_before_view_{$file} x_after_view_{$file} | functions/global/view-routing.php |
| Name | File |
|---|
Summary
We've talked about the hooks in the WordPress and how you can utilize the feature into your Child Theme, we also talked about the difference between actions and filters in WordPress and delved into declaring them. Finally, we've listed all the available X and Pro specific hooks available.
See something inaccurate? Let us know