Creating a Basic WordPress Plugin

This post includes some sample code, and web links for a presentation I put together for the Minneapolis/Saint Paul WordPress Users Group. The session is an introduction to creating a WordPress Plugin. This post is intended to be a place to find the resources and code used in the demonstration, but I will attempt to explain what it all means in this post.

The Purpose

This post is intended to be an introduction to the basic structure of a WordPress plugin. The plugin is, arguably, not extremely useful. But it does do something. So that has to count for something, right?

The purpose of a user group is to bring product users together to learn from each other. I’m not an expert in WordPress plugin development. So I would love to learn from you. If I missed something, or could say something better, feel free to leave a comment below!

The Problem

On our family blog, I posted a picture of our children, with their names.

The only problem was that my wife and I would rather not post their names online. Our preference is that we will refer to them as “Thing 1”, “Thing 2” and “Thing 3”.

The Solution
Now, I could try and remember to change their names every time I write a post. I suppose that wouldn’t be too difficult. However, as a true geek, I decided to find a way to automate it. I created a WordPress plugin that will change their names in each post.

WordPress plugins are an easy way to enhance, suppress or filter some of the basic WordPress functionality. It makes it fairly simple to customize the functionality, without editing the application itself.

Plugins are stored in the wp-content/plugins folder in your WordPress installation.

The Start

The first thing we do is create the plugin file. For this project, I created the PHP file:

wp-content/plugins/thing1.php


/*
Plugin Name: Thing 1
*/

That is the minimum amount of information needed to create a plugin. With that file created, I should be able to go the “Plugin” section of my WordPress dashboard, and see the plugin listed.

Sweet!

Now, let’s make something happen

Now that the plugin file has been created, we will add a simple PHP function to replace the girls’ names with the generic replacements:


function thing_1($text) {
$text = str_replace('Helga', 'Thing 1', $text);
$text = str_replace('Olga', 'Thing 2', $text);
$text = str_replace('Inga', 'Thing 3', $text);
return $text;
}

What we’ve done here is created a function called “thing_1” that will process the content it is sent ($text) and replace the names with the replacement words.

The next step is to attach this function to WordPress. We are going to do this with a hook the WordPress API has provided for plugin creation.

Hooks

There are two types of hooks in WordPress. Action hooks and Filter hooks.

Action hooks are used to add a function when WordPress “does something” (like sending an email or writing to the database)

Filter hooks are used to modify data before it is written to the database, or published to the browser.

There are a lot of hooks. I’m not going to get into them here, but here are some great links to learn more about the various hooks in WordPress:

• http://codex.wordpress.org/Plugin_API (a general guide to understanding how hooks work with the API)
• http://codex.wordpress.org/Plugin_API/Filter_Reference (a list of Filter hooks in WordPress)

For this project, we are going to use a “Filter Hook” to modify the post content before it is published to the browser. This will keep the names intact in the database, but will change them before it is displayed on the browser screen:

add_filter('the_content', 'thing_1');

This uses the WordPress function “add_filter” to add my function “thing_1” to the filter hook “the_content”. Essentially, it will take the contents of “the_content” and pass it through the function “thing_1”.

There are other arguments that can be passed to the “add_filter” function. For more information, visit this reference on the function.

Let’s take a look.

Now that we have created the plugin file, created a function, and assigned that function to a Filter Hook, I am going to activate the plugin and see how it impacts my site:

You can see now, that the plugin has replaced the names in the post. The only remaining issue is that the name “Helga” still shows up in the post title:

Let’s add one more filter to the plugin, to apply the same function (thing_1) to the post title.

add_filter('the_title', 'thing_1');

Here we are grabbing onto the Filter Hook “the_title” to apply the same function. Let’s take a look:

Perfect.

Now that the function works, I am going to add a few more lines to the comments at the top of the plugin file, to take a little credit for my work:

/*
Plugin Name: Thing 1
Plugin URI: http://www.carlbliss.com/?p=528
Description: Protects the identity of my daughters by changing their names to generic Dr. Seuss References
Author: Carl Bliss
Author URI: http://www.carlbliss.com
Version: 1.0b
*/

Those comments will add extra information to the plugin page in the dashboard.

And the process has now been automated!

Here is the completed plugin code (wp-content/plugins/thing_1.php)


/*
Plugin Name: Thing 1
Plugin URI: http://www.carlbliss.com/thing_1
Description: Protects the identity of my daughters by changing their names to generic Dr. Seuss References
Author: Carl Bliss
Author URI: http://www.carlbliss.com
Version: 1.0b
*/

function thing_1($text) {
$text = str_replace('Helga', 'Thing 1', $text);
$text = str_replace('Olga', 'Thing 2', $text);
$text = str_replace('Inga', 'Thing 3', $text);
return $text;
}

add_filter('the_content', 'thing_1');
add_filter('the_title', 'thing_1');

You can download the entire plugin file here: thing_1.php (ZIP)