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 and more.

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

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>',
));

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.

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!