Advanced WordPress Widgets
The Widget Class
There are several ways to set up a widget, but by far the best method is to use a CLASS structure. By creating a PHP class for our widget, it makes it very easy to create as many widgets as you wish, without having to worry about conflicting function names. You can simply duplicate the code from your first widget, rename the class, and you’re done! So we are going to use a class for our example widget, and it starts like this:/**
* Example Widget Class
*/
class pippin_example_widget extends WP_Widget {
// all of our widget code will go here
}
You can name the class anything you want, but I would advise you to
be meaningful in your naming convention. “My Awesome Widget” really
doesn’t tell you anything, even though it probably is awesome. I always
go for names that explain the widget’s function, such as
“blog_authors_widget”. It is also a good practice to always prefix your
class names, just as you should prefix your function names. This is to
help avoid the possibility of conflicts with other developer’s functions
or class names. So our example widget class name is
“pippin_example_widget”.The Widget Functions
Now that we have our widget class, we will begin filling it with the various functions we need to construct our widget. There will be four functions total:- pippin_example_widget()
- widget()
- update()
- form()
The Constructor Function
The first function we will write is pippin_example_widget(), and yes, it should be named the same as your widget class. This is a very simple, short function that constructs our widget and gives it a name./** constructor */
function pippin_example_widget() {
parent::WP_Widget(false, $name = 'Example Widget');
}
The only thing you should ever need to change with this function is the $name variable. This variable determines the name that appears on the widget in the admin widgets panel.The Widget Output
Next comes the function that controls the widget’s output to the front end of the site. This function can contain just about anything you want, including HTML, CSS, jQuery, PHP, and more. Because this function does not have many set constraints on what you can do with it, I’m just going to show you examples of how you can use it.First of all, our base function is going to look something like this:
/** @see WP_Widget::widget */
function widget($args, $instance) {
extract( $args );
// these are our widget options
$title = apply_filters('widget_title', $instance['title']);
$text = $instance['text'];
$checkbox = $instance['checkbox'];
$textarea = $instance['textarea'];
$select = $instance['select'];
echo $before_widget;
if ( $title ) {
echo $before_title . $title . $after_title;
}
echo $after_widget;
}
There are several important things going on here. First of all, the
two parameters passed to the function are used to retrieve the saved
options that we have set on the widget panel (don’t worry, we haven’t
actually gotten there yet). These two parameters should never change,
and nor should the extract($args) function call just after the opening }.The next couple lines are the widget options. The options are all stored in the $instance parameter, which is an array, so I have set up a unique variable name for each option.
- $title – This is the main widget title
- $text – This is our sample text input field
- $checkbox – This is our sample checkbox field
- $textarea – This is our sample textarea field
- $select – This is our sample select menu
The widget() function above as it is will do nothing more than display the widget title, so we are going to want to make it a little more advanced. I said earlier that you can do just about anything with this function that you want. That’s because it is the function that controls the output of our widget on the front end of the site. We are going to use our option (defined a moment ago) to control the exact output of the widget
/** @see WP_Widget::widget */
function widget($args, $instance) {
extract( $args );
// these are our widget options
$title = apply_filters('widget_title', $instance['title']);
$text = $instance['text'];
$checkbox = $instance['checkbox'];
$textarea = $instance['textarea'];
$select = $instance['select'];
echo $before_widget;
// if the title is set
if ( $title ) {
echo $before_title . $title . $after_title;
}
// if the text field is set
if ( $text ) {
echo '
<div class="widget-text">' . $text . '</div>
';
}
// if the checkbox is checked
if ( $checkbox == true ) {
echo '
This message is displayed if our checkbox is checked.
';
}
// if text is entered in the textarea
if ( $textarea ) {
echo '
<div class="widget-textarea">' . $textarea . '</div>
';
}
// output text depended on which option is picked
if ( $select == 'one' ) {
echo '
Option One is Selected
';
} else if ( $select == 'two' ) {
echo '
Option Two is Selected
';
} else {
echo '
Option Three is Selected
';
}
echo $after_widget;
}
What I have done is use the option values to control what is
displayed. For example, I checked to see if the CHECKBOX field was
checked (or had a value of TRUE), and if it was, display a message. I
also displayed a different message for each SELECT menu option. These
are all really, really simple examples but they convey a very important
point: by utilizing your widget options (and a little bit of syntax) you
can display anything you want inside of a widget.While I have left the output to nothing more than simple text messages, you can just as easily use the options to control a post query, just as I did with my Better Recent Posts Widget.
Saving the Widget Options
The next function in our widget class is the update() function. This one does nothing more than save the options chosen from the widgets panel. It’s a very simple function./** @see WP_Widget::update */
function update($new_instance, $old_instance) {
$instance = $old_instance;
$instance['title'] = strip_tags($new_instance['title']);
$instance['text'] = strip_tags($new_instance['text']);
$instance['checkbox'] = strip_tags($new_instance['checkbox']);
$instance['textarea'] = strip_tags($new_instance['textarea']);
$instance['select'] = strip_tags($new_instance['select']);
return $instance;
}
Remember how I told you that the widget options were stored in an array variable called $instance?
Well, this function takes two parameters, $old_instance which contains
all the option values already saved, and $new_instance which contains
all of the options that we have just updated. the function does nothing
more than take the old instance and set each value in the array equal to
the appropriate value in the new instance, thus saving our optionsIt is important to note that each of the instance variables matches those of the widget() function above. If your variable names do not match, your options will not save correctly.
There is only one more function to write, and that is the one that displays the widget options form in the widgets panel in the WordPress admin.
The Widget Options Form
Once again, there is nothing really special about this function, it simply outputs an HTML form with a field for each of our options. Let’s see the function, then I’ll explain parts of it. /** @see WP_Widget::form */
function form($instance) {
$title = esc_attr($instance['title']);
$text = esc_attr($instance['text']);
$checkbox = esc_attr($instance['checkbox']);
$textarea = esc_attr($instance['textarea']);
$select = esc_attr($instance['select']);
?>
<p>
<label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Widget 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 $title; ?>" />
</p>
<p>
<label for="<?php echo $this->get_field_id('text_field'); ?>"><?php _e('This is a single line text field:'); ?></label>
<input class="widefat" id="<?php echo $this->get_field_id('text_field'); ?>" name="<?php echo $this->get_field_name('text_field'); ?>" type="text" value="<?php echo $text_field; ?>" />
</p>
<p><
<input id="<?php echo $this->get_field_id('checkbox'); ?>" name="<?php echo $this->get_field_name('checkbox'); ?>" type="checkbox" value="1" <?php checked( '1', $checkbox ); ?>/>
<label for="<?php echo $this->get_field_id('checkbox'); ?>"><?php _e('This is a checkbox'); ?></label>
</p>
<p>
<label for="<?php echo $this->get_field_id('textarea'); ?>"><?php _e('This is a textarea:'); ?></label>
<textarea class="widefat" id="<?php echo $this->get_field_id('textarea'); ?>" name="<?php echo $this->get_field_name('textarea'); ?>"><?php echo $textarea; ?></textarea>
</p>
<p>
<label for="<?php echo $this->get_field_id('select'); ?>"><?php _e('This is a select menu'); ?></label>
<select name="<?php echo $this->get_field_name('select'); ?>" id="<?php echo $this->get_field_id('select'); ?>" class="widefat">
<?php
$options = array('one', 'two', 'three');
foreach ($options as $option) {
echo '<option value="' . $option . '" id="' . $option . '"', $select == $option ? ' selected="selected"' : '', '>', $option, '</option>';
}
?>
</select>
</p>
<?php
}
This function takes one $instance parameter, which allows our HTML
form to read the saved options. The HTML form in this function is very
straight forward, so if you have questions about it, please ask in the
comments. I would like to explain how we connect each FORM field with
its corresponding option, and how we ensure that the value entered (or
selected) in each field is saved correctly.There are several key functions used inside of this form() function:
- $title – This is the main widget title
- $text – This is our sample text input field
- $checkbox – This is our sample checkbox field
- $textarea – This is our sample textarea field
- $select – This is our sample select menu
The only other part to the options form that might be a little confusing is the way that the SELECT field is set up. After we’ve done the normal field name and ID stuff, as described a moment ago, we use a FOREACH loop to display the options available in this SELECT menu. We use the foreach loop because we need to have a way of making the saved option as the selected option when we load the page, and because it is much more efficient than simply writing out each option. In order to mark the correct option as selected when the page loads, we use the conditional that looks like this:
foreach ($options as $option) {
echo '<option value="' . $option . '" id="' . $option . '"', $select == $option ? ' selected="selected"' : '', '<', $option, '</option<';
}
This essentially says: display the option value and id, and if it
matches the value of the option saved in the database (remember our
$instance variable), include the selected=”selected” attribute.And that’s it for our widget options form. This also marks the end of our widget class, which means that there is only one more step before our widget is available to use in WordPress.
Activating the Widget
Our widget is built, it’s options can be saved, and all we need to do is turn it on. To do that, we use the add_action() function to hook our widget into WordPress.// register example widget
add_action('widgets_init', create_function('', 'return register_widget("pippin_example_widget");'));
This hook will register our widget and make it available for use.
Note that the parameter passed to the register_widget() function inside
of the hook is the same as our widget class name. If you use a different
value than the name of your widget class, the widget will not work.That’s everything! Keep reading below to see the complete code for an actually useful widget that you can use to display your blog authors.
Simple Blog Authors Widget
To help provide “real world” sense to this tutorial, I’m providing the code for a complete widget that will provide a simple widget that can be used to list your blog authors. The widget includes options for:- Widget Title
- Author Gravatars
- Author Post Counts
The widget code:
/**
* Authors Widget Class
*/
class pippin_simple_authors_widget extends WP_Widget {
/** constructor */
function pippin_simple_authors_widget() {
parent::WP_Widget(false, $name = 'Simple Authors Widget');
}
/** @see WP_Widget::widget */
function widget($args, $instance) {
extract( $args );
global $wpdb;
$title = apply_filters('widget_title', $instance['title']);
$gravatar = $instance['gravatar'];
$count = $instance['count'];
if(!$size)
$size = 40;
?>
<?php echo $before_widget; ?>
<?php if ( $title )
echo $before_title . $title . $after_title; ?>
<ul>
<?php
$authors = $wpdb->get_results("SELECT ID FROM $wpdb->users ORDER BY ID");
foreach($authors as $author) {
$author_info = get_userdata($author->ID);
echo '<li>';
echo '<div style="float: left; margin-left: 5px;">';
echo get_avatar($author->ID, 40);
echo '</div>';
echo '<a href="' . get_author_posts_url($author->ID) .'" title="View author archive">';
echo $author_info->display_name;
if($count) {
echo '(' . count_user_posts($author->ID) . ')';
}
echo '</a>';
echo '</li>';
}
?>
</ul>
<?php echo $after_widget; ?>
<?php
}
/** @see WP_Widget::update */
function update($new_instance, $old_instance) {
$instance = $old_instance;
$instance['title'] = strip_tags($new_instance['title']);
$instance['gravatar'] = strip_tags($new_instance['gravatar']);
$instance['count'] = strip_tags($new_instance['count']);
return $instance;
}
/** @see WP_Widget::form */
function form($instance) {
$title = esc_attr($instance['title']);
$gravatar = esc_attr($instance['gravatar']);
$count = esc_attr($instance['count']);
?>
<p>
<label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('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 $title; ?>" />
</p>
<p>
<input id="<?php echo $this->get_field_id('count'); ?>" name="<?php echo $this->get_field_name('count'); ?>" type="checkbox" value="1" <?php checked( '1', $count ); ?>/>
<label for="<?php echo $this->get_field_id('count'); ?>"><?php _e('Display Post Count?'); ?></label>
</p>
<p>
<input id="<?php echo $this->get_field_id('gravatar'); ?>" name="<?php echo $this->get_field_name('gravatar'); ?>" type="checkbox" value="1" <?php checked( '1', $gravatar ); ?>/>
<label for="<?php echo $this->get_field_id('gravatar'); ?>"><?php _e('Display Author Gravatar?'); ?></label>
</p>
<?php
}
} // class utopian_recent_posts
add_action('widgets_init', create_function('', 'return register_widget("pippin_simple_authors_widget");'));
Once again, you can download the complete Simple Authors Widget plugin from Pippin’s Plugins.com. Enjoy!
No hay comentarios:
Publicar un comentario