Simple widgets. Widgets 101.
Posted by Leonid Mamchenkov on June 16, 2007
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:
- Create a function that prints something out.
- 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:
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.