In one of the recent posts – “Advanced Widgets. Widgets with controls.” – we saw how to create WordPress widgets, which could have configuration options.  In one of the comments to that post, Matthew Smith, asked a very good question:

do the widgets leave settings in the database upon removal? Should these be cleaned up using a hook like unregister_widget() (if it exists, I haven’t looked yet)? Or does WordPress do this automatically?

Nicely spotted, Matthew!  Thank you.

Indeed, what happens there?

Widget settings are stored in regular WordPress options.  Some widgets can be re-used several times (like Text widget and  RSS widget).  This can cause plenty of data to be flowing around.  That, in turn, can affect web site’s performance and server’s memory usage.

What can we do about it?   It’s obvious that we have to do some sort of clean-up routine, but how, when and where?

To answer those questions, let’s refresh our memory with how we got ourselves into that mess in the first place.  WordPress options are updated and populate from within our widget control.  Here is the control code that we used for that article:

Here we see the call to update_option(), which populates the database with our stuff.   This routine is registered as widget control, using the following line (again, the code is from the previous article):

Here is a call to register_widget_control() function.  This is how we add stuff.  So, to remove stuff, there should be something like unregister_widget_control() somewhere.  Let’s look through WordPress code for a bit… ah, here it is, found it!  wp-includes/widgets.php (no link to WordPress Source this time, as it features version 2.1-alpha2, which didn’t have widgets yet, so use your own copy of WordPress for reference)has definitions of all widget things that we saw registering – unregister_sidebar(), unregister_sidebar_widget(), and unregister_widget_control() .

OK, now that we know that it would be nice to call unregister_widget_control() and delete_option() for our widget, where is the best place to do so?  I mean, if we just add those calls to our widget file, it will get unregistered and we won’t be able to use it.  How can we know when is our widget in use and when it’s not and when is it the best time to do the cleanup?

The answer to that, of course, depends a lot on how you do things.  There are many places to create widgets (themes, plugins), so there is no single recipe here.   But from the first glance, it seems, that putting all widget stuff into a  plugin makes sense.  When the plugin is activated, both the widget and its control are registered, and the database option is populated.  When the plugin is deactivated, the widget and the control are unregistered and the database option cleaned up.

We’ll look at how to create widget plugins in one of the upcoming posts.  (There are still a few issues in that area that I need to figure out before I can do a full blown post on that.)

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.

WordPress plugins live in wp-content/plugins/ subdirectory. They can be simple PHP files, or they can have directories and subdirectories, CSS styles, JavaScripts, and images of their own. Like widgets, WordPress plugins can be as simple as a single command, or as complex as a standalone application.

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…

Hopefully, by now you understand how cool and powerful WordPress widgets are. Widgets 101 demonstrated how to create simple widgets with text paragraphs, HTML markup, and even some PHP code. What else is there? Not much, but something.

In this post we’ll take a look at how to create widgets which support options and easy configuration via administration interface. WordPress calls these widgets with controls.

Let’s reuse one of the examples from the Simple Widgets post – the Date widget. Here is how it looks so far, without any controls.

We have all output in widgets/current_date.php file:

And we have registered this widget in functions.php file of our theme like so:

It works and seem OK, doesn’t it? Well, it does. But what if we want to change the format of the date? What if instead of “February 23, 2007″ we want to use “23 Feb 2007″? We’ll have to edit the file widgets/current_date.php and correct the date() format. This doesn’t seem right. WordPress is a beautiful, flexible platform, and we shouldn’t be editing PHP files for simple changes like that.

And, indeed, we don’t have to. Let’s upgrade this widget. We’ll give it a control – a configuration screen, where users will be able to edit date() formats. For this to work, we’ll have to do the following:

1. Upgrade our output function to understand options.
2. Create a new function which will manage option editing.
3. Register that new option editing function as widget control.

Here is how the new function for date printing looks:

All in all, it is very similar to what we had before. The core functionality of this widget is still date printing. Now, for our control function:

Of course, you can have several options in there, text paragraphs with option descriptions, images with instructions, and so on. Play with it. Try new things out. By the way, this code above was adopted from the WordPress’ core code for default widgets.

We have all the pieces now. It’s time to put them all together. I mean, we should proceed to step 3 of the list above and register the control for the widget. Here is how both widget and widget control are registered in my functions.php file:

