the MerchantOS developers blog

Wordpress 2.5 And Widgets

A Wordpress Widget is a dynamic element that can be placed in the sidebars (or anywhere that is declared a sidebar) in your Wordpress theme. For example on this blog there is a right sidebar with these widgets: Search It, Recent Entries, Categories, Related Sites, Recent Visitors (by Feedjit), Recent Readers (by MyBlogLog). A widget can be any small modular piece of html (usually a list but not always) that can be stuck into a sidebar.

Widgets Make Your Plugin More Flexible

If you write your plugin as a widget your users will easily be able to move your plugin to which ever sidebar they want and arrange it with their other widgets how they want to. And they can do all of this without touching their theme’s code. This is great for users who don’t know how to modify a Wordpress theme template.

Sidebars Are Not Just Sidebars

Though they are called sidebars, they can actually be any block element of the page. A sidebar could be a heading, a footer, a section within a particular page, anything you want. It’s easy to declare a sidebar. Usually sidebars are declared within a theme’s functions.php file.

Declaring Your Sidebars – From Within A Theme

Update: There’s a great tutorial just on making your theme widget ready over here.
For example in a theme I’m working on I have 3 sidebars, normal left and right sidebars, and a top navigation bar that I’m also using as a dynamic sidebar for widgets. In my functions.php file I have:

register_sidebar(array(
    	'name'=>'top_sidebar',
        'before_widget' => '<li id="%1$s" class="widget %2$s">',
        'after_widget' => '</li>',
        'before_title' => '<h2 class="widgettitle">',
        'after_title' => '</h2>',
    ));
    register_sidebar(array(
    	'name'=>'left_sidebar',
        'before_widget' => '<li id="%1$s" class="widget %2$s">',
        'after_widget' => '</li>',
        'before_title' => '<h2 class="widgettitle">',
        'after_title' => '</h2>',
    ));
    register_sidebar(array(
    	'name'=>'right_sidebar',
        'before_widget' => '<li id="%1$s" class="widget %2$s">',
        'after_widget' => '</li>',
        'before_title' => '<h2 class="widgettitle">',
        'after_title' => '</h2>',
    ));

You can see some basic documentation on register_sidebar here. The name=>top_sidebar’ tells Wordpress what I’m calling my sidebar. This name will be displayed in the Admin interface under Design->Widgets->Current Widgets in the drop down list. You also use this name to place all the sidebar widgets within your them template. Users can choose to add widgets to any of the declared sidebars. The before_widget, after_widget, before_title, and after_title specify some html to wrap the widget in. This is handy if you need to style the widgets in a special way for your theme.

Using Dynamic Sidebars Within Your Theme

To use your sidebars within a theme you just call the dynamic_sidebar function. Here’s how I do it in my theme:

<?php if (function_exists('dynamic_sidebar')) {
dynamic_sidebar('right_sidebar');
} ?>

This tells Wordpress to call the display functions for all the widgets the user has added to the ‘right_sidebar’ sidebar.

A Hook To Hang Your Widget From

You’ll need to tell Wordpress about your plugin’s widget. To do this you declare a “plugins_loaded” action hook like so:

    function mycoolplugin_loaded()
    {
        $widget_ops = array('classname' => 'mycoolplugin_widget', 'description' => "A very cool widget for your sidebar." );
        wp_register_sidebar_widget('mycoolplugin_widget', 'CoolPlugin', 'mycoolplugin_widget', $widget_ops);
    {
    add_action('plugins_loaded','mycoolplugin_loaded');

In your widget you’ll want to replace mycoolplugin with the unique name you’ve chosen for your plugin. And you’ll want to replace “A very cool widget for your sidebar.” with the real description for your widget.

A Note For Uber-Geeks

Your Widget Display Code

In the code above we specified mycoolplugin_widget as the callback function for Wordpress to use when it wants to display your widget. So we’ll need to declare this function and use it to generate our widget’s HTML code.

function mycoolplugin_widget($args)
{
	extract($args); // extracts before_widget,before_title,after_title,after_widget
	echo $before_widget . $before_title . 'CoolPlugin' . $after_title . "<ul>";
	for ($i=0; $i<10; $i++)
	{
		echo "<li>List Item $i</li>";
	}
	echo "</ul>" . $after_widget;
}

My widget simply displays a header of “CoolPlugin” and then a list of ten items. Of course you’ll want to make your widget do something much cooler, but I’ll leave that to you!

Further Reading & Resources

Most of these resources a little out of date for Wordpress 2.5. Most of the screen shots show the admin widget pannel for 2.3 instead of 2.5.

• Widget API Documentation – documents the functions register_sidebar and register_sidebar_widget
• Making New Widgets – Recommended tips for designing plugin widgets.
• Widetizing Your Wordpress Themes
• Worpress API Actions – Documents action hooks like ‘plugins_loaded’ you can use to change Wordpress.
• Wordpress API Filters – Documents all the filters you can use to change Wordpress.
• Wordpress Widget Information – Basic information on widgets.
• Blog Post: Wodpress 2.5 Released – A blog post introducing Wordpress 2.5.
• Makebeta Wordpress Customization – A tutorial I wrote about how to customize Wordpress.

{ 13 comments }