Custom WordPress Widget Template

I had a bunch of custom widgets to create for this theme, mostly for displaying ads, and then one to display twitter/RSS followers, and one to display a tabbed widget that included popular posts, recent posts, tags and comments. Creating a custom widget is surprisingly easy, after getting the first one done, I just modified it for the others. I thought I’d share a basic template for a custom widget, which can be modified to do all sorts of things. The possibilities are endless!

The custom widget we’re creating is basically the same as the default text widget, it takes text input in the widget admin panel and displays it as a widget in your theme.

The code for our widget is going to live in a file called “widget_example.php” inside a directory called “functions” in the theme’s directory. All we have to do is reference it in functions.php.

$functions_path = TEMPLATEPATH . '/functions/';
require_once ($functions_path . 'widget_example.php');

I’ve included a lot of files from functions.php, so I stored the path in a variable.

Next we’re just going to dive right into the template, most of the important information is commented, so hopefully you can follow along:

<?php

	add_action('widgets_init', 'ex_widget_example');

	function ex_widget_example() { // function name matches name from add_action
		register_widget('Ex_Widget_Example');
	}

	class Ex_Widget_Example extends WP_Widget {

		function Ex_Widget_Example() { // function name matches class name
			$widget_ops = array(
				'classname'=>'example-widget', // class that will be added to li element in widgeted area ul
				'description'=>'Display text from input' // description displayed in admin
				);
			$control_ops = array(
				'width'=>200, 'height'=>250, // width of input widget in admin
				'id_base'=>'example-widget' // base of id of li element ex. id="example-widget-1"
				);
			$this->WP_Widget('example-widget', 'Example Widget', $widget_ops, $control_ops); // "Example Widget" will be name in control panel
		}

		function widget($args, $instance) {
				extract($args);

				$text = $instance['text'];

				echo $before_widget;

				if ($text) echo '<p>'.$text.'</p>'; // how input text will be displayed

				echo $after_widget;
			}

		function update( $new_instance, $old_instance ) {
			$instance = $old_instance;
			$instance['text'] = $new_instance['text'];

			return $instance;
		}

		function form( $instance ) {

			$defaults = array('text' =>'default text');
			$instance = wp_parse_args( (array) $instance, $defaults ); ?>

			<p>
				<label for="<?php echo $this->get_field_id( 'text' ); ?>">Custom Text:</label>
				<input id="<?php echo $this->get_field_id( 'text' ); ?>" name="<?php echo $this->get_field_name( 'text' ); ?>" value="<?php echo $instance['text']; ?>" style="width:100%;" />
			</p>

<?php
	}
}
?>

This code outputs the following HTML when added to a widgeted area:

<li id="example-widget-3" class="widget example-widget"><p>Testing Text</p></li>

Now to customize this widget, you basically rename all the bits that say “example” with the name of your widget, and the “Ex” prefix is where you reference your theme’s name abbreviated, to prevent clashing with functions from plugins etc.

To get the widget to do something else, you just change the variable “text” everywhere it occurs to whatever you’re going to display, for example, you might want to change it to an image, so the user would input the URL to an image, and then in the output bit, you would change it to something like

if ($image) echo '<img src="'.$image.'" />';

So there you have it, basic “copy-and-paste” template for a custom WordPress widget. Have fun!