In the administration interface, where I drag-and-drop the widgets, I now have a box called ‘Date’. When I drop it into one of my widget containers, I see that my ‘Date’ box also has an icon. When I click on the icon, a small window pops up, which asks me for date() format.

Now you know all about WordPress widgets that there is to know. Enjoy.

In the last post I covered widget containers and promised to tell you how to create widgets. I also mentioned that widgets can be of a varying complexity – from simple text and HTML blocks, through customized WordPress function calls, to mini applications with their own administration interface.

That sounds like a lot to cover in one post. So, I’ll leave the advanced widgets for the next time. In this post we’ll look at simple things – text, HTML, some PHP and tailored WordPress function calls.

Creating widgets is a simple two-step process. Here is an overview:

1. Create a function that prints something out.
2. Register function from step 1 as a widget.

Let’s make the simplest of all examples – a ‘Hello World’ widget. For step 1, we create a function in our theme’s functions.php file (it can be anywhere in your theme or plugins actually, but we’ll try to maintain some order).

Now, we should register our little function as a widget. We do so by adding these lines to the functions.php file (again, you can choose another location):

That’s it. All done. Now you can login to the administration, navigate to Presentation -> Widgets, and you should see a new ‘Hello World’ widget available. Drag-n-drop it to any of your widget containers (sidebars, remember?), save and reload the web page where the container is displayed. You should see the ‘Hello, world!’ string printed out.

That was easy, wasn’t it?

Before you blow up your functions.php file with gadzillion of widgets, let me share this one tip with you. Create a subdirectory widgets/ in your theme’s main directory, and keep your widgets in there. One per file. Then, simply include() your widgets. Here is an updated example with this tip implemented:

In wp-content/themes/mytheme/widgets/hello_world.php:

In wp-content/themes/mytheme/functions.php:

Now you have it with HTML. And you can use CSS to make it look good.But how about a little bit more functional example? No problem. Let’s go for something simple, but yet something practical, something that you could use for your web site (not necessarily a blog) – current date widget.

It seems that every web site out there considers it its own obligation to tell you what date it is, what day of week it is, and what time is it exactly in some time zone you’ve never heard of. A perfect task for a widget.

Here is my widgets/current_date.php file (refresh your memory of PHP date() function):

Now I create a widget function and register it in my functions.php like so:

Done. All I have to do now is only drag-n-drop this widget to the widget container that I want.

Obviously, you can have as much code and markup as you need in your widget file. You can use WordPress functions (such as wp_get_links() or wp_get_pages()), WordPress logic (such as is_home(), is_page(), and is_search()). You can include more files. You can do anything you like. You don’t even necessarily have to output anything, but I think it’s still a good idea to. Leave a trace on the page, even if that is just a space. It’ll make troubleshooting much easier later on.

I’m sure you have plenty of ideas now about how to utilize this widget knowledge. But if your mind is blank, here is a hint for you. Every time you come across something that says “Copy this piece of code and paste it into your web site’s template”, make it into a widget. Every time you see a banner or button that you want to include in your web site – make a widget. Pretty soon, you’ll start thinking that everything can be a WordPress widget. And that is so close to the truth that I won’t even argue with you.

So long, until next time, when we’ll look at advanced widgets – those that have options and need configuration.

WordPress widget is a powerful tool when used properly. Too bad, many people who use WordPress for web site building haven’t heard of them. And many of those who heard of them, don’t realize the full potential. In this post, I’ll try to put some light on WordPress widgets.

So, what is a widget and what is it good for? WordPress widget is a block of something. It can be as simple as a paragraph of text or a piece of HTML markup. It can be a customized call to some WordPress function. It can be a mini application. It can have its own options. And it can have its own administration area.

WordPress comes with a few default widgets, which are very useful for blog web sites. These are things like search boxes, archive lists, links lists, recent posts and comments, etc.

WordPress provides a way to create a sort of container, where you can put your widgets. In most cases that I’ve seen, this container is placed in sidebar – a place where such functionality belongs on a blog.

But the thing is that WordPress puts no limitation on where you can use widgets. You can create a container on your article page, or in the search results, or on a front page. It doesn’t matter. And what is even better, you can have several such containers, each with unique set of widgets.

