Writting your first WordPress plugin

Wordpress is a highly used and easily customizable platform for content creation and management. In this post I’ll guide you through the basic structure and steps required to create a simple and useful wordpress plugin.

The first step is to define the plugin header that wordpres uses to determine which files it should include in the plugin list:

1
2
3
4
5
6
7
8
9

<?php
/*
Plugin Name: wp-Octave
Plugin URI: http://www.bgoncalves.com/notes/2007/05/21/wp-octave-bringing-the-power-of-octaves-plotting-capabilities-to-wordpress/
Description: Easily include Octave's output in WordPress posts.
Version: 1.0
Author: Bruno Goncalves
Author URI: http://www.bgoncalves.com/
*/

Here we define the plugin name, version and a brief decription as well as some information about the author and the URI where the latest version can be downloaded.

Wordpress runs each post contents through various filters before actually displaying the end result to the user, with each filter modifying the content in some way. Most plugins simply declare new filters that allow them to add all sorts of functionality to wp. This is done with a line of the form:

174

add_filter('the_content','octaveFilter',1);

that simply tells wordpress to filter “the_content” through the function “octaveFilter”. The number “1″ tells wp that this plugin wants to have priority 1, that it wants to run before any other plugins.

In this simple example, the function “octaveFilter” will just go through the content, pick out the parts in between consecutive “[octave]”, “[/octave]” tags and send them to a new function to be processed. A new version of the content is then created where those pieces were replaced by the some useful html code. The filtered content is then returned back to wordpress. A basic implementation of this function would be:

101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

function octaveFilter($content) 
{
    $start=0;
    $newcontent=$content;
 
	while(($start=strpos(strtolower($content), '[octave]',$start))!==false)
    {	
		$end=strpos(strtolower($content),'[/octave]',$start);
 
	    if($end===false)
	       break;
 
		$start=$start+8;
		$data=substr ($content,$start, $end-$start);
 
		$result=octaveRun($data);
 
		$newcontent=str_replace('[octave]'.$data.'[/octave]',$result,$newcontent);
		$start=$end+9;
    }
 
	return $newcontent;
}

where we just use simple string functions to pick out the pieces we are interested in. Much more functionality (and complexity) could be added by using Regular Expressions to perform the matchings.

Now that we have the basic functionality of our plugin implemented (with the gory details hiding inside “octaveRun”) it’s time to make it more user friendly by adding an options page, using:

181

add_action('admin_menu', 'octaveGetOptionsPage');

where we tell wordpress to call the “octaveGetOptionsPage” function whenever a user goes to the administration menu. In turn, this function:

35
36
37

function octaveGetOptionsPage() {
       add_options_page('wp-Octave', 'wp-Octave', 8, __FILE__, 'octaveOptionsPage');
}

explains to wordpress where to find the function that implements the options page functionality, that it should only be visible to users of level 8 or above and that the name of the new options pane is “wp-Octave”. The function “octaveOptionsPage” is responsible for outputting the options form and updating the options according to the user input using wordpress’s built in options “API”. This “API” has two basic functions, “update_option” that updates the value stored in wordpress db (or adds it if it doesn’t exist already) and “get_option” that just retrieves the value stored. The syntax for “update_option” is a simple as it gets:

45

update_option('octaveBin',$_POST["octaveBin"]);

it just assigns the value received by the form to an option identified by the string in the first argument.

Unsurprisingly, the syntax for “get_option ” is even simpler, requiring just the option’s name:

11

$octaveBin=get_option('octaveBin');

With just this rudimentary understanding of the wordpress plugin API and some knowledge of php, you should now be able to contribute a useful plugin to wordpress’s community. You can download the complete (and fully functional) plugin file below by just right clicking the link and please leave any questions or suggestions you might have in the comments area.