Creating a WordPress Widget

Once you’ve created a sidebar, you’ll probably want to add code to it. If you can’t find an existing widget that serves your needs, there’s a few options:

1. Use a plugin that let’s you execute PHP in the widgets. Do NOT do this, because if you make a php error you won’t be able to log in to fix it, and you can’t FTP into the theme files to fix it. You’ll need to go into the database and delete the widget (which is hard to find).
2. Stick the code before or after the widget, either in the theme file or, if you’re using Thesis or Genesis, using a hook. This is okay if you want it at the top or bottom, but it’s not very flexible. It also doesn’t provide the end user/client the ability to remove it, like they could with widgets.
3. Build your own widget.

For a while I used Option #2 because I thought it would be difficult to build a widget – not worth it for the small piece of code I was trying to add. But after reading Justin Tadlock’s excellent post on widgets I started building my own.

If the widget you’re building will only work with the specific theme you’re building, include the widget code in the theme files. If the widget can be useful for other themes or clients, build it as a plugin. That way you can easily add it to future projects. Here’s some examples from recent projects of mine:

• Theme specific: Navigation for a custom post type (ex: when on a Person page list all the posts in the People post type, broken down by Role).
• General widgets: Subpages widget, Twitter widget  (I took the official Twitter widget and built it as a WordPress plugin so all the options can be controlled from the Widgets page).

There’s two types of widgets you can build:

No Options Widgets

These widgets don’t provide any options or input fields for the user on the Widgets page. When you drop it in a sidebar, it says “There are no options for this widget.” This is best if you need to just drop a piece of code in the sidebar. Here’s the Subpages widget:

The first piece of code loads the widget at the appropriate time. The second one creates our widget as an extension of WP_Widget. This allows us to build on top of all the existing widget code and only add our specific customizations. The last piece (function widget()) is the actual widget code. For this specific widget I’m doing the following:

• If the current page has a parent, get all the children of the parent. If it doesn’t have a parent, get all the children of the current page.
• If there’s any children pages, display an unordered list of them.
• I put all the widget code, including the $before_widget and $after_widget variables inside the if statement so that if there were no children I wouldn’t have an empty widget. Typically those variables will be at the top and bottom of your widget.

Widgets with Options

We can also build widgets that have options on the Widget page for the user to customize. In addition to the above code, we’ll need to add the form code (what the user sees when on the Widget page) and the update code (what happens when they click “Update”). Fortunately we’re extending WP_Widget, so these parts are really easy. I’m going to extend the subpages widget to include a Title box which the user can control.

What I’ve added:

• At the beginning of the widget code I pull in the value for the Title.
• Right after $before_widget, I check to see if $title has a value, and if it does, display $before_title, $title, and $after_title.
• The update function will strip any HTML tags from the title before saving it as the new title.
• The form function sets the default value, then pulls in the current values (if the widget has never been saved before, it will use the default value). Then it displays the actual form input fields.

For more details on creating widgets, read The complete guide to creating widgets in WordPress 2.8.