Filter hooks in WordPress provide a very powerful way to “alter” the output of functions. Using filters we can easily add extra HTML to some functions, and strip HTML from other functions. Some filters, such as the “body_class” filter, allow us to modify the class names of an HTML element, and some filters have nothing to do with HTML at all. The “get_attached_file”, for example, is for modifying the data retrieved by the get_attached_file() function. I’m going to keep with the theme of modifying HTML, since that is what most filter hooks are for, and show you how to setup a custom filter to modify the output from your plugin.

If you’re not familiar with filter hooks, then please consult my Quick Introduction to Using Filter.

Example One – Stripping HTML Tags

Let’s assume, for a moment, that we are outputting some HTML defined by the user, and to ensure that none of that HTML causes problems (such as broken layouts) we want to strip out all non-allowed tags. By this I mean that we’re only going to allow certain HTML tags to be used. The WordPress comments form is a good example of where something like this happens. We also may want to strip out non-allowed tags to prevent malicious code being placed with <script> tags.

So this function will serve as our sample HTML (we can pretend it was defined by a user somewhere):

1
2
3
4
5
6
7
8
9
10

function pippin_sample_html() {	
	ob_start(); ?>	
	<ul>
		<li>List Item <em>One</em></li>
		<li>List <strong>Item</strong> Two</li>
		<li>List Item <a href="#">Three</a></li>
	</ul>	
	<?php
	return ob_get_clean();
}

This is nothing more than a simple unordered list with a few other HTML tags inner mixed.

The HTML from this function is going to be outputted on our site, but before it does, we want to strip out all of the tags that are not allowed. In this case, let’s assume the only allowed tags are <ul> and <li>. To remove all of the other tags, we’re going to pass the HTML through a filter before we echo it. So let’s write the filter function.

1
2
3
4
5

function pippin_strip_tags_filter($html, $preserved_tags = '') {
	$html = strip_tags($html, $preserved_tags);
	return $html;
}
add_filter('pippin_strip_tags', 'pippin_strip_tags_filter', 10, 2);

The function takes two parameters: the HTML to be filtered and a string of the HTML tags we want to preserve. Inside of the function then, we use the strip_tags() function to remove all unwanted tags. At the end, we return our HTML with the unwanted tags removed.

We then use the add_filter() function to attach our pippin_strip_tags_filter() function to a filter hook. Since our filter takes two parameters, instead of the default one, we have to specify the number of accepted arguments.

So now, to output our HTML with the unwanted tags removed, we can do this:

1
2

$html = pippin_sample_html();
echo apply_filters('pippin_strip_tags', $html, '<ul><li>');

The final result will be:

1
2
3
4
5

<ul>
	<li>List Item One</li>
	<li>List Item Two</li>
	<li>List Item Three</li>
</ul>

Example Two – Adding a Wrapper to Existing HTML

For this example, let’s use the same HTML as we did before:

1
2
3
4
5
6
7
8
9
10

function pippin_sample_html() {	
	ob_start(); ?>	
	<ul>
		<li>List Item <em>One</em></li>
		<li>List <strong>Item</strong> Two</li>
		<li>List Item <a href="#">Three</a></li>
	</ul>	
	<?php
	return ob_get_clean();
}

Now let us suppose that we want to add some wrapper HTML around the output of our pippin_sample_html() function. Let’s start with our filter function:

1
2
3
4
5
6

function pippin_add_html_wrapper($html, $begin, $end) {
	// wrap our original HTML with the new tags
	$html = $begin . $html . $end;
	return $html;
}
add_filter('pippin_html_wrap', 'pippin_add_html_wrapper', 10, 3);

The function takes three arguments:

1. The HTML to wrap
2. The HTML to use as the opening wrapper tag
3. The HTML to use as the closing wrapper tag

Inside of the function we simply combine the three parameters, and then return it.

So to output our sample HTML with a custom wrapper, we use this:

1
2

$html = pippin_sample_html();
echo apply_filters('pippin_html_wrap', $html, '<div id="sample_wrapper">', '</div>');

Both of the examples I’ve shown you here are pretty simple, but very powerful at the same time. Filters can be used for all sorts of things, so I encourage you to be creative and play around with them.