Getting Started With WordPress Filters

WordPress filters are one of the major contributors to WordPress’ over all success. They allow developers to extend WordPress tremendously in themes and plugins, which is the main reason why so many developers like myself have adopted the platform.

So what are WordPress filters and how can I use them in my next theme? In short, WordPress filters are a way for you to modify a specific piece of information. Now this might not make sense right away but once you see the code it should begin to.

Understanding WordPress’ Plugin API

WordPress Plugin API

In order to create a new filter we have to first understand what WordPress filters are and when to use them.

WordPress filters are one of the two types of hooks in the WordPress Plugin API that we can utilize to extend WordPress. The other being actions which are outside of the scope of this article but will be discussed in a future article.

So what are hooks? Hooks are events/functions that fire at specific times when the page you’re viewing is being rendered. WordPress is jam packed with hooks that fire throughout every single page load, and it’s these hooks that we want to target or mimic.

Practical Uses For WordPress Filters To Extend Your Plugin/Theme

Filters are different from actions in the what they do and how they’re supposed to be used. An example of a standard WordPress filter would be the body_class filter which allows you to add classes to the <body> of the website.

add_filter( 'body_class', 'my_filter_manipulator' );
function my_filter_manipulator( $classes ){
	$classes .= ' my_really_cool_class ';
	return $classes;
}

So what just happened? Well first we hooked into the body_class filter and provided a callback function to be executed.

add_filter( 'body_class', 'my_filter_manipulator' );

The callback function my_filter_manipulator() is where we manipulate the body_class filter. Now it’s important to understand that every WordPress filter requires an argument to be passed into our function. This is exactly what we did when we added the $classes variable to our my_filter_manipulator() function. The variable $classes is not defined anywhere because it is supplied to us via the body_class hook, and $classes is the data we will be manipulating through our function.

function my_filter_manipulator( $classes ) {
}

By default the body_class filter contains many previously hooked classes provided by WordPress so we don’t want to override them all. Instead we want to add our classes to it by concatenating our classes to the $classes string.

On a side note, not all of the arguments we filter will be strings. In many cases they will come in as integers, or arrays, but for the sake of this specific filter, it’s a string.

function my_filter_manipulator( $classes ){
	$classes .= ' my_body_class_1 my_body_class_2 ';
	return $classes;
}

In the example above we added 2 classes to the <body> of our site, but what if we only want to add it on a specific page or post type? Well this is where WordPress filters can be really handy.

function my_filter_manipulator( $classes ){
	if( is_page('about') || is_post_type( 'lessons' ) ) {
		$classes .= ' my_body_class_1 my_body_class_2'';
	}
	return $classes;
}

In summary we added the classes to the about page and the lessons post type pages only, and we returned the argument back to the filter. It’s important to note that if we don’t return the data, nothing will happen.

Creating WordPress Filters

Now that we understand what WordPress filters are and how we can use them to extend WordPress’ default functionality, it’s time to learn how we can create our own filters.

For the sake of this article I’ll show you how to create a new filter that mimics the functionality of the body_class filter which can be used in multiple areas.

First off let’s imagine that we want to apply a set of classes to multiple html elements so that we can target those elements specifically depending on the page we’re on. The perfect example would be to have a different header and footer for the homepage, pages, posts, etc. What we need to do first is create a function that will contain all of our logic.

function theme_classes() {
}

Next we can begin adding classes based on the page we’re on, and then imploding them into a string to be output.

function theme_classes() {
	if( is_front_page() ) {
		$class_array[] = 'front-page';
	} elseif ( is_single() ) {
		$class_array[] = 'single';
	} elseif ( is_archive() ) {
		$class_array[] = 'archive';
	} else {
		$class_array[] = 'page';
	}
	return sprintf( 'class="%1$s"', implode( ' ', $class_array ) );
}

Now is the fun part. Let’s create a new filter that will allow us to add more classes after the the default classes have been added. The filter we will create will be theme_classes.

function theme_classes() {
	if( is_front_page() ) {
		$class_array[] = 'front-page';
	} elseif ( is_single() ) {
		$class_array[] = 'single';
	} elseif ( is_archive() ) {
		$class_array[] = 'archive';
	} else {
		$class_array[] = 'page';
	}

	/**
	 * theme_classes filter
	 * 
	 * @var array $class_array
	 */
	$class_array = apply_filters( 'theme_classes', $class_array );

	return sprintf( 'class="%1$s"', implode( ' ', $class_array ) );
}

The theme_classes filter now allows us to hook into this function and add new array items to the $class_array variable like so.

add_action( 'theme_classes', 'add_new_classes' );
function add_new_classes( $class_array ){
	$class_array[] = 'some_new_class';
	return $class_array;
}

Page Specific WordPress Filters

Now getting back to the filter we created. It allows us to add classes to the overall $class_array, but what if we just wanted to modify one of the specific page classes that we had defined earlier? Well we could do that by adding more if statements to the add_new_classes() function, or we could add new filters to the default classes in our theme_classes() function to prevent having to add more if/else statements.

if( is_front_page() ) {

	$class_array[] = apply_filters( 'theme_frontpage_classes', 'front-page' );

} elseif ( is_single() ) {

	$class_array[] = apply_filters( 'theme_single_classes', 'single' );

} elseif ( is_archive() ) {

	$class_array[] = apply_filters( 'theme_archive_classes', 'archive' );

} else {

	$class_array[] = apply_filters( 'theme_page_classes', 'page' );

}

So now we’ve created 4 new filters; theme_frontpage_classes, theme_single_classes, theme_archive_classes, and theme_page_classes. By default all of these new filters provide a string, so whenever we hook into them we also need to provide a string.

Now instead of adding a class to all of the pages we can specify any of the default pages with our new filters. Let’s add a class to the frontpage!

add_filter( 'theme_frontpage_classes', function( $class ){
	$class = ' my_page_classes ';
	return $class;
});

Using The Filters In Our HTML Markup

Now that we’ve got our function setup all we have to do is echo it wherever we want these classes to display. In this case we’ll just add it to the header and footer.

<header id="main" <?php echo theme_classes(); ?> ></header>
<footer id="main" <?php echo theme_classes(); ?> ></footer>

And that’s it! Now all we have to do is hook into our filters and the classes we add will be added to both our header and footer.

Final Thoughts

Now that you know the basics of filters I hope you’ll use them more throughout your plugins and themes. Not everything needs to be filterable, but the things that you do choose to allow filters for will definitely help you and other developers extend your code. Lastly, If you enjoyed this tutorial I hope you’ll subscribe and share it. I’ll be posting more like this with time.