Widgets For Dummies?

[JohnM]

Simple widget generator:
http://programming.has.no.com/widgettemplate/

Its pre 2.8 though, isnt it ?

[JohnM]

This is great stuff! I haven't tried making a widget since the new interface was introduced and I hadn't yet gotten around to figuring out what all the changes are.

An Advanced Widget Template builder should fit in nice with Pixopoint business model I would assume ?
( check my post above )

[Otto]

What Dan said.

Also:

What is "classname"? Can it be anything, or is there some standard nomenclature?

classname is what gets put into the class of the surrounding tags for the widget when it's displayed. This is for styling. It can be anything, but generally widget_whatever is preferred.

What are the arguments for $this->WP_Widget? Particularly, what are the first two?

$this->WP_Widget('basic', 'Basic', $widget_ops);

The first one is an internal identifier, must be unique. Second one is the name of the widget as displayed on the widget page. Third is the options for the widget in an array (classname and description).

 <p> BASIC! </p> 
  

When replacing BASIC! with my code, can it be anything, including PHP, HTML, and (especially) javascript?

Yes.

If it can be PHP, can I use an include, to include a PHP file that contains the code, or is it better to copy/paste the contents directly into the function here?

Includes are fine, but it's generally more acceptable to make the whole thing into a single file for a plugin. You can define your own functions and call them from here, if you like.

I'll post an explanation of that code here shortly.

