Turing tarpit

One of the really cool things about WordPress is that extending its functionality is a breeze. Think up a new feature and more often-than-not, someone has already written a plugin for it. With plugin installation now possible within the admin panel – things couldn’t be easier. You can search for, download, install and upgrade plugins without leaving the browser. Gone are the days of downloading, unzipping and messing with the command line on a remote server.

So, why did I end up writing a WordPress plugin? It all began with choosing a theme ….

Choosing a magazine style theme

I wanted to use a magazine style theme for this blog. I use K2 for all my other WordPress blogs and have been quite happy with it. However, the visual dazzle of recent magazine style themes left K2 a little wanting. Besides, most of K2s unique features like widget control were now standard in WordPress. I was impressed by the Hamasaki theme, developed by Nurudin Jauhari, on Aral Balkan’s blog. However, the elements were a little too large for my taste and the prominent place given to the most recent post was not to my liking. In contrast, Jauhari had another magazine style theme called hijiriah (demo) that I took a liking to instantly.

There are some excellent features in this theme. The money features for me were:

• Built-in ad support ( a nice way to link to my other resources ).
• Dynamic hierarchical navigation menu based on categories ( structured  access to eclectic subject matter ).
• Auto generated image for each post ( pain free way to add some visual interest to the blog page ).

Auto generating an image for each post

I must say that this is the singular feature that really sold me on this theme. Images are generated automatically using a custom version of the Get the Image plugin developed by Justin Tadlock. This plugin is like a cascading image seeker. It also degrades gracefully. The following image seeking sequence is from the plugin README file.

1. Looks for an image by custom field.
2. If no image is found, it grabs an image attached to your post.
3. If no image is attached, it can extract an image from your post content.
4. If no image is found at this point, it will default to an image you set.

The Get the Image plugin has a function called get-the-image that returns the image element ( img tag ) for the auto generated image. A feature that is lacking is flexible image sizing ( you can only choose from predetermined sizes ).  To scale the image to a custom size, the hijriah theme uses an image resizing script called timthumb. This is the whole reason for customizing/hacking the plugin.

The custom version of Get the Image that shipped with hijriah was based on version 0.3. The customization was a simple hack to add an additional function to the plugin called get-the-link that returned the URL of the chosen image for the post ( as opposed to the whole image element ). For some reason, a similar function that existed in Get the Image was now deprecated (probably due to a very good reason unknown to me). The URL to the image chosen by the hacked Get the Image plugin was passed to the timthumb script for resizing and eventually displayed on the blog page.

Another issue was that version 0.3 of  Get the Image had a bug that prevented it from returning an image specified by a custom thumbnail field. Version 0.3.1 fixed this issue.

Upgrading plugins broke image auto generation

Of course, upgrading the Get the Image plugin to 0.3.1 overwrote the hacked version and the hijriah theme was left without an implementation for the template tag get-the-link.

Modifying the code in the hijriah theme ( I was using a child theme ) to substitute get-the-link tag with the get_the_image tag seemed a little too complicated due to the resizing issue. The other option was to write a new plugin that implemented the get-the-link function.

This was a beginning of my sojourn into plugin development…

Writing a plugin to implement the get-the-link template tag

Template tags are used within WordPress theme templates to display information dynamically. It is really nothing more than a call to a function internal to WordPress or externally implemented in a plugin or functions.php file. In the case of the hijriah theme, the get-the-link tag is required in the index.php template file.

The purpose of the new plugin clear and simple. Implement the get-the-link function by calling the get_the_image function in the  Get the Image plugin. I just have to use regex to extract the src attribute from the image element and return it. Simple right? Well, there were a few important things that I had to learn first.

Important stuff about plugins

This is my first attempt at writing a plugin for WordPress. I had to dispel some preconceived ideas.

It’s been awhile since I did any coding in PHP. Coming from my recent ActionScript 3 background and dabbling extensively in OOP and design patterns I thought the new plugin could simply extend the  Get the Image plugin class and override a method or two. But, noooo! I quickly realized what I was up against as my PHP started to come back.

WordPress has a nice modular architecture, but it is not modular in the OOP sense. Here is the definition of a plugin from the WordPress Codex.

A WordPress Plugin is a program, or a set of one or more functions, written in the PHP scripting language, that adds a specific set of features or services to the WordPress weblog, which can be seamlessly integrated with the weblog using access points and methods provided by the WordPress Plugin Application Program Interface (API).

Forget about looking for a class to extend. All the plugins I looked at were collections of functions. Here are some things I learned about WordPress plugins that may be useful for a newbie like myself.

The bar to entry is very low

It was surprising how easy it was to get WordPress to recognize a new plugin. This is a testament to the simplicity of the plugin architecture in WordPress. All you need is to create a new PHP file inside the plugins folder in your WordPress installation and write a comment block on it. Although not a requirement, it is always a good idea to put your plugin files inside a folder. The comment is the plugin information header.

You can now go into the WordPress admin panel and activate it (from the inactive plugins list). You will now see the plugin activated. Of course it doesn’t do anything, but that was incredibly easy!

