wpthemedetector-logo
WordPress Theme Detector Blog
wpthemedetector-wordpress-filters

Add functions to your WordPress child theme (5) – WordPress Filters

9 comments

In our post about Introduction to WordPress Hooks we saw the differences between WordPress Actions and WordPress Filters, and then in the previous tutorial of this series we learned about using actions in our child theme. So it is time for WordPress Filters now.

As we already saw, a WordPress filter modifies the value of something whenever the hook is triggered. And, as opposed to what happened with actions, the final result of a filter is not usually an output because the filter returns something that would be outputted anyway, only that the filter modifies it before it is sent to output (for example by changing the way the text is formatted on a post).

What do we need WordPress filters for?

But what does all this mean in the practical world, and how can we use and take advantage of WordPress filters? We´ll see it with the aid of some examples.

WordPress filters do their work somewhere between the database and the browser, or just the other way around, depending on what the WordPress code is doing at any particular moment.

For instance, when the user is searching a blog, WordPress retrieves the applicable posts from the database and, among other things, it filters the content of each post to truncate its length and to add the “read more…” link before sending it to the screen to display the archive page. In cases like this you could think of the job done by the filter as “last minute” editing.

WordPress filters can be used for a wide variety of applications. Just to name a few of them, we could use WordPress filters to achieve any the following:

  • Add specific html to particular pieces of data.
  • Change the formatting of text.
  • Add elements to content.
  • Modify the way any part of the WordPress data is displayed.

For example, que might want to wrap the post title inside a div with a particular CSS class, or add a background to the post excerpts on a blog page, or add a notice at the beginning or end of a post whenever a certain condition is met. All that (and much, much more) can be done by means of WordPress filters.

The add_filter function

So WordPress filters intercept the piece of data to be modified and alter it the way we want. What we use to intercept the right data in the right moment is actually the hook itself. It´s the $tag variable in the add_filter function, which in its simplest form looks like this:

add_filter( $tag, $function_to_add );

The add_filter function is what we´ll use in order to bind a filtering function ($function_to_add, usually referred to as “callback function” or just “filter function”) to a particular filter hook ($tag).

The callback or filter function needs to be fed with the unmodified data (for example, the content of a post) and it must return the modified (filtered) data.

So, if for example we were to filter the post content by adding to every post on our blog that belongs to the “tutorials” category a final paragraph in italics saying “I hope you like this tutorial, please let me know through the comments”, our filter function would look like this:

So our function takes the post content retrieved from the database (which resides in the variable $content) and, in case the post belongs to the tutorials category, adds the desired paragraph to it. If it doesn´t, the function just returns the unmodified content (because the if condition is not met). But our function must return the data (the post content, in our case) anyway, whether it is filtered or unmodified, for the rest of the WordPress code to use it. This also means that a particular piece of data can be filtered as many times as we want or require.

Once we have such a function defined in the functions.php file of our child theme, all we need to do is to bind it to the appropriate hook. The way to hook our new function is, as we´ve just seen, the add_filter function.

We just need to add a new line of code to our child theme´s functions.php file hooking our custom filter function to the appropriate hook.

In our example we want to modify the content of some posts, so we´ll bind our function to the the_content hook. According to the WordPress Codex: the “the_content” filter is used to filter the content of the post after it is retrieved from the database and before it is printed to the screen.

So these are the lines we´ll need to add to the functions.php file of our child theme:

On the code above I´ve changed the name of the callback function to something more significant than “function_to_add”, if you noticed. Other than that, the only addition to what we had before is the add_filter line, where we´re hooking our function to the “the_content” filter hook.

Now it is time to check whether those few lines of code we´ve added to our child theme work or not.

I´ve pasted those lines on the functions.php file of a child theme of Twenty Sixteen on a local dev site, and then published a couple of sample posts, one of them having the Tutorials category.

Here we have the results. This is the post with the Tutorials category:
worpress-filters-example-1

However, my Lorem Ipsum post does not belong to the Tutorials category, and therefore this other post doesn´t get the final paragraph we´ve just added for tutorials:

worpress-filters-example-2

Wow, that was simple, wasn´t it? Imagine all you can achieve with WordPress filters!

By the way, when I talked before about the simplest form of the add_filter function it was because this function can accept the use of optional arguments and it can also handle optional priorities (as it also happens with the add_action function in the case of action hooks, as we saw in the previous post of this series), its general form being like this, for your information:

add_filter( $tag, $function_to_add, $priority, $accepted_args );

For any other example of application you might think of, you can select your appropriate filter by means of the Filter Reference page on the WordPress Codex.

Why WordPress filters work

At different places of the WordPress core code (or of your parent theme code, for instance), a function named apply_filters is called. It is used to create a new filter hook:

apply_filters( $tag, $value );

When that point of the code is reached, every filtering callback function bound to that particular hook will be executed, so the piece of data contained in $value (the value on which the filters hooked to $tag are applied on) will be modified by the functions that were hooked via the add_filter function.

A final word

Hey! By the way, I almost forgot to add this:

I hope you liked this tutorial, please let me know through the comments.

🙂

Luis Alejandre

Luis is the creator of the WPThemeDetector tool and the chief editor of this blog. You can read more about Luis in our About page.
Liked this post? Please share it!

9 Comments

  1. its nice tutorial specially i learn The add_filter function…..

  2. Thank you Luis Alejandre for making a great tutorial about how to add functions a wordpress child theme. As I have a basic knowledge about theme development, I understand your tutorial fully. A bunch of thanks for your step by step tutorial.

  3. Thank you very much, very well explained like the subjects of the previous posts.

  4. Normally custom code would be overwritten during the next update to the newest version of WordPress.
    In this is case normally it may affect main files of theme and this is why it is necessary to customize code in child theme so that it can be possible to modify some parts of WordPress, a theme without modifying the original files.
    This is very nice and useful initiative sharing here such informative article .

  5. Thank you for this tutorial. It helps me understand how WordPress Filters Work!

  6. Very easy to understand the relationship between the tag and the hook the way demonstrate it. Thank You

  7. Hi,
    Very helpful much appreciated, crystal clear about filters. 🙂

  8. Congratulations for this post series. You have written a great tutorial even for non code savvy marketing professionals

  9. Hi Luis Alejandre,

    Thanks for your great post and tutorials on how to add WordPress filter in your child theme and how it works for you by intercepting data. I hope the whole procedure will be helpful for the users.

Submit a Comment

Your email address will not be published. Required fields are marked *