[Otto]

 <?php
 class WP_Widget_Basic extends WP_Widget {

    function WP_Widget_Basic() {
        $widget_ops = array(
        'classname' => 'widget_basic', 
        'description' => 'Basic Widget, no options except title' );
        $this->WP_Widget('basic', 'Basic', $widget_ops);
    }  

The above basically just defines the widget to WordPress. It gives it a classname for display, and a description to show in the back end. It also gives it a name "Basic" and an internal identifier "basic".

function widget( $args, $instance ) {
        extract($args);
        $title = apply_filters('widget_title', empty($instance['title']) ? 'Basic' : $instance['title']);

        echo $before_widget;
        if ( $title )
            echo $before_title . $title . $after_title;
?>
<p> BASIC! </p>
<?php
        echo $after_widget;
    }  

Now we have the guts of the widget. This displays the actual content onto the sidebar. First, it extracts the arguments from the widget system. These are things like before_widget, after_widget, before_title, after_title. Basically, these are defined by the declaration of the widget sidebars in the theme. The widget uses them in order to conform to the way the theme wants it to behave.

Next, it checks for the title of the widget in the instance. This is a multi-widget, there can be more than one of it. Each copy of the widget is a separate instance, and this instance of it is passed in.

Finally, it outputs the widget itself. The before, the title, the code, then the after. Easy.

     function update( $new_instance, $old_instance ) {
        $instance = $old_instance;
        $instance['title'] = strip_tags($new_instance['title']);

        return $instance;
    } 
  

This is the update function, which receives the data passed to it from the configuration form. It gets a copy of the new data in new_instance and a copy of what the data used to be in old_instance. Here, it takes the old data, replaces the title with the title recieved from the form, then returns the changed instance. Each form input should be processed similarly.

function form( $instance ) {
        $instance = wp_parse_args( (array) $instance, array( 'title' => '' ) );
        $title = strip_tags($instance['title']);
?>
            <p><label for="<?php echo $this->get_field_id('title'); ?>">Title:</label> <input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo esc_attr($title); ?>" /></p>
<?php
    }  

Finally, we have the form itself. It receives a copy of the instance, which it cleans up a bit and uses to populate the form. You can see that building the form uses the get_field_id and get_field_title functions, this is to create the proper ids and names for form elements so that the data, when saved, comes back to the correct instance of the widget. The form itself, you'll note, has no extra formatting. The only thing used is the class of "widefat" on the input. This allows the natural styling of the widget admin page to control the display of the form elements, and lets it fit inside the box.


If you were to add more form elements, you'd do three things:
1. Add the input into the form function.
2. Process the input in the update function (clean it up, put it into the instance).
3. Use it in the widget function (get it from the instance, echo it, or whatever).

[Ryan]

An Advanced Widget Template builder should fit in nice with Pixopoint business model I would assume ?
( check my post above )

I don't think that would be particularly useful though. It would be far too complex to make a useful widget builder. Any widget template creator would be very simplistic and anyone creating a useful widget is likely to know enough PHP to be able to hack their way around making one from scratch anyway I imagine.

[chipbennett]

Here is some info on how to edit the code above:

• Replace "WP_Widget_Basic" with the name of your widget code, but also state that it is a widget. No spaces or dashes. Try to keep it short and descriptive. This is often the name of your widget "in code form", i.e the average person will never see it.
• Replace "widget_basic" with the name of your widget code, but also state that it is a widget. This will be used as a style ID. No spaces, keep it short and descriptive. People often replace the underscores with dashes, because it a CSS thing.
• Replace "Basic Widget, no options except title" with a short description of what the widget is or does. This will be seen by people.
• Replace "basic" with the name of the widget, do not state that it is a widget. This is not seen by the average person.
• Replace "Basic" with the name of the widget, do not state that it is a widget. This will be seen through the WordPress backend and is the main title of the widget.
• Each option that the widget has will have a name, the value of that option can be accessed by putting the name in "$instance['title']", in this case the name was "title".
• The line "<p> BASIC! </p>" is the actual output of the widget on the web page. You can use any type of code here as long as it follows the coding rules, e.g. don't use PHP outside of the <?php ?> tags. It's often best to define CSS and JavaScript else where, i.e. the header and footer respectively. As for including files, you can do it here, but remember that all widgets can be used multiple times, but a PHP function can only be defined once.
• The update function in most cases doesn't need anything other than "return $new_instance;", but this example has some advanced stuff.

If I was to make a "Dan Cole" widget, it's PHP Class name would be "Dan_Cole_Widget". It's viable name would be "Dan Cole". It's classname (CSS name) would be "dan-cole" and in other places I would refer to it as "dan_cole".

This was exactly the clarification I needed. Thanks!

I now have my left column widgetized, and its entire content included as custom, built-in widgets.

Thanks everyone for your help!

Do you think it would be worthwhile for me to summarize everything here into a tutorial?

[chipbennett]

 <?php
 class WP_Widget_Basic extends WP_Widget {
 
    function WP_Widget_Basic() {
        $widget_ops = array(
        'classname' => 'widget_basic', 
        'description' => 'Basic Widget, no options except title' );
        $this->WP_Widget('basic', 'Basic', $widget_ops);
    }  

The above basically just defines the widget to WordPress. It gives it a classname for display, and a description to show in the back end. It also gives it a name "Basic" and an internal identifier "basic".

function widget( $args, $instance ) {
        extract($args);
        $title = apply_filters('widget_title', empty($instance['title']) ? 'Basic' : $instance['title']);
 
        echo $before_widget;
        if ( $title )
            echo $before_title . $title . $after_title;
?>
<p> BASIC! </p>
<?php
        echo $after_widget;
    }  

Now we have the guts of the widget. This displays the actual content onto the sidebar. First, it extracts the arguments from the widget system. These are things like before_widget, after_widget, before_title, after_title. Basically, these are defined by the declaration of the widget sidebars in the theme. The widget uses them in order to conform to the way the theme wants it to behave.

Next, it checks for the title of the widget in the instance. This is a multi-widget, there can be more than one of it. Each copy of the widget is a separate instance, and this instance of it is passed in.

Finally, it outputs the widget itself. The before, the title, the code, then the after. Easy.

     function update( $new_instance, $old_instance ) {
        $instance = $old_instance;
        $instance['title'] = strip_tags($new_instance['title']);
 
        return $instance;
    } 
  

This is the update function, which receives the data passed to it from the configuration form. It gets a copy of the new data in new_instance and a copy of what the data used to be in old_instance. Here, it takes the old data, replaces the title with the title recieved from the form, then returns the changed instance. Each form input should be processed similarly.

function form( $instance ) {
        $instance = wp_parse_args( (array) $instance, array( 'title' => '' ) );
        $title = strip_tags($instance['title']);
?>
            <p><label for="<?php echo $this->get_field_id('title'); ?>">Title:</label> <input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo esc_attr($title); ?>" /></p>
<?php
    }  

Finally, we have the form itself. It receives a copy of the instance, which it cleans up a bit and uses to populate the form. You can see that building the form uses the get_field_id and get_field_title functions, this is to create the proper ids and names for form elements so that the data, when saved, comes back to the correct instance of the widget. The form itself, you'll note, has no extra formatting. The only thing used is the class of "widefat" on the input. This allows the natural styling of the widget admin page to control the display of the form elements, and lets it fit inside the box.


If you were to add more form elements, you'd do three things:
1. Add the input into the form function.
2. Process the input in the update function (clean it up, put it into the instance).
3. Use it in the widget function (get it from the instance, echo it, or whatever).

Wow, thanks, Otto! This is awesome stuff!

[Ryan]

Do you think it would be worthwhile for me to summarize everything here into a tutorial?

Perhaps you could turn it into a guest blog post for the Tavern?

[chipbennett]

Perhaps you could turn it into a guest blog post for the Tavern?

Not a bad idea.

How does Jeff usually like those? Can it be a cross-post, or does he want original content only?

[Ryan]

I don't think he'd want duplicate content.

Here's the submission page ... http://www.wptavern.com/submit-a-post


I've always wondered what would happen if I submitted a guest post via that form but answered the question "what colour is the sky" with the actual answer, rather than just "blue" (it's usually grey here).