Use Content Filters for Easier Customization

This article is deprecated! Any technical information refers to software versions that are now obsolete. Please visit the DIYthemes Blog for current updates, or check out the old Thesis Blog for a treasure trove of website marketing insights.

By now, a lot of you have upgraded to Thesis 1.5.1, enjoying all of the awesomeness already mentioned by Chris. As usual, though, we like to pack in as much awesomeness as we can into a release, even a point release like 1.5.1!

As you all know, we’re a big fan of hooks here at DIYthemes, with Thesis now containing over 50 hooks allowing for countless and varied customizations (which we love seeing, by the way). The next thing I’m going to mention was quietly introduced in a couple of places in the past, but 1.5.1 has seen the idea greatly enhanced.

The idea? Filters!

What are filters? I’m glad you asked! A filter, like a hook, is a point of interaction within Thesis; just like with hooks, functions are created and added to the filter.

The difference? Filters operate on content that already exists. This means two things:

1. A filter function must accept a variable as a parameter, and

2. a filter function must return the resulting content after all operations on it have been performed.

Let me illustrate with a simple example: I want to change “add one” to “Shout @ Me!” in the introduction to comments. To work on that text, we’ll be using the thesis_comments_intro filter, but first we need to create our function:

function custom_comment_intro($content) {
    [...your code will go here...]
}

You can name your function just about anything you’d like; the import thing is that you allow a variable to be passed to your function. The name of the variable is irrelevant, so for simplicity, I usually use $content.

The $content variable contains all of the output of thesis_comments_intro(), including not only the “add one” text, but the entire div.comments_intro block. All of that markup is available via our $content variable to modify — we can remove it completely, change all of the words to something contextual on our site, use our own markup rather than Thesis’ default, and so on. Sky’s the limit, just like with hooks!

Okay, back to our function. Let’s take our variable and do something with it:

function custom_comment_intro($content) {
	$content = str_replace('add one', 'Shout @ me!', $content);
}

See what we’ve done there? We’ve taken the original $content and modified it using the str_replace() PHP function. Only two more things we need to do to get our customization up and running, so let’s add them in to the mix:

function custom_comment_intro($content) {
	$content = str_replace('add one', 'Shout @ me!', $content);
	return $content;
}
add_filter('thesis_comments_intro', 'custom_comment_intro');

What we’ve done is to return the modified content. You’re probably used to echoing content when customizing with hooks; filters, however, are processed prior to echoing anything, so we simply want to return our content so that it can continue to be processed by any other filters or WordPress/Thesis functions which need to be run.

Finally, we add our custom function as a filter on the thesis_comments_intro item.

Phew! Well, that’s filters in a nutshell, and I am considering 1.5.1 as merely our first steps into that territory. Hooks have allowed you to add your own content for a long while now; filters are going to allow you to modify what’s output by Thesis itself. It won’t be long before you’ll be able to build a site with Thesis that will be virtually unrecognizable as Thesis. And I like that idea. I hope that the community of designers and users really embrace the use of filters just as you have done with hooks.

I’ll be putting together some documentation over the next couple of days, explaining what the default content of these hooks are and so on, but for now, I want to close this post with a list of the currently available filters:

• thesis_trackback_link
• thesis_trackback_datetime
• thesis_allowed_tags
• thesis_comments_link
• thesis_comments_intro
• thesis_avatar
• thesis_comments_navigation
• thesis_content_classes
• thesis_img_caption_shortcode
• thesis_body_classes
• thesis_get_header
• thesis_get_footer

Let the games (and experimentation) begin!