WordPress 3.0+ Custom Widgets How-to

After recently trying to figure out how to make a custom widget/widget template for a theme I’m working on, I discovered that it was difficult to find good information that wasn’t just explaining how to make your theme widget-ready etc.

Wait a second …. this is really off topic isn’t it?  Well, compared to what I have used this blog for so far, yeah, it is.  But there’s times I’d like to share things other than topics regarding my faith and as a mere servant, this seems suitable to place them here.

Overview to Widgets and This Article

I feel it necessary to go ahead and clarify what this is about so if it’s not what you’re looking for, I won’t waste any more of your time.
My goal is to first very briefly explain enabling widgets via your theme’s code and then how to make your own custom Widget.  If that’s what you’re here for, then you most likely found the right place.

A place to put the Widgets – Showing them in your theme

The first step is adding what WordPress refers to as a Sidebar, which is more less a “bin” that you can add various widgets to show in your theme.  There’s two functions you can use to do this:
register_sidebar() – For adding a single sidebar.
register_sidebars() – For adding multiple sidebars.

Since there’s plenty of information on how to use these, including the tutorial links under the Resources Section of the register_sidebar() page, I’ll leave it at that.

Make a custom widget – A working example

So now we get down to the nitty gritty….
I found This Example Code by Jonathon Byrd that offers two different examples of adding/creating a custom widget for use and we’re going to use it since I thought it made great example code.
As I mentioned, there’s two different example files included and only one is needed, so we’ll start with the one he named QuickWidget.php.

Quick and Easy Custom Widget

Copy the file QuickWidget.php to your theme’s directory, then in your functions.php file add the following:


// Include example widget
require 'QuickWidget.php';

Now if you go to Appearance > Widgets in your WordPress Administrator panel (the theme must be enabled!), you should see a widget named Document Widget with the description A Foo Widget with the rest of the available widgets.

Now you can tinker with the QuickWidget.php file and make your custom widget!  This gives you a working template to work with so you can test your changes and so forth.

Master custom Widget class

The second file named MasterWidget.php takes a little more of an advanced approach by creating a widget “framework” so that adding/customizing one or more widgets is as easy as possible.  This doesn’t just work straight-out-of-the-box like the previous one and we need to take a couple of extra steps, but it’s still simple so here we go…

Like with the above file, we have to copy it to our theme’s directory and then include it in our functions.php file.  So copy the MasterWidget.php file to your theme’s base directory and then add the following to your functions.php file (Keep it open, we’ve got more work to do in a second…):


// Include custom widget class
require 'MasterWidget.php';

Now in the MasterWidget.php file, copy the following section of code (currently lines 41-95 in  MasterWidget.phpand paste it either the bottom of your MasterWidget.php file or add it to the functions.php file like such:


// Include custom widget class
require 'MasterWidget.php';

//build an array of settings
$docWidget = array(
	'id' => 'first-custom-widget',	//make sure that this is unique
	'title' => 'aaaFirst Widget',
	'classname' => 'st-custom-wi',
	'do_wrapper' => true,
	'show_view' => 'document_widget_view',
	'fields' => array(
			'name' => 'Title',
			'desc' => '',
			'id' => 'title',
			'type' => 'text',
			'std' => ''
			'name' => 'Textarea',
			'desc' => 'Enter big text here',
			'id' => 'textarea_id',
			'type' => 'textarea',
			'std' => 'Default value 2'
			'name' => 'Select box',
			'id' => 'select_id',
			'type' => 'select',
			'options' => array('Option 1', 'Option 2', 'Option 3')
			'name' => 'Radio',
			'id' => 'radio_id',
			'type' => 'radio',
			'options' => array(
				array('name' => 'Name 1', 'value' => 'Value 1'),
				array('name' => 'Name 2', 'value' => 'Value 2')
			'name' => 'Checkbox',
			'id' => 'checkbox_id',
			'type' => 'checkbox'

//register this widget

function document_widget_view( $args )
	the view for my widget

After saving your changes, go to Appearance > Widgets in your WordPress Administrator panel (the theme must be enabled!), you should see a widget named aaaFirst Widget with the description aaaFirst Widget with the rest of the available widgets.

If you drag it/add it to a sidebar, you can expand it and see the widget fields that were created by the ‘fields’ array in our $docWidget array.  This is as far as I’m taking you in this tutorial on creating the custom widget, but now that you have a working example, play with the input array values and you’ll have your own customized widget in no time!

Custom WordPress Widget - Admin Panel Preview

Custom WordPress Widget – Admin Panel Preview

Further Reading/Resources

Posted in Uncategorized Tagged with: , , , , ,
2 comments on “WordPress 3.0+ Custom Widgets How-to
  1. web says:

    How do you then access the fields in the view section? In the normal WP widget class you can use, for example $instance[‘title’], but $args[‘title’] didn’t work work here.

    • web says:

      Variables like $title, $width, etc. didn’t work either, though I would have expected them to due to the extract($args) line. They came out empty.

Leave a Reply

This Article’s Short URL

Want to link or Tweet this article?
Here's the short URL to it: