WordPress Bits

Hacking WordPress. Keeping the bits together.

Advanced widgets. Widgets with controls.

Posted by Leonid Mamchenkov on June 17, 2007

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:

Date widget

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

Register date widget

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:

Advanced date widget

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:

Control for advanced date widget

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:

Register sidebar widget with control

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.

Date widget control popup window

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


11 Responses to “Advanced widgets. Widgets with controls.”

  1. Michel said

    I’ve done this example, too. Works:)

    One question, though:

    How to include this more advanced widget with controls in widgets/advanced_date_widget.php (for example)?

    The simpler example from the previous post I made easily… But this one?


  2. Michel said

    Tip: If code is in image format, then, please (if possible) provide also code samples for download as .txt files… Not that I can’t retype them, but it’ll be just easier:)

  3. Michel,

    just put all your code in the widget’s PHP file. Including the register_sidebar_widget() and register_widget_control() function calls. If you use the Widget Loader plugin, than your widget’s PHP file will get included and whatever is in there will be executed.

    Regarding the text version – yes, I want to do it. But currently WordPress.com doesn’t even support text attachments. Boomers. I should probably let them know or something… :)

  4. Shawn said

    Not all I need to know!

    Can I have multiple instances of a widget? can each use a separate “argument”?

    This would probably be great for configuring different banner ad blocks for openAds (phpAdsNew) within the different sidebars– but each uses a different banner ad zone id.

    You wanna continue showing us how to get progressively complex with this stuff? You’ve done great so far.

  5. Shawn,

    guilty as charged. :)

    Yes, indeed, there is more. I’m working on a new post for widget series. Multiple instances with their own options each. It should come out sometime before WordPress 2.3. :)

  6. Ryan Fox said

    What about registering a widget as a plugin? I’ve downloaded a few widgets that I had to add as plugins, rather than registering them with the theme. To me, this seems preferable since they would also be very easy to move between themes and you could easily enable/disable them.

    Now that you’ve shown that widgets are crazy-simple to make, I might just have a go at it myself.


  7. Ryan,

    making widget into a plugin is not any more complicated. All you have to do is put a file with some comments at the top to the plugin folder. The minimum comment, I think, should be the “Plugin Name”, but you can easily add more.

    Once you have the comment with meta information about your plugin at the top, and WordPress recognizes it as a plugin, you can put your widget stuff – register_sidebar_widget(), etc.

  8. Your guides on writing / using widgets are excellent! I have used them to somewhat “widgetize” a theme that I’m working on (based on cutline, see here (development area) and I was wondering if the widget controls need to perform any “cleanup.”

    In other words, 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?

    Just want to make things nice and neat…

  9. Matthew,

    nicely going theme you’ve got there. I really like the idea with colored boxes and the bottom part with links and stuff. :)

    Regarding your question… as logical as it is, I never actually thought of it, so I’m not sure at the moment. Thanks for asking! I’ll check it out and either reply here (if it’s something small), or write up a new post (if it makes sense).

  10. […] WordPress customiza…Leonid Mamchenkov on Automating WordPress customiza…Matthew Smith on Advanced widgets. Widgets with…Stephen Rider on Automating WordPress customiza…Aaron on Automating WordPress customiza…Jonathan […]

  11. Truong Trong Hai said

    I love this example.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: