This is a tutorial I’ve been developing for a presentation I will give in December. The sample plugin described here is available for download here: demo.zip. About 90% of what I’ve learned about WordPress plugin development comes from WordPress Plugin Development – Beginner’s Guide by Vladimir Prelovac. The other 90% has come from trial and error, searching the WordPress documentation, and seeking out other code examples around the web.
The sample plugin described below is loaded on this site, for purposes of example: webliberationnow.com (a domain I haven’t gotten around to developing otherwise). I’ll point to specific examples of how it is incorporated there as I go along.
By the way, Prelovac’s book does a great job of stepping through techniques in the context of practical examples. My examples are generally less practical, designed instead to give a quick tour through various techniques I have found useful.
In WordPress, a plugin is simply a PHP file loaded under the wp-content/plugins/ directory under the web root directory. Usually, each plugin has it’s own directory, so on my demo site the full path is /home/weblib/public_html/wp-content/plugins/demo/
Inside that directory is a file called demo.php that looks like this.
<?php
/*
Plugin Name: Demo by carrcommunications.com
Plugin URI: http://www.carrcommunications.com
Description: Demo of plugin programming techniques.
Author: David F. Carr
Version: 1.0
Author URI: http://carrcommunications.com/
*/
include WP_CONTENT_DIR."/plugins/demo/dashboard.php";
include WP_CONTENT_DIR."/plugins/demo/menu.php";
include WP_CONTENT_DIR."/plugins/demo/shortcode.php";
include WP_CONTENT_DIR."/plugins/demo/contact_form.php";
include WP_CONTENT_DIR."/plugins/demo/quote_post.php";
include WP_CONTENT_DIR."/plugins/demo/filter.php";
include WP_CONTENT_DIR."/plugins/demo/options.php";
include WP_CONTENT_DIR."/plugins/demo/load-jquery.php";
add_action('wp_footer', 'your_function');
function your_function() {
$content = '<p>This is a wp_footer action call.</p>';
echo $content;
}
?>
The comments at the top of the file are what makes it act as a plugin. The format is explained in the WordPress.org article on Writing a Plugin. As I understand it, the “Plugin Name:” comment is the only one that’s absolutely required. The rest of the tags inside the comment become more important if you are preparing your plugin for publication.
WordPress scans the plugin directory for php files containing this markup and makes them available on the Plugins administration page. Only the plugins that have been activated by an administrator are actually loaded at runtime.
I have this plugin set up to load a series of other files that illustrate various functions and effects. The only active function on display here is the one at the bottom labeled “your function” – an example taken straight from the WordPress documentation on how to use a function hooked to the wp_footer action call.
The WordPress application programming interface is built around a series of these hooks that allow you to trigger your own custom functions in response to the loading of pages or the posting of data.
The two main types of hooks are described in the Filter Reference and Action Reference sections of the WordPress API documentation. Essentially, the distinction is that filters are associated with modifying specific bits of content, whereas actions are associated with events, including events that occur before the page even loads.
If you write a function to act on the filter known as ‘the_content,’ for example, your function will take in the existing content of a post, act on it in some way, and then return it. A filter could translate the content of a post into Pig Latin, if that were your goal. There are similar filters for the post, date, title, and other associated content. Other filters intercept content on its way into the database when an administrator posts an update. Yet others alter database operations. If you wanted to change the sort order of posts on your blog page, you could use a ‘posts_orderby’ filter to modify the SQL query used to retrieve posts.
Another way your plugin can alter the behavior of WordPress is by detecting the occurrence of actions, which are events that take place as WordPress loads and displays a page.
For example, the ‘init’ action comes after the system has loaded all the plugins and created the $wpdb database object (which you will need for any queries or updates) but before the process of displaying a particular page. I often use ‘init’ to intercept a form post and then redirect the user to a different URL depending on whether or not the form submission validates properly. There is also an ‘admin_init’ function that only occurs on administration pages.
The ‘wp_head’ and ‘wp_footer’ actions are triggered by function calls embedded in a template file included with the current WordPress theme. This assumes that the theme follows the standard conventions for the placement of these functions; otherwise, the action will never get called.
In the example above, add_action('wp_footer', 'your_function'); is used to detect the wp_footer action and call a function that outputs a snippet of code.
Modifying the WordPress Administration Screens
The first thing you see when you log in to WordPress is an administrator’s dashboard, with the menus for editing posts, pages, links and so forth on the left. You can modify just about everything you’re seeing here if you know where to hook in your plugin.