No Widget Area …

… no problem! Thanks to the introduction of the_widget() function in WordPress 2.8 … and this post.

Using a sample plugin (download zip file below) I will show you a simple how-to that makes use of the_widget() function. There is no codex page at WordPress.org for this function as of this writing, but there are some references you can find:

• WordPress trac ticket #9701
• WordPress trunk reference

The “trunk” reference provides an easy to follow layout of the function:

the_widget (line 1291 in file ../wp-includes/widget.php)

Output an arbitrary widget as a template tag

    * since: 2.8

void the_widget (string $widget, [array $instance = array()], [array $args = array()])

    * string $widget: the widget's PHP class name (see default-widgets.php)
    * array $instance: the widget's instance settings
    * array $args: the widget's sidebar args

We are going to use the sample plugin to replace the values in the function. We will start with this:

<?php /* Using the_widget() to make a plugin template tag */
the_widget(
  string $widget,
  $instance = array(),
  $args = array ()
);
/* NB: This will not work ... yet! */ ?>

First we will replace the “string $widget” with the plugin class name (see line 19):

<?php
/*
Plugin Name: WPFirstAid Sample Widget
Plugin URI: http://wpfirstaid.com
Description: Plugin with multi-widget functionality that displays stuff ...
Version: 0.1
Author: Edward Caissie
Author URI: http://edwardcaissie.com/
*/

/* Add function to the widgets_init hook. */
add_action( 'widgets_init', 'load_my_wpfa_sample_widget' );
  
/* Function that registers our widget. */
function load_my_wpfa_sample_widget() {
	register_widget( 'WPFA_Sample_Widget' );
}

class WPFA_Sample_Widget extends WP_Widget {
  
	function WPFA_Sample_Widget() {
      /* Widget settings. */
  		$widget_ops = array('classname' => 'wpfa-sample', 'description' => __('Displays some stuff.'));
  		/* Widget control settings. */
  		$control_ops = array('width' => 200, 'height' => 200, 'id_base' => 'wpfa-sample');
  		/* Create the widget. */
  		$this->WP_Widget('wpfa-sample', 'WPFirstAid Sample', $widget_ops, $control_ops);
  	}
	
	function widget( $args, $instance ) {

The function now looks like this:

<?php /* Using the_widget() to make a plugin template tag */
the_widget(
  WPFA_Sample_Widget,
  $instance = array(),
  $args = array ()
);
/* NB: This will not work ... yet! */ ?>

Next we will replace the “$instance = array()” part of the function with the appropriate code from the sample (see lines 70-75), in this sample case simply start with the “$defaults” values:

	function widget( $args, $instance ) {
      extract( $args );
      /* User-selected settings. */
      $title        = apply_filters('widget_title', $instance['title'] );
      $choices      = $instance['choices'];
      $show_choices = $instance['show_choices'];
      $optionals    = $instance['optionals'];

      /* Before widget (defined by themes). */
      echo $before_widget;

      /* Title of widget (before and after defined by themes). */
      if ( $title )
        echo $before_title . $title . $after_title;

      /* Display stuff based on widget settings. */
      if ( $show_choices ) {
        echo $choices . ' is in ... step to your ' . $optionals;
      } else {
        echo __('No appointments today');
      }

      /* After widget (defined by themes). */
      echo $after_widget;
  }
  
	function update( $new_instance, $old_instance ) {
      $instance = $old_instance;
      
      /* Strip tags (if needed) and update the widget settings. */
      $instance['title']          = strip_tags( $new_instance['title'] );
      $instance['choices']        = strip_tags( $new_instance['choices'] );
      $instance['show_choices']   = $new_instance['show_choices'];
      $instance['optionals']      = $new_instance['optionals'];

      return $instance;
  }
  
  function form( $instance ) {
      /* Set default widget settings. */
      $defaults = array(
          'title'                 => __('WPFirstAid Sample'),
          'choices'               => 'The Doctor',
          'show_choices'          => true,
          'optionals'             => 'right'
      );
      $instance = wp_parse_args( (array) $instance, $defaults );
		?>
    
		<p>
			<label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e('Title:'); ?></label>

The function now looks like this:

<?php /* Using the_widget() to make a plugin template tag */
the_widget(
  WPFA_Sample_Widget,
  $instance = array(
        'title'                 => __('WPFirstAid Sample'),
        'choices'               => 'The Doctor',
        'show_choices'          => true,
        'optionals'             => 'right'
  ),
  $args = array ()
);
/* NB: This will not work ... yet! */ ?>

Now we just need to replace the last parameter, “$args = array()” with the appropriate information. Depending on the theme, and whether or not there exists widget areas in the theme, the simplest place to start is with clearing the standard widget arguments that reference before and after the widget, as well as before and after the widget title. The function will now look like this:

<?php /* Using the_widget() to make a plugin template tag */
the_widget(
  WPFA_Sample_Widget,
  $instance = array(
        'title'                 => __('WPFirstAid Sample'),
        'choices'               => 'The Doctor',
        'show_choices'          => true,
        'optionals'             => 'right'
  ),
  $args = array (
  'before_widget'   => '',
  'before_title'    => '',
  'after_title'     => '',
  'after_widget'    => ''
  )
);
/* NB: This will work, now! */ ?>

Just copy and paste into your theme; and, after making suitable changes to match your installed active plugin, it will now be used like a template tag!

Well Done! and, here is the sample plugin: WPFirstAid Sample Widget (190). Enjoy!

This post was inspired by this comment at BuyNowShop.com, thank you @finid.