Ridding WordPress Plugins of Template Tags [en]

[fr] Cet article décrit une méthode permettant de se défaire des "template tags" qu'utilisent certains plugins. Plutôt que de copier le fameux template tag à 3 endroits différents dans son thème (comme c'était le cas auparavant pour Basic Bilingual), il est possible de modifier à peu de frais un plugin pour qu'il injecte automatiquement son contenu dans le blog.

If you’re like me and use a bunch of plugins to liven up your WordPress blog, you’ve probably noticed that adding template tags in your favourite (or favourite-of-the-week) theme files can quickly become a royal pain in the neck.

One of the things I wanted to do with Basic Bilingual, and which I did with the last release, was make the plugin inject the text for the “other excerpt” (the French text you can see at the top of this post) automatically into the templates and feeds.

Once I’d figured out how to do that, I realised I could modify other plugins, too. And I’m going to tell you how you can do it, too. This method should work for any plugin which generates a template tag, as long as you want the content generated by the plugin to go immediately after or before the post content. (I’m still working on advanced rules for cases where you want to make modifications elsewhere in the template.)

Christine‘s Inline Tag Thing put me on the track (thanks!), as it does just that. Here’s the trick:

  1. create a function which concatenates (= “adds”) the plugin output to the content
  2. add an action hook to the plugin to apply that function to “the_content”.

Fear not, I’ll explain all. You don’t need to really know much PHP to do this, as long as you’re comfortable wading through a bit of code and copy-pasting stuff and making a few small modifications.

Let’s take an example: the Similar Posts plugin, which I’m now using to point out posts related to the current one (normally, in a box at the top of the post if you’re on the website, and as a list at the end of the post if you’re reading the feed).

Similar Posts provides a template tag, <?php similar_posts(); ?>, which you can paste in your template where you like the related posts to appear. Personally, I want them to appear on the main blog page, on the individual archive pages, and on the monthly, category, and taggy archive pages. This means I need to paste the tag into at least 3-4 different template files. And if I decide that I want the tag at the top of the post rather than the bottom, or I decide to remove it, there I go again. Not optimal.

So, here’s how I made it “better” (for me):

A. First, I looked at the plugin code to figure out where the template tag function was; in this case, quite easy, it’s the function called similar_posts(), logically. Here are the last two lines of this function, which do the actual data output:

print $result;
if (defined('POC_CACHE')) print $cache_time;

I changed them to:

return $result;
if (defined('POC_CACHE')) return $cache_time;

So that they didn’t print directly (ie, output text), but just return the value of the data we want to insert.

Then, I created the following function:

function sp_embed_similar_posts($content) {
    $content = similar_posts() . $content;
    return $content;

This function takes one parameter ($content), and sticks the output of similar_posts() in front of it. Now you see why we needed to change the other function so that it didn’t print. We’re just modifying the value of the $content string. This new function returns the modified value for the content (in our case, imagine it as being the content of your post with the code for the similar posts listing stuck in front.

Now all that is left to do is to tell WordPress to actually use that function at some point (plugins are usually a collection of functions, followed by a series of “hooks” which actually execute the functions at certain chosen moments). Here’s the action we’ll use:

add_action('the_content', 'sp_embed_similar_posts');

Try it!

This will also add the list of similar posts to the feed.

So, in summary, here is what we have done:

  • modified the template tag function so that it returns a value instead of printing it (in some plugins, you’ll find a function that already does that!)
  • created a function to stick that value on the beginning or end of a parameter, $content
  • add an action hook on the_content to execute the function.

Happy hacking!