1. Code
  2. Widgets

Writing Maintainable WordPress Widgets: Part 2 of 2


In the first post in this series, we discussed the reasons that WordPress Plugins should be treated more like larger software projects (but often aren't) and made a case for using well-organized code in an attempt to make our plugin projects more maintainable. All of this was done within the context of developing a WordPress widget.

The thing is, widgets are not the only type of plugins that can be developed for WordPress. The application also supports plugins that extend its functionality through the use of hooks located throughout the application. As such, widgets are not the only type of plugin that could benefit from a boilerplate.

In this tutorial, we'll define what exactly WordPress hooks are, how they work, and why they are beneficial. Next, we'll take a look at my WordPress Widget Boilerplate and how to leverage it in new projects through the context of an example application.

Understanding Hooks, Actions, and Filters

Before developing plugins, it's important to understand WordPress' model for hooking into the application and the different between actions and filters.

  • Hooks are areas in the core WordPress application that allow you to register your code for execution. Simply put, your plugin registers itself with WordPress at a specific point of execution. When WordPress reaches that point of execution (either in saving information, rendering information or some other point), it fires your code.
  • Actions are a type of hook that WordPress makes available for you to take advantage of whenever a specific event occurs during the application's life cycle. Some of these points include whenever a theme is activated, whenever a post is saved, or whenever style sheets are being rendered. Generally speaking, if you're looking to insert some type of custom functionality at any point in the WordPress life cycle, there is likely an action hook available.
  • Filters are a type of hook that WordPress makes available for you to manipulate data before sending it to the database or sending it to render in the browser. Simply put, WordPress will pass the content to your function and then continue with its process with whatever you return. If you're looking to manipulate data before saving it or seeing it, your best option is to use filter.

Easy enough, right? On top of that, WordPress has solid documentation for adding actions[1] and adding filters[2]. You can reach much more about plugins in the Plugin API[3] in the WordPress Codex[4].

A Plugin Boilerplate

If you read the previous article, then you are already familiar with the Widget API. It's precise in that it requires a constructor and no less than three functions to get something working. Because plugins have the flexibility of hooking into a variety of points in the WordPress process, the Plugin API is a bit less structured. Fortunately, this doesn't mean that we can't craft some form of boilerplate off of which to create our plugins.

After all, they still consist of some common functionality:

  • Core plugin code
  • Style sheets
  • JavaScript
  • Localization files
  • Markup
  • Images

Similar to our WordPress Widget Boilerplate, we can setup our template directory to look like this:

Looks familiar, doesn't it? The most important aspect of the Plugin Boilerplate isn't the details of the directory structure (though we will examine a bit in the future) but the organization of the core plugin code itself.

The Plugin Skeleton

Plugin's can be developed either by using a handful of functions or by wrapping each function in a class in an object-oriented approach. I'm a fan of the latter and my boilerplate represents that. Here's the plugin definition:

Most IDE's have a function that lists all outstanding TODO's, so I place them throughout the code to easily locate what needs to be done during development. Note that there are three primary areas of code:

  1. Constructor. This function is responsible for defining any constants used throughout the code, specifying any localization files, and registering all actions and filters with WordPress.
  2. Core Functions are the actual function definitions registered in the constructor that are fired after during WordPress' execution.
  3. Helper Functions refer to functions that I use that help in execution by abstracting away common functionality (such as registering JavaScripts and stylesheets).

Note here that plugin development deviates from widget development in that there aren't multiple functions that are expected. In fact, you really only need a constructor. From there, any functions defined within the add_action or add_filter calls and your responsibility to implement.

Make sense? Let's take a look at using this boiler plate in a simple example.

A Working Example With Your Blog's RSS Feed

WordPress offers hooks for almost point of execution that you can imagine. In this example, we'll hook into the post rendering process in order to introduce a custom message. The thing is, we only want to display said message within the context of an RSS reader.

First, the requirements:

  • Display a message at the footer of each post
  • The message should only appear in RSS readers
  • The message should contain a link back to the website of the post

Based on this, it doesn't look like we'll need to use any JavaScript, CSS, or markup create our plugin so we can reduce our plugin boilerplate to the core plugin code and the localization files:

At this point, we can begin stubbing out the boilerplate with a name and the plugin constants:

Next, we need to consider what type of hook is required for manipulating the content. Recall tha tsince we're trying to add something to the content proir to rendering it in the browser, we'll need a filter. From here, we can stub out the constructor:

Note that the function is using two filter - one for the_content[5] and one for the_excerpt_rss[6]. We're doing this because some users opt to only publish an excerpt of their blog rather than all of the content and we want to make sure that we're capturing both cases.

Next, let's actually implement the function definition that will append the message to the rest of the post:

Note here that the function accepts a parameter referred to by the $content variable. WordPress itself is passing this data into the function. For these particular filters, we're dealing with the content of a blog post so whatever we add to it must be concatenated so that it's added to the end of it.

This message we're adding simply says "Thanks for reading! Be sure to catch up on the rest of my posts at [Blog Name]!" through use of the get_bloginfo()[7] function.. Of course, you can update it to read whatever you like. Finally, note that we've wrapped this in an conditional that checks the is_feed()[8] function. This is important as we only want this code to fire if the content is being sent via an RSS feed.

That's it - not too bad, right? You can download the full version of the working source code (including the associated README) for this plugin on GitHub or right here from Wptuts. The boilerplate is also available on GitHub, too.

The point of this series was not only to help provide an introductory guide to the WordPress Plugin API, but also to provide a case and boilerplates for making it much easier to treat and maintain WordPress Plugins like any other software project.

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.