Writing WordPress plugin. Widget Loader.
Posted by Leonid Mamchenkov on June 18, 2007
One of the best things about WordPress is its flexibility. For any given problem there are several solutions (“There is more than one way to do it” paradigm at work). There are many places where you can add code and markup – widgets, templates, plugins…
In this post, we’ll look at WordPress plugins. What are they? What can we do with them? How do we write them? We’ll go as far as create our own WordPress plugin from scratch. And it will be a useful one too.
WordPress plugins are simply chunks of PHP code. They are very useful for separating logical pieces of functionality of your web site for easier maintenance and reuse. If you know how to program PHP, you can make your web site do anything you want it to. If you don’t know how to program, you can browse through available plugins (see WordPress plugin directory for example) and choose pieces that suit your needs and wants – usually, installation and configuration of WordPress plugin requires very little technical expertise.
I like thinking about WordPress plugins as bricks. Bricks aren’t very useful or interesting on their own. Similarly, WordPress plugins aren’t of much interest when examined separately from WordPress. But when bricks are put together, when they are mixed with some concrete and architect’s creativity, we can see them emerge into some amazing structures. Similarly, WordPress plugins, when mixed with themes and widgets, can make a web site to really stand out.
Let’s jump into action now. Let’s solve some boring problem with a WordPress plugin. Let’s make something useful. Do you have any ideas yet?
Well, I do. During our widget tutorials, I kept doing the same thing over and over again – registering widgets. For each widget that I want to use for my web site, I had to have this piece of code added to my theme’s functions.php:
It’s a small chunk of code. It’s easy to understand and all. But what happens if I have dozens of widgets that I want to use? My functions.php grows and grows. What happens when I want to use the same widget or two for another web site of mine? I have to do plenty of scrolling, coping, and pasting. This doesn’t sound like a lot of fun. There should be a better way.
What if I could just have a separate file for each widget (which I already have anyway), and what if I could just copy this file somewhere into my theme directory and the widget contained in that file just be available for me in the administration area? That would make my life so much easier!
Can I have it so? The answer is “yes”. “Yes, of course”, even.
I can have a plugin, which, when enabled, would look at a predefined place in my theme, find all widget files, and automatically register them. Let’s starting writing it.
For my plugin, which I decided to call Widget Loader (yes, very creative, I know), I’ll need a single file. No need for a subdirectory or anything like that. Here is how I start my plugin widget_loader.php:
WordPress plugins start with a comment, which provides some information about the plugin, which WordPress displays in plugin administration interface. Things like plugin name, version, information about author, license and stuff like that, all go into this comment. (See WordPress Plugin API for more information)
Now we can add PHP code for our plugin. For Widget Loader, all we need is a simple function, which will look for files in widget/ subdirectory of the current theme, and include() them. Here is the code:
Small and simple. Just the way I like it (see KISS principle). There are a few things to note though:
- Function name – lm_widget_loader. We want our function name to be as unique as possible, to avoid name clashes with functions from other plugins that we might use on our web site. Here, I’m prepend my initials to the function name.
- Safety. There is no such thing as too safe when it comes to WordPress plugins. WordPress is a popular application, which runs on a number of platforms, with varying configurations. This brings a lot of potential for things being not exactly as you’d expect them. So, it’s a good idea to check your assumptions – WordPress versions, availability of functions that you rely on, PHP version, filesystem operations, database connectivity, etc. Before using something, check that it’s there and that you have enough rights to use it.
- Cleanup. With this simple code snippets it doesn’t look like a big problem if you leave something hanging – an open file or directory, an extra database connection, or a large data chunk in memory. But. You should always remember the fact that most WordPress web sites have multiple plugins enabled. When loose ends hang from a dozen plugins, things get ugly. Web sites slow down, error messages pile up, and things get hard to troubleshoot. So, cleanup after yourself.
- TEMPLATEPATH. WordPress provides plenty of handy functions and variables to make plugin developers’ lives easier. Things can be done the old way (“I’ll write that thing myself.”) or they can be done the WordPress way (there is a function or variable set for everything). It might take you some time and Codex digging to get from one stage to another.
Our plugin is almost done now. In fact, it is a valid plugin, and if you save it in wp-content/plugins/widget_loader.php , you will immediately see it appear in plugin administration interface inside WordPress. Activate it there, and you will be able to use lm_load_widgets() function call from anywhere in your theme or other plugins.
And that is the thing that I don’t really like now. All my widgets are loading just fine, but I have to remember to call lm_load_widgets() from my theme. And what if I give this plugin to somebody who is not very technical? They’ll have to edit their theme files, which can lead to all sorts of problems.
Instead, I want this function to be called automatically. I want WordPress to handle it on its own. It should be smart enough. And, in fact, it is.
WordPress has those things called “hooks“. Hooks are programming interfaces that allow us, programmers, change the way WordPress behaves, but from within our plugins and themes, without the need for editing of WordPress core files. There are two types of hooks – actions and filters. Filters allow us to change WordPress output, such as post title or user comment. (We’ll talk about these in another post later on). Actions allow us to tell WordPress what we want it to do when it gets to a certain point, such as printing comment form, inserting post into the database, or checking user’s credentials.
For our little Widget Loader plugin, we want to tell WordPress to call lm_widget_loader() function whenever it initializes (basically, when it loads all that other stuff and prepares to serve a request). There is a hook just for that. It’s called “init“. (You can see which other hooks are available together with some documentation for them at WordPress Hooks web site.) Here is how we use it:
That’s it. Just in case you missed or misunderstood something, here is the full text of our wp-content/plugins/widget_loader.php file:
Once this plugin is activated, we can just drop some widget files into widget/ subdirectory of our theme. To remove a widget, we just delete it from that subdirectory. To edit the widget, we just edit the file. No need to do tonnes of boring copy-paste. Chances of breaking something are even smaller now. And we can easily reuse bits and pieces between different themes and even between different web sites.
We’ll talk more about WordPress plugins in the upcoming posts…