Activate the plugin from the Admin Panel

Plugins are just a collection of functions

The best way to learn how to write a plugin is by studying other plugins. Good starting point are akismet and the hello dolly plugins that are included in the default installation. You will quickly see that most plugins have no class definitions, but they are just a collection of functions.

Plugins can take two forms:

1. Plugin as a library.
2. Plugin as a dependency injector.

1. Plugin as library

This is the simplest form of a plugin. A library is simply a collection of functions. The client, a WordPress template in this case, can call the functions. Each function call does some work and returns control to the client.

Template tags are calls to WordPress functions that do something or return some value back to a template. For example,  the bloginfo template tag is a function implemented within WordPress and returns information about the blog based on passed parameters. The ‘name‘ parameter, shown below,  returns the name of the blog.

bloginfo('name');

Custom template tags can be implemented in plugins. This is a super easy way to extend WordPress functionality. All you need to do is implement a function in your plugin with the name of a template tag you come up with (make sure it is unique – more on this later). The following figure shows the index.php template calling the get-the-image template tag. The get-the-image function is implemented in the Get the Image plugin.

2. Plugin as dependency injector

This is a more powerful method of extending the functionality of WordPress. Instead of waiting for the template to call the plugin function, the plugin injects the function into the template. Dependency injection using plugins is called hooks in WordPress. There are two types of functions that can be injected or hooked into wordpress: Actions and Filters.

Action functions can be hooked into specific events in WordPress. That means, the function is called or triggered by a specific WordPress event. For example, you can write an action function that informs different search engines when a new article is posted. The  plugin function will hook into the publish_post event. The events that can trigger an action function are numerous. Refer to the Plugin API/Action Reference for the list.

Filter functions can be hooked into WordPress  to pass content through the function before being output to the web page. For example, if you want to filter out profanity in comments, write a function that takes the comment text as a parameter and returns the clean content. Now you can hook this filter function to the comment_text filter hook so that it is called before comment text is published on the page. Refer to the Plugin API/Filter Reference for the list of filter hooks.

I won’t go into detail on writing plugins as dependency injectors. The plugin API documentation provides a good introduction. A good example on how to write action functions is to take a look at the hello dolly plugin. The book on WordPress Plugin Development by Vladimir Prevolac is quite good and explains action and filter functions very well ( check out the sample chapter ). Above all, download some plugins and take a look at the code – you will learn some interesting techniques.

Choose plugin and function names carefully

Make sure you use a unique name for your plugin and its function names. PHP  and WordPress don’t take kindly to duplicate function names. The plugin will just not load and you will be left wondering what happened. Searching the WordPress plugin directory before settling on a name is not a bad idea. The dash ‘-’ is the recommended separator for words in the filenames and function names for plugins.

Make sure the plugin function exists before you call it

This is also known as:

Looking for a black cat in a dark alley that isn’t there

This is most important for library type plugins that are called directly from templates. The template doesn’t know if the plugin exists or if it is activated. Therefore, it is a good idea to first check if the function is available before calling it from a template. The PHP statement in the template should be of the form:

if( function_exists('get-the-image') ) { get-the-image(); }

The tag function  ’get-the-link‘ will only be called if it exists. There is a tight coupling between the template tag and the plugin where the function is implemented. You need to manually add the tag to the new theme templates if you switch themes.

One of the big advantages of injector type plugins is that the hooks are created at runtime. The template files don’t have to be modified to call the functions. In fact, the template doesn’t know anything about the plugins or the hooks. Therefore, themes can be switched without requiring any changes in the template files.

Get the Image Link plugin

Let’s get back to the issue at hand. The purpose of the new plugin is to implement the get-the-link template tag by calling the get_the_image function in the  Get the Image plugin. We need to return the URL of the image as opposed to the image element.

It is a good idea to take a look at the README file for the Get the Image plugin before proceeding. First thing to note is that the function takes query string style parameters (as opposed to function style parameters). Query string style is desirable when a function has many parameters. The second issue to note is the ‘echo’ parameter which is set to true by default. This causes the function to echo the image element text to the output buffer inside the function. We need to set this to false.

The plugin will consist of one function called get-the-link that calls get-the-image in the Get the Image plugin. It then parses the image element to extract the src attribute using regexp and returns it.

function get_the_link($args = array())
{
	if (function_exists('get_the_image'))
	{
		$args = wp_parse_args($args);
		$args['echo'] = false; // prevent echo output
 
		$imageElement = get_the_image($args);
		$pattern = '/src=(['"])?(.*?)\1/i';
		preg_match($pattern, $imageElement, $matches);
 
		return $matches[2];
	}
}

You can now call the get-the-link template tag from a template and pass it as a parameter to the timthumb script for resizing. Look at the timthumb.php comment block for parameters and usage. The timthumb.php file is included in the hijriah theme.

I must say that writing a library type plugin was much simple than I thought. So, don’t hesitate to give it a try as the more you learn, the more comfortable you will be about customizing WordPress. I learned a lot about theme development during this process and now feel comfortable enough to develop a custom theme. I’ll write about that experience in a future post.

Download the Plugin