Social Bookmarking with WordPress Plugin Part III: WordPress plugin hooks

• 23 April 2009
• in: WordPress Resources

Our plugin now works fine, but there is a problem. In order to use it, we also have to edit the theme. This can be a real pain for all sorts of reasons:

• If you want to change to a different theme, the plugin will stop working until you edit the new theme.
• If you want to distribute your plugin to other people, they can’t just install it and activate it; they have to change their theme files too.
• If you change the function name, you need to alter the theme files again.

We need some way to make the plugin work on its own, without the users having to change their themes or anything else.

Hooks come to the rescue, making it possible to display our Digg This button in our posts—without ever modifying our theme.

Time for Action – Use a filter hook

We will use the the_content filter hook to automatically add our Digg This link to the end of the post content. This will avoid the need for the users to edit their theme files if they want to use our plugin.

1. Create a function that we will use to hook to the content filter:
   

   // create a Digg link and return it
   return ‘<a href=”http://digg.com/submit?url=’.$link.’&amp;
   title=’.$title.’&amp;bodytext=’.$text.'”>Digg This</a>’;
   }
   <b>/* Add Digg link to the end of the post */
   function WPDiggThis_ContentFilter($content)
   {
   return $content.WPDiggThis_Link();
   }</b>

2. Use the post content hook to automatically call our new function:
   

   add_filter(‘the_content’, ‘WPDiggThis_ContentFilter’);

3. Remove the references to our function from the theme template as we no longer need them. Leaving them would have the effect of showing the link twice.

The end result is now the same, but we now control the appearance of the link directly from our plugin.

What just happened?

When we activate our plugin now, WordPress comes across and runs this line:

add_filter(‘the_content’, ‘WPDiggThis_ContentFilter’);

This tells WordPress that every time it’s going to display the content of a post or page, it should run it through our WPDiggThis_ContentFilter() function. We don’t need to modify the theme file anymore – WordPress will make sure that the function runs at the required time.

When we load a post now, WordPress will automatically call our function:

/* Add Digg link to the end of the post */
function WPDiggThis_ContentFilter($content)
{
<b>return $content.WPDiggThis_Link();</b>
}

This function receives the post’s content as a parameter, and returns the filtered content. In this case, our Digg link gets automatically appended to the end of the content.

WordPress hooks

WordPress provides a powerful mechanism for plugin functions to be called at the exact time when we need them. This functionality is accomplished by using the so called hooks.

Every time you call a page from your browser, the WordPress engine goes through every possible function it needs to render the requested page. Somewhere along the way, you can “hook” up your function and use it to affect the end result.

You do this by simply registering your function with a specified hook, allowing it to be called by WordPress at the right moment.

There are two types of WordPress hooks:

• Action hooks: These are triggered by WordPress events, for example, when someone creates a post or writes a comment.
• Filter hooks: These are used to modify WordPress content on the fly, like title or content of the post as it is being served to the user.

Filter hooks

We learned that filter hooks (also referred to as simply ‘filters’) are functions that process WordPress content, whether it is about to be saved in the database or displayed in the user’s browser. WordPress expects these functions to modify the content they get and return it.

In our case, we used the_content filter hook to modify the post content by appending a Digg link to it. We could also have placed the Digg link at the beginning of the post, or broken up the post and put it in the middle.

To set up a filter, we need to use the add_filter function:

add_filter ( ‘filter_hook’, ‘filter_function_name’ , [priority],
[accepted_args] );

• filter_hook: One of the filter hooks provided by WordPress.
• filter_function_name: A function used to process the content provided by the filter_hook.
• priority: An optional parameter, which specifies the execution order of functions. The default value is 10 if several functions apply to the same filter hook, functions with a lower priority number execute first, while the functions with the same priority will execute in the order in which they were added to the filter.
• accepted_args: An optional parameter, which specifies how many arguments your function can accept. The default value is 1. The accepted_args parameter is used for hooks that pass more than one argument.

Here is an example list of filter hooks, which will help you to get a better understanding of what you can achieve using them.