This tutorial will walk you through the steps necessary to develop a very simple WordPress plugin, which can be used as a basis for future plugin development efforts.
1. Start with a clean installation of WordPress
Warning: You should never do plugin development with your live blog. Even a small programming error in your plugin can stop your site from functioning properly.
Install a separate copy of WordPress that is used only for development and experimenting. Follow the instructions in WordPress’s famous 5 minute install.
2. Locate the plugin directory and the plugin management screen
Find the root directory of your new WordPress install. WordPress plugins are kept in the wp-content/plugins directory. With a new install, there should be two plugins in the directory already: Akismet and Hello Dolly.
plugins $ ls akismet/ hello.php plugins $
Now log into your administration account and open the plugins menu by clicking in the left menu. On the plugins management screen, you’ll see the Akismet and Hello Dolly plugins listed.
WordPress monitors the wp-content/plugins directory. If we create a new plugin and drop it into this directory, WordPress will detect it.
3. Create a new plugin
While some plugins, like Akismet, are composed of many files, the simplest plugin is just a single PHP file. In fact, a WordPress plugin is just a PHP file with a special header.
Create a new file in the wp-content/plugins directory called sample.php, copy and paste the following text into the file, and save it.
<?php /* Plugin Name: Sample Plugin Plugin URI: http://geektastical.com/ Description: This is a simple, sample plugin. Author: A3 Version: 0.0.1 Author URI: http://geektastical.com */ ?>
Now, refresh your plugins management screen and the new plugin should appear.
Click the Activate Link to activate the plugin. Congratulations!
If you receive an error message, double check to ensure that you copied and pasted the header above exactly.
Tip: If your site breaks while doing plugin development, you can always fix it by deleting the plugin file or by moving it out of the wp-content/plugins directory. Once the incorrect plugin has been removed, WordPress should start working normally.
4. Adding functionality to your plugin
So you have a new plugin but it doesn’t do anything yet. The WordPress Function Reference details all the different hooks and calls you can make into the WordPress platform. In fact, there’s very little a plugin can’t do, but let’s focus on WordPress posts for now.
We’re going to modify our plugin to append a short HTML message to every post. Wherever on the site a full post appears, whether on the home page or on a post’s page, the HTML will be appended. This is useful functionality to start with, since many plugins append something to the tail of a post, such as related links or sharing buttons.
First, create two example posts that we will use to test our plugin.
Next, we must write a PHP function to append the HTML message to our post.
function geektastical_add_message_to_post( $content )
{
$new_content = $content . "<p>This text was added by our plugin!</p>";
return $new_content;
}
Think of this as a filter. Just before WordPress displays a post, it will call our function with the content of the post it’s about to display, and then display the result of our function call instead of the original content. We can do whatever we want to the content of the post before it’s displayed: prepending or appending HTML, replacing words, or even throwing all the content away and replacing it with something else entirely.
Our function above receives the content of the post, appends a short message, and returns the result.
Tip: All the functions we define in a plugin must have a unique name that’s different from every other function defined in WordPress or any function defined in any other plugin currently installed. It’s a good idea to give all your functions a suffix or prefix that will make them unique, like we do with geektastical_add_message_to_post.
Now, copy and paste the function to the sample.php plugin file and save the file.
<?php
/*
Plugin Name: Sample Plugin
Plugin URI: http://geektastical.com/
Description: This is a simple, sample plugin.
Author: A3
Version: 0.0.1
Author URI: http://geektastical.com
*/
function geektastical_add_message_to_post( $content )
{
$new_content = $content . "<p>This text was added by our plugin!</p>";
return $new_content;
}
?>
Reload the site’s home page to ensure everything is still working. If the site breaks, double check to ensure you copied and pasted correctly.
Now, check out the posts. Nothing has changed! That’s because there is still one more step.
5. Register our function with WordPress
We created our function, but we haven’t told WordPress that it should call it before displaying a post. We have to register our function by calling add_filter.
add_filter( "the_content", "geektastical_add_message_to_post", 10 );
The arguments are straightforward. the_content is a predefined label that tells WordPress to filter the content of posts. Next, we pass it our function name. The 10 is a priority. Since multiple plugins can register filters, WordPress has to decide in what order they should be run. The 10 is a low priority, encouraging WordPress to run all other filters before running ours. This way our message will appear at the bottom of the post, even if other plugins append things as well.
Copy and paste the add_filter call above into the sample.php and save the file.
Here’s the final plugin.
<?php
/*
Plugin Name: Sample Plugin
Plugin URI: http://geektastical.com/
Description: This is a simple, sample plugin.
Author: A3
Version: 0.0.1
Author URI: http://geektastical.com
*/
add_filter( "the_content", "geektastical_add_message_to_post", 10 );
function geektastical_add_message_to_post( $content )
{
$new_content = $content . "<p>This text was added by our plugin!</p>";
return $new_content;
}
?>
Now, reload the site’s home page and check out the posts.
Our message appears at the bottom of each post. Additionally, click on one of the posts to visit its page. Our message appears there as well. You’ve created your first WordPress plugin and learned how to edit a post’s content on the fly. Congratulations! You’re done.
Now that you’ve got a working plugin, start experimenting.