So, why would one want to use widgets instead of just coding these blocks in the theme? Because, widgets can be easily sorted, added to the site, removed from the site, or moved from one place to another – all that without any need for coding. Administration interface has a really simple drag-and-drop interface. Define widget containers in your theme, code some widgets, and then drag them and drop them anyway you like. It’s that easy.

Can we see an example? Sure, why not.

First of all, you need to register your widget container, which is confusingly called sidebar. Here is how to do it. In one of your theme files (I prefer functions.php, but you can use anything at all – index.php, sidebar.php, search.php, whatever), add these lines:

You just created a widget container called ‘Widget Home’. (Here is a good description of widget API, if you need one.) Now we need to place these container somewhere in the theme. Somewhere, where we want it to appear. This is up to you. You can choose any place at all – front page, search results, sidebar, footer, you name it. Once you decided where you want it to be, add these lines of code:

If you will accidentally use your theme on a WordPress installation which does not support widgets, or if your widget container is empty, you’ll have a “Widget Home is broken.” string printed out. You can, of course, change it. For example, you can have a fallback include file, which you can call with include(‘missing_widgets.php’).

So far so good. What’s next?

Now you need to place some widgets into your widget container. Login to administration interface and navigate to Presentation -> Widgets. You’ll see a rectangle with ‘Widget Home’ title on top. You’ll see a rectangle with ‘Available Widgets’ below. And you’ll see some widget boxes in there, such as ‘Recent comments’ and ‘Links’. Simply drag-and-drop these widget boxes into your widget container, reoder them as you see fit, and save your layout. Check your web site. Cool, isn’t it?

See, widgets are not only for sidebars. They are for anything and everything. You can have several widget containers (sidebars, eh?) defined. For example, you can have a setup like this:

In your administration area, you’ll see three widget containers now – ‘Left sidebar’, ‘Main area’, and ‘Right sidebar’. You can drag-and-drop widgets between them. And you can use them from in your theme like so (in index.php file, for example):

Now your front page can be easily customized and organized with some drag-and-drop in the administration area. No need to play with PHP files anymore.

In the next post, we’ll see how to create our own widgets.

I am currently building a web site, which uses WordPress as a platform. It’s not a blog, but an extended a very customized content management system (CMS) with several authors and a lot of custom plugins.

One of the things the client requested was maximum flexibility of the front page. They want to have a number of information blocks, such as currency quotes, market analysis, navigation menu, and advertising units; and they want to be able to rearrange them once in a while.

This is, of course, a perfect task for WordPress widgets. If you are not familiar with WordPress widgets, I only have two things to say to you right now:

1. You are missing on a lot of fun.
2. Subscribe to RSS feed of this blog, as I’ll be talking a lot about WordPress widgets.

Anyway. I have created all the widgets that they wanted, and I tested them to work properly. But there was a tiny problem. WordPress install comes with a few widgets of its own. Things like archives, blogroll, recent comments, and search box – all have a widget version. But most of these widgets, as good as they are for a regular blog, didn’t make any sense for this web site that I am working on. There are no archives. Calendar has a totally different meaning. And comments are disabled and hidden.

Of course, I could just left the widgets out of the sidebars. But why give user a choice which doesn’t work or makes no sense, right? I wanted them removed. Hidden. Unavailable. And I didn’t want to modify any core WordPress files, so that upgrading this web site to a newer version of WordPress is easier in the future.

Here is my solution to the problem.

In the theme directory, I have a functions.php file (this file has special meaning to WordPress). In this file, I have these lines:

Here is what happens. I define a function remove_default_widgets(), which is called for action widgets_init (more on this later, but if you are in a hurry, read file wp-includes/widgets.php around lines 922-958 in WordPress 2.2). This action is called just after the default widgets are registered. In this function I simply unregister all default widgets.

Hopefully, you can spot two exceptions here. Two special widgets are Text widget and RSS widget. These two widgets have additional controls on the administration page. They ask user for options (specifically: how many copies of each of these widgets user wants). Since I don’t want to use these widgets, I don’t need their options too. The options are initialized when sidebar_admin_setup and sidebar_admin_page actions take place. By looking through WordPress source code, I manage to find the appropriate callbacks, which I can now easily cancel.

Done.