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

This tutorial will take you through the process of developing a simple jQuery input hint in an unobtrusive manner, allowing the form to function as expected when JavaScript is not enabled.

Step One

Before we start on the plug-in itself, we need some basic HTML defining our form.

<form method="get" action="">
	<input type="text" value="" title="Search..." name="s" id="s" />
	<input type="submit" value="Search" />
</form>

Step Two

The first stage of plug-in creation is setting up the basic plug-in structure. I tend to stick to the custom aliasing method as this will prevent conflicts with other libraries or frameworks and still allow us to make use of the “$” alias.

To achieve this, we execute an anonymous function, passing jQuery through and using “$” as the alias (although this could be any variable name), creating the fn and then enable chaining by looping through and returning each matched element.

(function($) {
	$.fn.inputHint = function() {
		return this.each(function() {
			//...
		});
	};
})(jQuery);

You can read more about plug-in authoring on the jQuery site.

Step Three

This plug-in is going to allow the default value to be defined by either passing it in as a set value or fetching the value from the title attribute of the input.

To achieve the first method we are going to use the extend method, allowing us to globally set and re-define the customisations such as the hint value to use.

Here we take the globally defined values from the $.fn.inputHint.settings object and over-ride them with any values passed in by the callerSettings object. (Although we are using a deep / recursive merge in the example, it’s not totally necessary for this plug-in in it’s current state.)

(function($) {
	$.fn.inputHint = function(callerSettings) {
		var settings = $.extend(true, {}, $.fn.inputHint.settings, callerSettings);
		return this.each(function() {
			//...
		});
	};
	$.fn.inputHint.settings = {
		value: false,
		className: false
	};
})(jQuery);

Step Four

Now that we can define any custom options, let’s move on to actually doing something useful.

We need the ability to set the value of the input to the predefined value if the input is empty and clear the default value when the input receives focus.

Setting the default value if the input is empty:

$(this).blur(function() {
	$(this).val($(this).val() == '' ? settings.value : $(this).val());
});

Clearing the default value  on focus:

$(this).focus(function() {
	$(this).val($(this).val() == settings.value ? '' : $(this).val());
});

If we added these two events to our plug-in directly, it would look as follows:

(function($) {
	$.fn.inputHint = function(callerSettings) {
		var settings = $.extend(true, {}, $.fn.inputHint.settings, callerSettings);
		return this.each(function() {
			$(this).blur(function() {
				$(this).val($(this).val() == '' ? settings.value : $(this).val());
			});
			$(this).focus(function() {
				$(this).val($(this).val() == settings.value ? '' : $(this).val());
			});
		});
	};
	$.fn.inputHint.settings = {
		value: false,
		className: false
	};
})(jQuery);

We should however make use the chaining ability to cut down the amount of code we need to write.

The following introduces a couple of additions to go alongside the chaining, including the triggering of the blur event that will fire when the page loads and set the default value if necessary.

Here we have also included the ability to take the default value from the title attribute instead of the settings array (see variable v).

$.fn.inputHint = function(callerSettings) {
	var settings = $.extend(true, {}, $.fn.inputHint.settings, callerSettings);
	return this.each(function() {
		var n = $(this), v = settings.value || $(this).attr('title');
		n.focus(function() {
			n.val(n.val() == v ? '' : n.val());
		})
		.blur(function() {
			n.val(n.val() == '' ? v : n.val());
		})
		.blur();
	});
};

Using what has been written so far will provide us with a working version, but there are a few additions.

We should unset the default value when the form is submitted, as most back end scripts will be checking against an empty value. This can be achieved by checking the existence of a parent form and unsetting the default value on submission by triggering the focus event.

The second addition is the ability to add and remove a class name to the input,  so we can set a style when the default value is present and a class name is defined (see addClass and removeClass).

Step Five: The Completed Plug-in:

(function($) {
	$.fn.inputHint = function(callerSettings) {
		var settings = $.extend(true, {}, $.fn.inputHint.settings, callerSettings);
		return this.each(function() {
			var n = $(this), v = settings.value || $(this).attr('title'), f = $(this.form);
			n.focus(function() {
				n.val(n.val() == v ? '' : n.val())
					.removeClass(settings.className);
			})
			.blur(function() {
				n.val(n.val() == '' ? v : n.val())
					.addClass(settings.className);
			})
			.blur();
			if (f) {
				f.submit(function(e) {
					n.trigger('focus');
				});
			}
		});
	};
	$.fn.inputHint.settings = {
		value: false,
		className: false
	};
})(jQuery);

To make the whole effect work, add either of the following snippets to your page or script.
The first will attempt to use the title attribute as there are no custom settings.

$(function() {
	$('#s').inputHint();
});

The second specifies a defined hint value and a class to add to the input when the hint is visible, which are passed through in the settings object.

$(function() {
	$('#s').inputHint({
		value: "Search",
		className: 'faded'
	});
});

You should place the plug-in inside a file called jquery.inputHint.js and include this file in your page, this conforms to the jQuery plug-in author guidelines (“Name your file jquery.[insert name of plugin].js”).

Additional Notes

This is just one method of achieving an input hint, an alternative method would be to use the the label tag instead of input and set the hint value based on this, or even place the label tag itself on top of the input.