Wordpress Plugin Tutorial

Your first widget

I don’t like tutorials that spend too long talking so we are going to leap straight into the code. This is a minimal widget. It displays a hard coded widget title and widget body text. This code only works in Wordpress versions 2.8 or later.

<?php
/*
Plugin Name: TKSL Tutorial Example 1
Plugin URI: http://tkslmedia.co.uk/plugin/tutorial1
Description: Minimal Widget to introduce concepts
Author: Jon Knight
Version: 1.0
Author URI: http://tkslmedia.co.uk/
*/

add_action('widgets_init', 'tksl_tutorial_1_init');

function tksl_tutorial_1_init()
{
   register_widget('TKSL_Tutorial_1_Widget');
}

class TKSL_Tutorial_1_Widget extends WP_Widget {

function  TKSL_Tutorial_1_Widget() {
     $widget_ops = array( 'classname' => 'tksl_tutorial_1', 'description' => 'Tutorial 1' );
     $control_ops = array( 'width' => 300, 'height' => 350, 'id_base' => 'tksl-tutorial-1' );
     $this->WP_Widget( 'tksl-tutorial-1', 'TKSL Tutorial 1', $widget_ops, $control_ops );
}

function widget($args, $instance)
{
           extract($args);
           $title = "Tutorial 1 Title";
           $text =  "Tutorial 1 Body Text";

           echo $before_widget;
           echo $before_title . $title . $after_title;
           echo $text;
           echo $after_widget;
}

}
?>

Installing the widget

I don’t propose to teach you to suck eggs. Put the code above in a subdirectory of the plugins directory and activate it through the Wordpress Admin interface. There is plenty more on plugins here.

How does it work

We’ll look at this code in sections.

<?php
/*
Plugin Name: TKSL Tutorial Example 1
Plugin URI: http://tkslmedia.co.uk/plugin/tutorial1
Description: Minimal Widget to introduce concepts
Author: Jon Knight
Version: 1.0
Author URI: http://tkslmedia.co.uk/
*/

This code is the plugin header. This allows Wordpress to see the plugin when you copy it into the plugin directory. There is more information about the header here.

class TKSL_Tutorial_1_Widget extends WP_Widget {

This line has made our life much much easier. WP_Widget is a base class will all the Widget functionality already written for us. That means our Widget can inherit from it and we don’t have to reinvent the wheel.

If you don’t understand the term inheritance, try reading this good tutorial about Object Orientated PHP.

function  TKSL_Tutorial_1_Widget() {
     $widget_ops = array( 'classname' => 'tksl_tutorial_1', 'description' => 'Tutorial 1' );
     $control_ops = array( 'width' => 300, 'height' => 350, 'id_base' => 'tksl-tutorial-1' );
     $this->WP_Widget( 'tksl-tutorial-1', 'TKSL Tutorial 1', $widget_ops, $control_ops );
}

This function is the constructor and must have the same name as your Widget Class (Unless you are happy to go pure PHP5 whereupon it could be __construct). The constructor is a wrapper to the WP_Widget constructor.

* @param string $id_base Optional Base ID for the widget, lower case,
* if left empty a portion of the widget’s class name will be used. Has to be unique.
* @param string $name Name for the widget displayed on the configuration page.
* @param array $widget_options Optional Passed to wp_register_sidebar_widget()
* – description: shown on the configuration page
* – classname
* @param array $control_options Optional Passed to wp_register_widget_control()
* – width: required if more than 250px
* – height: currently not used but may be needed in the future

http://core.trac.wordpress.org/browser/trunk/wp-includes/widgets.php

function widget($args, $instance)
{
           extract($args);
           $title = "Tutorial 1 Title";
           $text =  "Tutorial 1 Body Text";

           echo $before_widget;
           echo $before_title . $title . $after_title;
           echo $text;
           echo $after_widget;
}

Widget overrides a method of the WP_Widget class. It is the method invoked to display the widget. $args is the standard parameters passed to every widget. The extract function call populates $before_widget, $after_widget, $before_title and $after_title. $instance holds the parameters unique to this widget; but we will cover that later on.

That block of echo statements will be used for pretty well every widget – just the title and text values get more exciting later. Failure to use $before_widget, $after_widget, $before_title and $after_title is liable to break your themes.

add_action('widgets_init', 'tksl_tutorial_1_init');

function tksl_tutorial_1_init()
{
   register_widget('TKSL_Tutorial_1_Widget');
}

The widgets_init hook is fired after the default Wordpress widgets have been loaded. This the add_action call means tksl_tutorial_1_init() is called after the Widgets system has been initialised.

register_widget takes a class name as a parameter and does what it suggests. It registers the widget so that it is visible on the Widgets Admin Page, so you can add it to a sidebar.

We now have a working widget. In Part 2 we will be adding parameters so you can change the title and body text on the Widgets Admin Page.