WordPress Plugins

WordPress plugins allow you to extend the power of WordPress by adding code to the main program. They have to be formatted correctly before WordPress will recognise them and incorporate them onto its operations.

Full information about writing a WordPress Plugin can be found in the WordPress Codex.

Requirements

Plugin Folder

All themes must reside in a uniquely named sub-folder of the installation's /wp-content/plugins folder.

Plugin File

In the plugin's folder there must be a file with the same name part as the sub-folder.

For example if the plugin is called my_super_plugin then the folder and file structure should look like this…

   wp-content
     plugins
       my_super_plugin
         my_super_plugin.php

This file must have a specific header format from which WordPress can extract information about the plugin.

Header Format

The header of the plugin file needs to look like this…

/*
Plugin Name: The Name of the Plugin
Plugin URI: <where plugin can be found>
Description: A description of the plugin that will appear on the Appearance/Themes page of the WordPress control panel. This can be several lines long but can't contain any HTML formatting.
Author: The Author's Name
Version: a numeric version reference, e.g 0.1.2
License: The license under which the plugin is released. This is normally the GNU General Public License
License URI: <where the license can be found>
*/

Of these the only line that must exist is the Plugin Name:

License

It is a good idea to include the license in the style.css file. The format could be something line this…

/*

Copyright YEAR PLUGIN_AUTHOR_NAME (email : PLUGIN AUTHOR EMAIL)

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, version 2, as
published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/

The Code

Now you have got all that out of the way you can start wring the code of the plugin.

Hooks

To get the plugin to work it is necessary to tell WordPress when to run the code. This is done by specifying either the WordPress action that we want to attach our plugin to or which the part of the page text we want to filter though our plugin. This action uses WordPress hooks.

Hooks exist in two categories known as action hooks or filter hooks.

Action Hooks

Action hooks allow us to attach or code to various stages in the construction of the page. E.g. running the plugin when the HTTP header is being built uses the wp_headers hook or running it when the footer is being constructed would use the wp_footer hook.

More information about action hooks can be found in the WordPress Codex.

Filter Hooks

Filter hooks allow us to intercept the text being rendered by WordPress for specific parts of the page and carry out some action on it. For example you could change every occurrence of the text 'WordPress' and convert it to a colourful version like 'WordPress'.

Filters are added with the add_filter() function. The syntax is…

add_filter( <filter_hook_name>, <plugin_funtion_name>, <priority>, <number_of_arguments>);

  • <filter_hook_name> is the name of the filter we want to use
  • <plugin_function_name> is the name of the php function that carries does the work of our plugin
  • <priority> determines where in the list of things to be done at this time our plugin wants to be run. Low numbers have high priority. The default is 10 which puts our plugin towards the end of the queue
  • <number_of_arguments> tells WordPress how many arguments or parameters our function expects

More information about filter hooks can be found in the WordPress Codex.

Now lets write the plugin…

Plugin Example Explained

Here is an example of a simple plugin that displays s colourised version the WordPress when a particular code is found in the page content.

outline

What we want to do is read the page content and look for a particular string then convert that string into WordPress.

We need to look for a code instead of just looking for 'WordPress' so that we can have some control over where and where the conversion takes place; we may not want every occurrence being changed. I suggest we make the code [wordpress]. We need to use a filter and intercept the page content. The filter to use is the_content.

the code
/*
Plugin Name: Bluegoldfish WordPress-ize
Plugin URI: http://www.bluegoldfish.com/
Description: A plugin to change the text [wordpress] into an styled text version.
Version: 0.2
Author: Bluegoldfish
Author URI: http://www.bluegoldfish.com 
License: GPL
*/
/*
    Copyright 2013  Chris Morgan (Bluegoldfish)  (email : [email protected])

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License, version 2, as 
    published by the Free Software Foundation.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/

//\\//\\//\\ the section above is explained in style.css above //\\//\\//\\

// This is the add_filter() function in action...
//   - the_content is the filter we want. It holds the text in the body of the page
//   - wordpressize is the name of the function in our plugin that does the deed
//   - 10 sets our plugin to low priority
//   - 1 is the number of parameteres our function expects

add_filter('the_content', 'wordpressize', 10, 1);


// this is the working part of our plugin
//   - $content holds the page content passed in by add_filter()

function wordpressize($content){
	// look for the first occuance of the string ['wordpress]'
	$found_at = strpos($content, '[wordpress]');
	// if we have found [wordpress] go into this while loop
	while($found_at !== false){
		// start building the modified content by copying all the text up to the start
		// of the [wordpress] string
		$new_content = substr($content, 0, $found_at);
		// add on the HTML formatted version
		$new_content .= '<span style="font-family: Georgia, \'Times New Roman\', Times, serif; font-size: larger; font-weight: bold; "><span style="color:#21759B;">Word</span><span style="color:#000;">Press</span></span>';
		// copy the remainder of the content after the end on the [wordpress] string
		$new_content .= substr($content, $found_at + 11);
		// copy the new version over the old version
		$content = $new_content;
		// check again to see if there are any more occurrences of [wordpress]
		// and if so then enter the while loop again 
		$found_at = strpos($content, '[wordpress]');
	}
	// all occurrences of [wordpress] converted so return the new content to WordPress
	return $content;
}
where should it go?

   wp-content
     plugins
       wordpressize
         wordpressize.php