Actions and Filters in X

This article was last updated on the January 2, 2017.

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 has 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’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 process or are getting started with X for the first time, please consult this Knolwedge Base article as it goes into detail on how to setup our provided child themes with X. 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.

What Are Hooks?

To quote the WordPress Codex itself, “In [the] WordPress Codex and source code, the terms ‘actions/filters’ and ‘hooks’ are sometime used ambiguously…Hooks are Actions and Filters. In fact, proper grammar would say ‘Actions and Filters can be Hooked.'” Confused? Don’t worry, this is usually the biggest sticking point for most beginners who are working with WordPress. In the interest of making things unambiguous, let’s take a moment to clear things up a bit.

The Difference Between Actions and Filters

The biggest difference between actions and filters is their purpose for how they are used. Here’s the TL;DR version to take away:

  • 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 it’s 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> 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 <head> of your website. You could easily accomplish this with the following snippet of code:

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 it’s own native filters that are used regularly throughout themes and plugins. One such filter, wp_title, is used to update the output of the <title> tag on a user’s website. For example, let’s say that 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 on the Codex, 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 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 over how to modify it based on community input.

X Specific Actions and Filters

Below is a list of various hooks utilized throughout X 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 on how they will function:

Actions

Name File
x_before_site_begin
x_after_site_begin
views/global/_header.php
x_before_site_end
x_after_site_end
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_view_{$file}
x_after_view_{$file}
Note: dynamic actions, see file for more information.
functions/global/helper.php