As this is the first of the Quick N Dirty plugin posts I’m going to explain the basic principles of WordPress plugins before getting to the plugin itself.
So what is a plugin?
At its most basic a WordPress plugin is just a PHP function that is called by WordPress during a specified process. As the plugin writer, you tell WordPress when you want your function to be called by adding your function to a list attached to one of a series of hooks. When WordPress gets to the point in the process that the hook applies to it will run all the functions in that list.
There are two types of hook: actions and filters.
Actions call the functions in the list without passing any data and without expecting any back. Often these are used to add content to the page in some way such as adding a copyright notice in the footer.
Filters are more involved. Filters pass data to the function and require that data, or an amended version, to be sent back. Filters are usually part of a data handling process such as outputing the content of a post to the screen.
For the first quick n’ dirty plugin I am going to use a filter: the_content.
This filter runs as part of the, the_content, template tag. When the tag is used in the template WordPress retrieves the content of the post, passes it through the filters that have hooked into the process, and then outputs it to screen. This means we can add anything we want, or amend anything we want, to the content of each post without altering the information in the database.
The fully commented plugin is included below. The plugin takes the content, retrieves all the links, checks ( using get_bloginfo ) it to see if the link points to my blog, or not, and then adds the links to the end of the post.
<?php
/*
Plugin Name: Quick N Dirty End of Post Links
Plugin URI: http://www.wp-fun.co.uk/2008/01/23/quick-n-dirty-links/
Description: Captures all the links within a post and lists them all at the end of the content.
Author: Andrew Rickmann
Version: 1
Author URI: http://www.wp-fun.co.uk
*/
//This is the line that adds your filter into the list.
// 'the_content' is the name of the filter
// 'qnd_end_of_post_links' is the name of the function, below
// 1 is the priority, 1 is called first, 10 last.
add_filter('the_content', 'qnd_end_of_post_links' , 1 );
//WordPress will call this function
//$content is the full content of the post
function qnd_end_of_post_links( $content ){
//a very basic regular expression to get the links
$regexlink = '/<a href="[^<]*<\/a>/i';
//apply the regular exporess, the links that match are saved in $matches
preg_match_all( $regexlink , $content , $matches );
//create a string to contain the internal and external links
$internal = '';
$external = '';
//loop through all the matching links
foreach( $matches[0] as $match ) {
//check if the link is pointing at our blog url, if so add to the internal string
if ( strpos( $match , get_bloginfo('wpurl') ) !== false ) {
$internal .= ' - ' . $match;
} else {
$external .= ' - ' . $match;
}
}
//only add the header to each list if there are links in the list
if ( strlen($internal) != 0 ) { $internal = '<h3>Links to my blog</h3>' . $internal; }
if ( strlen($external) != 0 ) { $external = '<h3>Links to other blogs</h3>' . $external; }
// !!important, filters must return the value or the post will be empty
return $content . $internal . $external;
}
?>
It is absolutely essential that the function you create has a unique name. If it is the same as any other function in WordPress then it will trigger an error. Plugin authors will always wrap their functions in classes to avoid this; however, for very simple plugins on your own blog, this isn’t really necessary.
This plugin is running on this blog right now. The next two headers and lists are the result of the plugin.
Note: If you copy the content of this plugin you will need to replace all the quote marks as WordPress replaces them with fancy ones.
Writing a plugin can seem daunting if you have never done it before. There are so many great plugins out there that it often seems as though there are no topics left to cover, but plugins really don’t need to be fully featured, publicly released, solutions. You can do a lot with your own blog by developing relatively quick plugins. I want to encourage everyone who hosts their own WordPress blog to write a plugin no matter how small, just for themselves. That is the point of this series.
Each weekday for the next ten days I will be publishing a very short, quick, sample plugin. It won’t be available to download, but the code on the blog will be complete.
The name of the series is Quick n’ Dirty for a reason. These won’t bother with classes, objects, options, admin pages, databases (well maybe a little in the later ones) or that kind of malarkey, just one file, one hook, one function. This is a series for beginners, so just get stuck in.
To encourage things along a little I want to give some publicity to anyone that takes part in QuADFuN (quick and dirty fortnight), as the kids are calling it, so if you write your own quick and dirty plugin for your blog in the next two weeks, whether or not you use one of the examples, and publish a post about the code then come back to this post and explain what you did and I’ll add your name to a list on this page.
I’m also here to help with problems that come up when you are writing them, I am open to suggestions for quick and dirty plugins (I have only thought of four), and I’m open to guest entries, just drop me a note from the contact form.
I am convinced that you can do a lot with very little time or effort once you know of a few hooks and uses. I hope there is a demand to learn, and if there is I am here to help.
The first post will be tomorrow; you’ve been warned!!
Quick n’ Dirty Plugin Posts
List the posts links at the bottom of the post
Replace text in your post each time you save the post.
Prevent posts appearing on the home page.
Add a footer to the end of each post in your RSS feed.
Use WordPress’s Blogroll functionality to create a controllable navigation scheme with links for both casual visitors and registered users.
Theme your WordPress admin login page quickly and easily.
Build a page to report statistics using Google Charts.
Use random forms to thwart spambots.
Connect your blogs together by sending category requests to that category on your other blog.
Show visitors that your blog is offline while you tinker like a mad inventor.
In part 2 of the series I looked at the way objects can be used to separate the repetitive logic from the core code of the plugin itself by demonstrating an object based text box. In this part I’m going to take it one further and show how several objects can be derived from a common class to prevent repetition of code in the objects themselves.
I ended part 2 with two classes: A text box class that handled display of a textbox as well as getting and setting its value when the form is loaded or submitted, and the class used for the plugin itself that created an admin page and added three textboxes.
In this part I am going to create two more classes. The first is a generic form control class. Into this I am going to put the initial declaration of the necessary variables, and the value getting and setting code from the text box class.
This is the full text box class from part 2:
//note this example does not perform any validation.
class my_text_box
{
var $prefix = 'my_text_box_';
var $name = '';
var $value = '';
var $description = '';
//php 4 constructor
function my_text_box( $name , $description ) {
$this->name = $name;
$this->description = $description;
if ( $v = get_option( $this->prefix . $this->name ) ) {
$this->value = $v;
}
if ( isset( $_POST[$this->prefix . $this->name] ) ) {
$this->value = $_POST[$this->prefix . $this->name];
update_option( $this->prefix . $this->name , $this->value );
}
}
function display() {
echo '<p>';
echo '<label for="'.$this->prefix . $this->name.'">'.$this->description.'</label>';
echo '<input type="text" name="'.$this->prefix . $this->name.'" value="'.$this->value.'" />';
echo '</p>';
}
}
The new class, is a generic class that doesn’t display anything, but does handle the values. You can see the sections of the code that have been removed from the textbox class by comparing the two classes.
In the generic class the value getting and setting code is no longer part of the constructor, so it will need to be called explicitly. Also note I have amended the prefix from my_text_box to the more generic my_form_control.
class my_form_control{
var $prefix = 'my_form_control_';
var $name = '';
var $value = '';
var $description = '';
function get_value( ) {
if ( $v = get_option( $this->prefix . $this->name ) ) {
$this->value = $v;
}
if ( isset( $_POST[$this->prefix . $this->name] ) ) {
$this->value = $_POST[$this->prefix . $this->name];
update_option( $this->prefix . $this->name , $this->value );
}
}
}
Now, this is the important part. Having moved some of the code into a generic class we need to rewrite the textbox class, and we do this by using the ‘extends’ keyword.
class my_text_box extends my_form_control
{
//php 4 constructor
function my_text_box( $name , $description ) {
$this->name = $name;
$this->description = $description;
$this->get_value();
}
function display() {
echo '<p>';
echo '<label for="'.$this->prefix . $this->name.'">'.$this->description.'</label>';
echo '<input type="text" name="'.$this->prefix . $this->name.'" value="'.$this->value.'" />';
echo '</p>';
}
}
The ‘extends’ keyword, used in the class title tells PHP that our class should inherit everything that is in the generic class, so although the my_text_box class is now much shorter than it was it actually has exactly the same functionality.
As well as moving the code into the generic class there is one more change; the constructor of the text box class now calls the get_value function. Note that we can still use the $this keyword to access it, even though it is contained within the generic class we have extended.
The benefit of this is that we can now create a second type of form control which will differ in only one way, it will output slightly different html, and we don’t need to recreate the code that gets and sets the value.
class my_text_area extends my_form_control
{
//php 4 constructor
function my_text_area ( $name , $description ) {
$this->name = $name;
$this->description = $description;
$this->get_value();
}
function display() {
echo '<p>';
echo '<label for="'.$this->prefix . $this->name.'">'.$this->description.'</label>';
echo '<textarea name="'.$this->prefix . $this->name.'">'.$this->value.'</textarea>';
echo '</p>';
}
}
This new class works in exactly the same way as the text box class, except that it outputs the html for a textarea, instead of a text box. It extends the base class, uses the same method of getting and setting the value. Already, extending the generic class has saved 10 lines of code that would have been identical to each other. If we were to create a third class, for example, a drop down box, then we would have saved twenty lines of code. Add that the fact that if you find a flaw you only need to amend it once, and the saving made by using objects instead of hardcoding the html into the admin page and you start to see how beneficial using objects can be.
Finally, there is one more change that is needed. We need to amend the actual admin page itself to use a text area as well as a text box. To do this we change only one line from the admin page in part 2:
$option2 = new my_text_box( 'Option_2' , 'Second Option');
We change this to:
$option2 = new my_text_area( 'Option_2' , 'Second Option');
So the final admin page class looks like this:
class my_plugin
{
//PHP 4 style constructor
function my_plugin(){
add_action( 'admin_menu' , array(&$this , 'add_admin_menu') );
}
function add_admin_menu(){
add_options_page('My Plugin Options', 'My Plugin Options', 9, basename(__FILE__), array(&$this, 'admin_page'));
}
function admin_page(){
$option1 = new my_text_box( 'Option_1' , 'First Option');
$option2 = new my_text_area( 'Option_2' , 'Second Option');
$option3 = new my_text_box( 'Option_3' , 'Third Option');
?>
<div class="wrap">
<h2>My Admin Page</h2>
<form method="post">
<p>
<?php $option1->display(); ?>
</p>
<p>
<?php $option2->display(); ?>
</p>
<p>
<?php $option3->display(); ?>
</p>
<p>
<input type="submit" name="submit_my_plugin_options" value="Submit" />
</p>
</form>
</div>
<?php
}
}
$my_plugin = new my_plugin();
We’ve made a significant change to the admin page by changing only one word of the actual page content itself.
You can download the finish plugin here: just remove the .txt from the end of it.
In this part I have demonstrated how you can extend generic classes that encapsulate regularly used functions to create multiple classes with similar functionality without repeating the same code, potentially saving a significant amount of identical code and making the code more maintainable at the same time. In the final part I will look at ways of storing collections of objects in order to remove even the admin page code itself from the core plugin files.