With the release of WordPress 2.8 came a new (and greatly improved) Widget API. Previously, developing widgets was a confusing and messy experience. With the new Widgets API, developing widgets becomes a more streamlined process in a nice and structured way.
The process to create a widget involves creating class that extends the Widget API class. Then you create a couple of functions, which gets passed parameters useful to your widget creation. Let’s take a look at the basic structure:
[php]class WP_Widget_Name extends WP_Widget {
function WP_Widget_Name() {
$widget_ops = array(‘classname’ => ‘widget_name’, ‘description’ => __( ‘A short description of your widget.’) );
$this->WP_Widget(‘name’, ‘Name’, $widget_ops);
}
function widget ( $defaults, $options ) {
}
function update ( $new_options, $old_options ) {
}
function form ( $options ) {
}
}
add_action( ‘widgets_init’, ‘my_widget_name_init’);
function my_widget_name_init() {
register_widget( ‘WP_Widget_Name’ );
}[/php]
Let’s take a look at the inner workings of this structure:
WP_Widget_Name is the name of your widget class. Replace name with the name of your widget. While you could certainly name this using any format, the WP_Widget_* format is recommended for consistency.
WP_Widget_Name() – this function needs to be named the same as your class (so PHP will automatically execute it when it starts executing the class). In this function we setup our widget’s details. widget_name is the name of your class, in lowercase, without the WP part.
widget() – this is where you will output (echo) your widget to be display in the theme’s sidebar. The first parameter passed ($defaults contains the before_widget, after_widget, before_title and after_title settings defined by the theme. The second parameter ($options) is an associative array containing all the options associated with your widget.
update() – this function will be executed when the widget’s options form has been submitted. You’re passed the new options and the previous options. You’re expected to return an associative array of which options you want to be updated (and their values).
form() – this is where you will output (echo) your widget’s options form. You’re passed an associative array of the current option’s values. Leave out the form tag and submit button, these will be added automatically. Use $this->get_field_name(‘field_name’) for generating the name of your fields, which will be used as the option name.
The last part is where you register your widget with the API.
Now, let’s look at a basic example that takes two fields and displays them. You may want to check if the options are empty and sub-in defaults in your own widgets.
[php]class WP_Widget_Example extends WP_Widget {
function WP_Widget_Example() {
$widget_ops = array(‘classname’ => ‘widget_example’, ‘description’ => __( ‘This is an example widget.’) );
$this->WP_Widget(‘example’, ‘Example’, $widget_ops);
}
function widget ( $defaults, $options ) {
extract( $args );
echo $before_widget . $before_title . $options['title'] . $after_title;
echo $options['field1'] . ‘<br />’ . $options['field2'];
echo $after_widget;
}
function update ( $new_options, $old_options ) {
return $new_options;
}
function form ( $options ) {
echo ‘<p><label for="’ . $this->get_field_id(‘title’) . ‘">Title</label> <input type="text" name="’ . $this->get_field_name(‘title’) . ‘" id="’ . $this->get_field_id(‘title’) . ‘" class="widefat" value="’ . $options['title'] . ‘" /></p>
<p><label for="’ . $this->get_field_id(‘field1′) . ‘">Field 1</label> <input type="text" name="’ . $this->get_field_name(‘field1′) . ‘" id="’ . $htis->get_field_id(‘field1′) . ‘" class="widefat" value="’ . $options['field1'] . ‘"/></p>
<p><label for="’ . $this->get_field_id(‘field2′) . ‘">Field 2</label> <input type="text" name="’ . $this->get_field_name(‘field2′) . ‘" id="’ . $htis->get_field_id(‘field2′) . ‘" class="widefat" value="’ . $options['field2'] . ‘"/></p>’;
}
}
add_action( ‘widgets_init’, ‘my_widget_example_init’);
function my_widget_example_init() {
register_widget( ‘WP_Widget_Example’ );
}[/php]
There you have it, a WordPress widget that utilized the new Widget API in WordPress 2.8.
