WordPress Bits

Hacking WordPress. Keeping the bits together.

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:

  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).

Hello, World!

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):

Register sidebar widget

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:

DIV with Hello world

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

Hello world widget with include

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):

Date widget

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

Register date widget

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.

15 Responses to “Simple widgets. Widgets 101.”

  1. […] with controls. 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 […]

  2. Michel said

    Interesting read. All easily explained… to the point that even I with my limited PHP knowledge want to start playing with some code examples right now:-)

    I have lots of small things in the sidebar (buttons, badges, etc.) — I may try converting them to widgets and see what’ll happen:)

  3. Michel,

    I am really glad to hear that it’s easy to understand this stuff. That was my main goal. The official documentation is a bit lagging behind, and I want people to start using these things, because I see lots of potential for amazing things. Being a lazy person, I don’t want to think of all those things myself. And neither do I want to program them all myself.

    Anyway, more is coming. Probably this weekend I’ll have some time for an article or two… Stay tuned.

  4. Michel said

    Just tested — works :)

    And how do plugins that create widgets work? In the same way?… I now go reading your next part:)

  5. Michel said

    PS Staying tuned! ;-)

  6. Michel,

    yes, plugins that create widgets work in the same way. Just instead of having a widget file with PHP code, you use plugin’s file. You can have some additional logic in the plugin too.

    As a rough example consider this:


    # we will use one of this functions for our
    # widget depending on the circumstances

    function a () {
    ...
    }

    function b () {
    ...
    }

    function c () {
    ...
    }

    # Choose which function to use
    if ($something) {
    $widget_function = 'a';
    }
    elseif ($something_else) {
    $widget_function = 'b';
    }
    else {
    $widget_function = 'c';
    }

    # Create widget
    register_sidebar_widget('My widget',$widget_function);

    As a result of this code, we will always have the widget with the same name (‘My widget’). But the functionality of this widget will vary depending on our conditions.

    There are many practical applications for this. One which comes to mind is an advertising/banner management solution. I can have Google Analytics, Yahoo, MSN, and local ads. And I can easily switch and combine them, depending on the provided options or on service license/agreement.

    Moving this functionality between sites becomes very easy. And an additional layer of fun comes from widgets having their own configuration and plugins having their own configuration. And … I’ll stop here, because the potential blows my mind ;)

  7. Once again I am convinced that a screenshot of my editor looks by far better than text code in this blog. :)

  8. […] from the Exec-PHP widget to its own widget plugin. This too proved to be more complicated than some people made it seem. Perhaps it was because I also had to requirement of the widget being a plugin, rather […]

  9. […] special thanks to Leonid at WordPress Bits for his excellent tutorial on creating simple […]

  10. Thunder said

    How crate widget that list blog directory in my blog, add static link in code in widget script ???
    Pleas simple example !!! :)

  11. Thunder,

    I think the widgets that you want to create already exist. Check the http://wp-plugins.net

  12. Creating AdSense Widgets in WordPress

    Recently I attempted to create a WordPress widget for an AdSense Firefox referral image ad in a widget-ready theme. I was quite surprised how easy it was. It may not be the best code ever, but it got the job done. Here is a quick run-down of how I did …

  13. ElMehdi said

    Thank you for your article : clean and clear :)
    Regards;

  14. […] Simple Widgets. Widget 101. – I used this tutorial to create my ‘Simple Archives’ sidebar widget. It’s very straight to the point and perfect for adding a widget in which you’re trying to display some php queries or results. […]

  15. Oh good! I’ve created a widget to get latest sticky post with below code for my website somihanquoc.com and it runing. Thank you very much. Here is this code:
    $sticky, ‘caller_get_posts’ => 1 ) );
    ?>

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s

 
%d bloggers like this: