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

1 2 3

<?php apply_filters( 'my_filter', 'code to be filtered goes here' ); ?>

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

1 2 3 4 5 6

<?php function my_function() {     // code for function here } add_filter( 'my_filter', 'my_function' ); ?>

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 theprevious 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:

1 2 3 4 5 6 7

<div class="site-name half left">     <!-- site name and description - site name is inside a div element on all pages except the front page and/or main blog page, where it is in a h1 element -->     <h1 id="site-title">         <a href="<?php echo home_url(); ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a>     </h1>     <h2 id="site-description"><?php bloginfo( 'description' ); ?></h2> </div>

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:

1 2 3 4 5

<h1 id="site-title">     <a href="<?php echo home_url(); ?>" title="<?php echo esc_attr( apply_filters( 'wptutsplus_sitetitle', get_bloginfo( 'name', 'display' ) ) ); ?>" rel="home">         <?php echo apply_filters( 'wptutsplus_sitetitle', get_bloginfo( 'name' ) ); ?>     </a> </h1>

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:

1	<?php echo apply_filters( 'wptutsplus_sitetitle', get_bloginfo( 'name' ) ); ?>

This creates a filter called wptutsplus_sitetitle and then applies it to theget_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:

1 2 3

<h2 id="site-description">     <?php echo apply_filters( 'wptutsplus_sitedescription', get_bloginfo( 'description' ) );?> </h2>

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 myfunctions.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:

01 02 03 04 05 06 07 08 09 10 11 12 13 14

function wptp_colophon() { ?>     <section class="colophon" role="contentinfo">         <small class="copyright half left">             &copy; <a href="<?php echo home_url( '/' ) ?>"><?php bloginfo( 'name' ); ?></a> 2014         </small><!-- #copyright -->               <small class="credits half right">             <?php _e( 'Proudly powered by', 'tutsplus' ); ?>             <a href="http://wordpress.org/">WordPress</a>.         </small><!-- #credits -->     </section><!--#colophon-->   <?php        }

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:

01 02 03 04 05 06 07 08 09 10 11 12 13 14

function wptp_colophon() { ?>     <section class="colophon" role="contentinfo">         <small class="copyright half left">             &copy<a href="<?php echo apply_filters( 'wptp_colophon_link', home_url( '/' ) ?>">) ?>"><?php echo apply_filters('wptp_colophon_name', get_bloginfo( 'name' ) ); ?></a> 2014         </small><!-- #copyright -->               <small class="credits half right">             <?php _e( 'Proudly powered by', 'tutsplus' ); ?>             <a href="http://wordpress.org/">WordPress</a>.         </small><!-- #credits -->     </section><!--#colophon-->   <?php        }

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:

01 02 03 04 05 06 07 08 09 10 11 12 13 14 15

function wptp_amend_colophon_name() {           $name = 'Rachel McCollin';     return $name;       } add_filter( 'wptp_colophon_name', 'wptp_amend_colophon_name' );   function wptp_amend_colophon_link() {           $link = 'http://rachelmccollin.co.uk';     return $link;       } add_filter( 'wptp_colophon_link', 'wptp_amend_colophon_link' );

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:

Summary

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.