Simple Recent Posts Widget

This next part in our Working with Widgets Series is going to show you how to create a simple recent posts widget, much like my Better Recent Posts Widget plugin, though it will be even simpler. The goal of this tutorial will be to demonstrate a very useful technique that you can use in countless different kinds of widgets, and that is how to query and displays post lists.

To start, please refer back to the Simple WordPress Widget Template that I gave in the first part of this series. It will provide you with almost everything you need, and we will simply be expanding on that code.

So the first thing we will do is define our widget class:

/**
 * Recent Posts Widget Class
 */
class pippin_simple_recent_posts extends WP_Widget {
    // the rest of our code will go in here
}

Nothing too special here, so we’ll go ahead and move on to the next step: the constructor function.

/** constructor */
function pippin_simple_recent_posts() {
	parent::WP_Widget(false, $name = 'Simple Recent Posts');
}

This function essentially “builds” our widget and gives it a name. The name is what will show up on the widget panel in the WordPress admin.

Next is the function that defines the output of the widget, which, in this case, is a simple post query.

/** @see WP_Widget::widget */
function widget($args, $instance) {
	extract( $args );
	$title 		= apply_filters('widget_title', $instance['title']);
	$number 	= apply_filters('widget_title', $instance['number']);
	$offset 	= apply_filters('widget_title', $instance['offset']);
	?>
		  <!--?php echo $before_widget; ?-->
			  <!--?php if ( $title )
					echo $before_title . $title . $after_title; ?-->

At the top of this function we have setup variables that retrieve the option values set by the user on the widget panel (we’ll set these up in a moment). $title is the title of the widget that will be displayed above the post list; $number is the number of posts we wish to display; and $offset is the number of posts to skip.

After the option variables, we place the standard widget variables for $before_widget, $before_title, etc, so that our widget will fit into 99% of WordPress themes seamlessly. Now we get to the core part of this function: displaying the post list. The query, for which we use get_posts(), is no different than any other get_posts query. Pretty simple actually. The only part that may be a little different is the $args variable declaration. Because we want our users to be able to customize the posts that are displayed through the options we present them in the widget panel, we use the title, number, and offset variables we declared at the top to build our final $args variable. Then we pass the constructed variable to get_posts().

Our next function is the one that handles the updating / saving of the widget options. This one is very simple.

/** @see WP_Widget::update */
function update($new_instance, $old_instance) {
	$instance = $old_instance;
	$instance['title'] = strip_tags($new_instance['title']);
	$instance['number'] = strip_tags($new_instance['number']);
	$instance['offset'] = strip_tags($new_instance['offset']);
	return $instance;
}

We just have to remember that our $instance variable names must match in every function we write for this widget.

Now there is just one more function, and it is the one that will display our widget options in the widgets panel.

/** @see WP_Widget::form */
function form($instance) {	
 
	$title = esc_attr($instance['title']);
	$number = esc_attr($instance['number']);
	$offset = esc_attr($instance['offset']);
	?&gt;<label for="<?php echo $this->get_field_id('title'); ?>"><!--?php _e('Title:'); ?--></label> 
<input id="<?php echo $this->get_field_id('title'); ?>" class="widefat" type="text" name="<?php echo $this->get_field_name('title'); ?>" value="<?php echo $title; ?>" /><label for="<?php echo $this->get_field_id('number'); ?>"><!--?php _e('Number to Show:'); ?--></label> 
<input id="<?php echo $this->get_field_id('number'); ?>" class="widefat" type="text" name="<?php echo $this->get_field_name('number'); ?>" value="<?php echo $number; ?>" /><label for="<?php echo $this->get_field_id('number'); ?>"><!--?php _e('Offset (the number of posts to skip):'); ?--></label> 
<input id="<?php echo $this->get_field_id('offset'); ?>" class="widefat" type="text" name="<?php echo $this->get_field_name('offset'); ?>" value="<?php echo $offset; ?>" />

There’s nothing too special going on here, just remember, again, that our instance variable names must match. Each option is nothing more than a simple HTML input field with names that match the instance variables.

And, finally, there is just one more step: hooking our widget class into WordPress. All the functions above this went inside our class, but this line must go outside of the class. I usually place it just after the class’ closing bracket.

// register Recent Posts widget
add_action('widgets_init', create_function('', 'return register_widget("pippin_simple_recent_posts");'));

That’s it! You will now have a fully functional recent posts widget that includes options to control the Title, the Number of posts displayed, and the post Offset.

We will be continuing this Working With Widgets Series with ever more complex tutorials, so stay tuned!