Words I Write

I quickly gave up working with the WordPress Codex and found what I think is a better starting point from WPengineer.com. Widgets are broken down into three basic sections. The first section is the actual widget; what it’s doing and what it’s displaying. The middle section is how the updates are handled. When you save or update the widget WP will create or update an instance of the widget, these multiple instances of the widget are what allow you display the same widget in multiple places with different settings. The third section is for control, that’s where we’ll put the form that allows the user to control the widget options in the WP backend. The very basic structure looks like this:

    class My_RSS_Widget extends WP_Widget {
    function My_RSS_Widget() {
    //Constructor
    }
    function widget($args, $instance) {
    // prints the widget
    }
    function update($new_instance, $old_instance) {
    //save the widget
    }
    function form($instance) {
    //widgetform in backend
    }
    }
    register_widget('My_RSS_Widget');

Here we can see the three major sections of a widget. Although WPengineer says "The code is self-explanatory", I certainly didn’t find it to be, so I’ll try to help out a bit. When building a widget, what we are really doing is building an extension of the WP_Widget class already built into WP which is located in wp-includes/widgets.php. So let’s start with all the stuff before the first sections starts.

class Promo_Tooth extends WP_Widget {
    function Promo_Tooth() {
    $widget_ops = array('classname' => 'toothPromo', 'description' => 'Displays promo box with tooth icon' );
    $this->WP_Widget('promo_tooth', 'Promo - Tooth Icon', $widget_ops);
    }

So Promo_Tooth is the name of my widget, and $widget_ops takes an array that contains descriptive info for your widget. classname is the class that will be added to your widget and the description is the description the user will see on the backend. $this sets all the options for the widget, including what is passed to it from $widget_ops. The first argument is the id prefix for each widget instance, in my case sometime like promo_tooth-3 (WP auto increments each instance of the widget so you can access the widget with a unique id). The second argument is the title of your widget on the WP backend, and then finally you pass all the options assigned to $widget_ops to $this.

With the above options, you get something like this in the Widgets page of your admin panel.

Ok, so now to the first section of the widget code:

function widget($args, $instance) {
    extract($args, EXTR_SKIP);
    echo $before_widget;
    $title = empty($instance['title']) ? ' ' : apply_filters('widget_title', $instance['title']);
    $text = empty($instance['text']) ? ' ' : apply_filters('widget_text', $instance['text']);
    $link_url = empty($instance['link_url']) ? ' ' : apply_filters('widget_link_url', $instance['link_url']);
    $link_text = empty($instance['link_text']) ? ' ' : apply_filters('widget_link_text', $instance['link_text']);
    if ( !empty( $title ) ) { echo $before_title . $title . $after_title; };
    echo '<img src=".../images/tooth.png">';
    echo '<p>' . $text . '</p>';
    echo '<a href="' . $link_url . '">';
    echo $link_text . ' &raquo;';
    echo '</a>';
    echo $after_widget;
    }

So this is where the actual work is being done. For my widget this is fairly simple because I am simply displaying information the user has input into the widget form on the backend. The purpose of this widget is to remove all need to add any actual code to achieve a very specific and limited output. The extract function imports the vars in the array to the current symbol table, and the EXTR_SKIP argument tells the function not to overwrite duplicate vars. $before_widget and $after_widget are vars that set how your widgets display in the sidebar, there’s a good explanation of them in the WP Codex. The same is true for $before_title and $after_title. These are usually li or h2 tags that control the display and layout of widgets within the theme. Make sure you are using these or your layout will be completely messed up. You can always override the display of an element using CSS.

Then all we are doing is defining our vars for use in the output, the vars will be set later by user input in the form section, after our vars are defined we can simply echo the desired output. This is a simple case obviously, because all we are doing is outputting user inputted strings with a little extra HTML around it. But this is where you would put whatever function you would like to perform before displaying data. So after you are done echoing, just make sure you echo $after_widget to append your closing li tags (or whichever tag your theme uses to organize a sidebar or widget area).

I think that’s enough for now, I’ll tackle the rest of the widget tomorrow.