SixCrayons

Over the past few months I’ve found myself working on a number of WordPress powered projects and as a result of this have ended up writing a number of plugins to solve some of the problems I had encountered.

In order to keep each plugin standardised and at the same time speed up the development process, I decided to create a plugin template containing some the features commonly used. After de-constructing my existing plugins it was clear that one of the most common features was the inclusion of a settings page, so have included that in the template.

Introduction

If you haven’t glanced your eyes over the WordPress Codex yet, it’s recommend you start by taking a look at it’s introduction to Writing a Plugin. It outlines all the basic principles and practices of plugin development as well as linking to some other useful resources.

The Template

The template assumes we are writing a plugin called “MyPlugin“, which does absolutely nothing (that’s your task for later) and is stored a directory called “myplugin” in the plugins folder (/wp-content/plugins/).

In this directory there are three files – index.php, readme.txt and settings.php.

It’s recommended that you download the files first and take a look, however the following brief description should prove some insight into what’s there.

readme.txt

If you want to host your Plugin on http://wordpress.org/extend/plugins/, you need a readme.txt file which contains details about the plugin, who it was written by, current version etc.

=== MyPlugin ===
Contributors: Steve Whiteley
Tags: my, plugin, template
Requires at least: 2.8.2
Tested up to: 2.9
Stable tag: 0.1
 
A short description of my plugin.
 
== Description ==
 
A longer description outlining some of the major features.
 
...

index.php

If you open up index.php you will you see the core functionality of the plugin, the following will attempt to break it down a little and explain what it going on.

The first thing you will see are the comments at the top of the file:

/*
Plugin Name: MyPlugin
Plugin URI: http://wordpress.org/extend/plugins/myplugin/
Description: A short description of the plugin that is displayed on the plugins overview page.
Version: 0.1
Author: SixCrayons
Author URI: http://sixcrayons.com
*/

WordPress will use the details provided here when displaying the plugin within the admin panel.

Our plugin template is going to use a class based structure, my main reason behind this is that it provides a namespace for your functions and allowing for shorter function names and prevention of conflicts.

We are now going to begin writing our class, but first ensuring that there are no classes with the same name in existence:

if (!class_exists('MyPlugin')) {
	class MyPlugin {
		var $name = 'MyPlugin'; // The name of your plugin used for display purposes.
		var $tag = 'myplugin'; // This should be the same value as the plugin directory.
		var $options = array(); // Will hold any settings the plugin has saved.
		function MyPlugin()
		{
			// Fetch any stored plugin options/settings...
			if ($options = get_option($this->tag)) {
				$this->options = $options;
			}
			...
		}
	}
	$myPlugin = new MyPlugin(); // Instantiates the plugin
}

This is pretty much all we need to get the plugin appearing on the plugins list of the admin area, but we really want to add at least a small bit of functionality. Because this template assumes we are using a settings page, we want to make the settings as easy to get to as possible.

This can be done in two ways, adding a link under the plugins side menu and appending a link to the the plugin description on the plugins list. To do this we require two different hooks (admin_menu and plugin_row_meta) which we will add to out class initialisation function.

function MyPlugin()
{
	if ($options = get_option($this->tag)) {
	...
	}
	if (is_admin()) { // Only if we are currently in the admin panel should we add these hooks...
		add_action('admin_menu', array(&$this, 'admin_menu'));
		add_filter('plugin_row_meta', array(&$this, 'plugin_row_meta'), 10, 2);
		...
	}
}
function admin_menu()
{
	// Add a link to the settings page under "Plugins" on the sidebar menu...
	add_submenu_page(
		'plugins.php',
		'Manage '.$this->name,
		$this->name,
		'administrator',
		$this->tag,
		array(&$this, 'settings')
	);
}
function settings()
{
	// Include the settings page when we click on a settings link...
	include_once('settings.php');
}
function plugin_row_meta($links, $file)
{
	// Append a link the after the author URL on plugins list page...
	$plugin = plugin_basename(__FILE__);
	if ($file == $plugin) {
		return array_merge(
			$links,
			array(sprintf(
				'<a href="plugins.php?page=%s">%s</a>',
				$this->tag, __('Settings')
			))
		);
	}
	return $links;
}

We now have two links in place which take you through to the settings page (settings.php). The example contains two options (“Option One” and “Option Two“) and uses the same template found elsewhere on the default settings pages.

settings.php

It also includes a message that is displayed when the settings have been saved.

A settings page requires the settings to be registered by calling register_setting and output settings_fields within the settings page form. Additionally the settings can be validated, but this step has not been included in the template.

The template also stores all the settings in a single options field, helping to keep the footprint of the plugin to a minimum.

Summary

I’d like to round this one off by saying this is certainly not the be all and end all of writing a plugin, however I do find it very useful to have all my plugins in a similar structure. The Plugin API still requires completion in some areas and finding the right hooks and filters can often take some effort, so hopefully this will help save you a fair amount of time.

If you can recommend any “best practices” for plugin development or have your own style then your ideas and feedback are very welcome :).

Download the WordPress Plugin Template