January 24, 2008

In the first of my Quick N Dirty plugin posts I showed you an example of modifying the content of a post just before it is displayed on screen. In this, the second of the Quick n’ Dirty plugins I am going to look at modifying the text of a post before it is saved to the database.

Yesterday’s plugin used a filter (the_content) to modify the content coming out of the database. The problem with this approach is that it needs to be calculated every time the page is loaded. This can slow down the loading process which in turn affects your readers. Especially if there are a number of plugins filtering the content one after the other.

For more fundamental content changes it is better to do it just once, and to do it where the only affected user is yourself.

Instead of a filter, this time the plugin will use an action: wp_insert_post. wp_insert_post is triggered whenever the post content is sent to the database. Importantly, it is triggered after the content is sent, so it isn’t enough to modify the content, the plugin also needs to update the database, or call a function that does it for us. Thankfully there is such a function so it is a simple process.

This action passes two variables to our function, the ID of the post, and a post object. The post object is quite a useful one to get to grips with as it is used wherever WordPress interacts with a post. You can also access it directly from within a theme (inside the loop). For now we will take this as a variable, modify the content portion of it, and pass it on to another function.

What this all means in real terms is that this plugin will be triggered whenever you save, save and continue, or publish a post. It will take your content and replace the terms such as -wp-, that you could use in your post to save time, with the full word, in the case the word is ‘WordPress&rsquo. You can see the replacements that will be made in the array within the plugin itself.

Here is the plugin:

[php]
/*
Plugin Name: Quick N Dirty Replacements
Plugin URI: [insert the plugin uri here]
Description: Alters pre-defined terms within your post when the post is saved
Author: Andrew Rickmann
Version: 1
Author URI: http://www.wp-fun.co.uk
*/

//call the action
//wp_insert_post is called for any post content update
//qnd_replacement is our function
//10 is the priority, 1 runs first, 10 last
//2 is the number of arguments we want.
//the default number of arguments is 1, just the ID.
add_action('wp_insert_post', 'qnd_replacement' , 10, 2 );

function qnd_replacement( $post_ID , $post = NULL ){

//check to see if we have post information
//if not then there is no point in continuing
if ($post == NULL) {return;}

//define an array to contain all our replacement values
$replacement_array = array();

//set the full text replacements
$replacement_array[] = array( '-css-' , 'Cascading Style Sheets');
$replacement_array[] = array( '-wp-' , 'WordPress');
$replacement_array[] = array( '-wpp-' , 'WordPress plugin');
$replacement_array[] = array( '-wpt-' , 'WordPress theme');

//set the abbreviation repacements
$replacement_array[] = array( '~css~' , 'CSS');
$replacement_array[] = array( '~html~' , 'HTML');

//set a variable to keep track of replacements
$replaced = 0;

foreach( $replacement_array as $replacement ){
//access the post_content and switch the terms
$post->post_content = str_replace( $replacement[0] , $replacement[1] , $post->post_content , $i );
//add the number of replacements carried out to the total
$replaced += $i;
}

//trigger an update but only do it if there have been replacements made
//wp_update_post will result in this action being triggered again
//if we don't check for replacements we will infinitly loop
if ( $replaced > 0) { wp_update_post($post); }
}

?>


Comparing it to yesterday’s plugin there are some noticeable differences in the first actual line of code. The first is that we are now dealing with an action, so we use the add_action command, instead of add_filter. The second is that there is an extra variable. This isn’t usually required. Most actions pass either no variables, or one variable. Most filters pass one variable. This particular action can pass either one or two variables. We want the second variable and so we need to tell the action to send us them both. That is what the last variable (the number 2) does.

If you miss this, and it is very easy, and common, to do, then you will get the post_id only. You can use the post_id to get the post object by using the command below, but it is easier to just get it passed as part of the function call.

[php]
$post = get_post($post_id);


The plugin is really just a simple string replacement that replaces strings such as -css- with the full text: Cascading Style Sheets, or ~css~ with css (note some browsers, IE *cough* don’t display this so don’t worry if you can’t see anything different).

An essential component is that the plugin counts the number of replacements. If some replacements have been made then the plugin will send the amended post object to the WordPress function wp_update_post($post); If no replacements have been made it will not send it. This is very important.

If you recall my explanation of when this action is fired, it is fired whenever post information is sent to the database. That means when we call the update function, sending the post information to the database, the action is called again. If we called it even when the were no replacements we would create an infinite loop which would end badly for all concerned. So, if there are replacements to made the plugin does run twice. But the second time it doesn’t really do very much.

There are ways to prevent it from running at all the second time but for the sake of simplicity I decided to just let it run twice. After all, it isn’t doing any harm.

Unlike yesterday’s plugin this one isn’t running on the blog. You wouldn’t notice the outcome of it, except that it would remove all the conditions ( -css- ) from the plugin code and the description.

Note: If you copy the content of this plugin you will need to replace all the quote marks as WordPress replaces them with fancy ones.