1. Code
  2. WordPress

Adding Filter Hooks to Your WordPress Theme Framework

This post is part of a series called How Theme Frameworks Actually Work.
Adding Functions to Your WordPress Theme Framework
Creating Child Themes for Your WordPress Theme Framework

So far you've added action hooks to your theme framework and you have written some functions which are activated via those hooks. The next step is to add some filters, which give you even more flexibility.

A Quick Overview of Action and Filter Hooks

Before continuing, it's worth giving a quick overview of the difference between action and filter hooks:

  • Actions are triggered at specific points in your code. The action hook itself doesn't contain any code which is executed, but provides a location ion the code where you can make things happen via functions which you activate via the hooks.
  • Filters make it possible to change code which is already written into your theme. Instead of being empty, a filter hook is wrapped around some existing code, which you can then amend or override using a function which you attach to the hook.

For more details, see this great guide to action and filter hooks.

How to Create and Use a Filter Hook

You then access that filter hook using the add_filter() function, as follows:

What you add to the function will replace the filterable code in the framework, so that's where you make your changes or overrides.

What You'll Need

To follow this tutorial, you'll need:

  • A development installation of WordPress
  • A code editor
  • If you're working with the code used in my framework, the code from the previous tutorial.

Adding Filter Hooks

In this tutorial, I'm going to add three filter hooks to the framework:

  • In the header, I'll enclose the site title and description in a filter
  • In the footer, I'll add a filter to the colophon function which we added in the last tutorial

This means that in future, both of these can be amended or overridden by a child theme or plugin. You could add many more filters to your theme framework: anywhere that you're adding code or markup which you might want to change at a later date, you can use a filter to allow that change to be made without having to create a new template file in a child theme.

Adding a Filter Hook to the Site Title and Description

Start with the site title and description. Open your theme's header.php file and find the following code:

Instead of writing one filter for all of this, it's better to add a filter to each of the site title and site description, so that you can amend or change what's output for one or both.

In each case, you replace the bloginfo() function with the get_bloginfo() function, and then add echo before the apply_filters() function. Let's start with the site title. Edit the code inside the h1 element so it reads:

As you can see, I've added the apply_filters() function twice here - once for the title attribute of the link, and then again for the text displayed. The new code is below:

This creates a filter called wptutsplus_sitetitle and then applies it to the get_bloginfo( 'name' ) function. This is then echoed.

Now let's do the same with the site description. This is a bit simpler as there's no link. Edit the h2 element so it reads:

Again, this won't affect the output content of that element but it does give you a filter you can use to change it at a later date.

Adding a Filter Hook to the Colophon

Next, I'm going to add a filter to the colophon, which is contained in a function in my functions.php file. This will let users of my framework amend or override the content of the colophon.

First open, your functions.php file and find this block of code:

Now take the line that outputs the name of the blog inside a link and wrap each of the two functions in an apply_filters() function so it reads:

Here, I've created two filters:

  • echo apply_filters( 'wptp_colophon_link', home_url( '/' ) applies to the link which the name points to.
  • echo apply_filters('wptp_colophon_name', get_bloginfo( 'name' ) ) applies to the name itself.

If I wanted to change each of these at a later date I could do so with a couple of simple functions, as follows:

Each of these functions returns some static content in place of the php function in the original filter, replacing the home url and the blog name with my name and my blog's url:


Here, I've added a couple of simple filters which will let you or your framework's users change what's output without having to create new template files. As we've seen, a filter is different from an action in that it lets you modify what's already output by the hook, rather than adding something new to an empty hook.

In some cases, you might find that a filter is getting too complex, in which case you would need to write a new function or sometimes create a new template file. For example, if I wanted to make more significant changes to the colophon, I would add a new function called wptp_colophon() to my child theme - as the wptp_colophon() function in the framework is pluggable, my new function would override it. But if I wanted to replace the whole footer, I'd have to create a new footer.php file.

Filters can be helpful however to help avoid having to do such drastic work - when you're writing your framework's template files, consider what is being output that your users might want to amend, and wrap it in a apply_filters() function.

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.