A look at WordPress filters. Disable wpautop() on post formatting.

WordPress provides a number of ways to control how content is stored and displayed. There are themes, which I’m sure everybody has already heard of. There are widgets, which are picking up the fame. But there are things deeper in, which aren’t as famous. They are called filters. And WordPress has quite a few of them.

There are some default filters in WordPress, which work behind the scenes, formatting the content the best possible way. The thing is though, while this formatting suits most users out there, sometimes you want to have control over how things are done. In this post, we’ll see how to gain that control.

First of all, what is a filter? WordPress filter is a type of hook (another type is action hook, which we briefly look at while writing first WordPress plugin). Filters allow data modification on-the-fly. Which means you can change something after it was read and compiled from the database, but before it is shown to your visitor. Or, you can modify something a visitor sent to your database, before it is actually written there.

Modifying a filter call is as easy as calling add_filter(‘filter_name’,’your_function_name’). With the only caveat being that you need to know what data WordPress sends to a filter function. But, as always, there are a few ways to find out.

A good way to start playing with filters is checking out what defaults are and how they work. Default filters are listed in wp-includes/default-filters.php file. From this list, you can learn the names of some filters, the names of functions which are called, and the order in which they are called.

Once you know the names of functions which WordPress uses as filters, you can find them in the rest of PHP files in wp-includes/ directory, see which parameters they accept, what values they return, and how they work in general. This is one of the beauties of the Open Source Software, which WordPress is a great example of.

Let’s get to a practical example, to see how it all works. In your theme, which is the function call which produces the most content? Well, while WordPress can be used for a number of things, I’d say it’s safe to assume that the_content() line which displays the content of your posts and pages brings in the most. Let’s dive into WordPress source code and see how it works. It is defined in the file wp-includes/post-template.php around line 53 (WordPress 2.2.2 or so). Here is how it looks:

(I cut it off a bit on the right, but it doesn’t matter for our example.)

The function is small and easy to understand. First it gets teh content of the post. Then it applies the ‘the_content’ filter. Then it does some more string replacements. And then it prints out the result.

Now, look at the line where it applies the filters. The filter name is ‘the_content’ and argument given to is the actual content of the post. It expects the processed and modified content back, as it will still need to print it.

How is the content modified? Let’s see. We go back to the wp-includes/default-filters.php file and find all lines for the ‘the_content’ filter. There are four of them, calling wptexturize(), convert_smilies(), convert_chars(), and wpautop(). All of these are defined in wp-includes/formatting.php .

Now we have the knowledge of how WordPress processes the content before displaying it visitors of the web site. We can also understand how many formatting plugins work, as modifying filters it the most common way of tweaking content display. And, of course, we can make our own changes.

Just for the sake of the example, let’s disable WordPress’ default wpautop() call for ‘the_content’ filter. Although it does a good job, we know better how our content should look. Even if for the sake of the example.

To disable a filter, we could either comment an appropriate line in wp-includes/default-filters.php – an ugly solution and a big “No!No!”, or write our own plugin – a much better and preferred solution, assuming no other plugin for this functionality exists. Like WP Unformatted from Alex King (which you should definitely check). Here is all that I had to write for the wpautop() to disappear from my content filtering process.

I can’t hide any longer. Yes, you are right. All this post was to write a single line. :) But I hope you’ve learned a thing or two on the way.