Info

single posts.

Calendar

Categories

A calendar of your site's posts A list or dropdown of categories

A calendar of your site's posts A list or dropdown of categories

Figure 6.1. Our custom widget, as it appears in WordPress's admin section

However, if you drag the widget onto one of your widget-ready areas, you'll see that it lacks any customizable options, as shown in Figure 6.2.

There are no options for this widget.

Figure 6.2. Our newly defined widget has no options

We'd like our users to at least be able to set a custom title for the widget, so we should fill out the form and update functions to give us an options form. Let's start with the form method.

Fortunately, WordPress handles the creation of the form element; all you need to do is write the label and input elements specific to your option. These must be assigned specific id and name attributes in order to work correctly, but again WordPress has your back: your widget has functions called get_field_id and get_field_name that serve this purpose. Here's what our simple form looks like:

chapter_06/v4/wicked/widgets/author-data.php (excerpt)

function form($instance) {

<label for="<?php echo $this->get_field_id('title'); ?>">Title:

<input class="widefat"

id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text"

value="<?php echo attribute_escape($title); ?>" />

The function receives an $instance variable that represents the current widget, which will include the options that are currently set. So, to make sure the form displays the current value of the title, we first extract the $title variable from $instance.

Then we construct the form field, using $this->get_field_id and $this->get_field_name to set the field's id and name attributes. Other than that, this is fairly straightforward HTML. If you want your form to have more than one field, all you have to do is add them here, setting their attributes appropriately.

When the form is submitted, WordPress will use your update function to save the options the user has entered. Let's have a look at that next:

chapter_06/v4/wicked/widgets/author-data.php (excerpt)

function update($new_instance, $old_instance) { $instance = $old_instance;

$instance['title'] = strip_tags($new_instance['title']); return $instance;

The update function works a little differently: it receives two parameters, which hold a brand new widget containing the new options submitted in the form, and the old widget with the previous options, respectively. So we need to grab the title from $new_instance—being careful to strip out any HTML and PHP tags—and use that to set the title on our instance. To avoid confusion, we've dumped $old_instance into a new variable simply called $instance, and that's where we set the new title. Then we return $instance, and WordPress handles the rest, updating the widget with the options we've set.

If your form has more than one field, just repeat this process for each option that requires setting. You can include as much logic as you want in update. If ever you'd like to discard the new options (based on some condition), all you have to do is return false and the widget won't be updated.

Now that we have our options form, test it out: go back to your widgets admin page, and drag the Author Data widget onto one of the widget areas. You should see your new title form, as shown in Figure 6.3.

Author Data

Title:

About the Author Delete | Close

Figure 6.3. A simple widget options form

That's three out of four functions defined: we have our constructor, as well as the form and update methods for handling our widget options form. Now all that's to be done is tell WordPress how to display the widget!

Here's what that function will look like:

chapter_06/v4/wicked/widgets/author-data.php (excerpt)

function widget($args, $instance) { extract($args, EXTR_SKIP); Q

echo $before_widget; Q

$title = apply_filters('widget_title', $instance['title']) ; Q

if ( !empty( $title ) ) { echo $before_title . $title . $after_title; }; 0 echo '<div class="author-data">1 ;

echo get_avatar(get_the_author_meta(1user_email1), 150); @ echo '<h4>' . the_author_meta('display_name') . '</h4>'; // Is there an author description? if (get_the_author_meta('description')) { echo '<div class="description"><p>'

. get_the_author_meta('description') ■ '</p></div>';

echo $after_widget; Q

Your function receives two parameters: the first one is $args, which is an array of the arguments provided to all widgets in your theme. They will be familiar to you: before_title, after_title, before_widget, and after_widget. The second parameter is our old friend $instance, which contains all the options set on your widget. In our case that's only the title.

Here's a breakdown of what's going on in there:

^ First, we're using PHP's handy extract2 function to break up the $args array into individual variables. So, from now on, instead of typing $args['before_title'], we can just use $before_title. Feel free to copy and paste this line into all your own widgets, or remove it if you prefer the more explicit $args['before_title'] style.

We only want to display our widget on single post pages: that's really the only place where it makes sense!

Q We echo out the standard before_widget string: if you've been following along with the rest of this chapter, you'll have guessed this should be Thematic's standard opening <div> tag.

Q We pass the title provided by the user ($instance['title']) through any filters applied to widget_title by our theme or any plugins.

0 As long as the title has content in it, we'll output it as well as the $before_title and $after_title values.

Q We use the get_the_author_meta3 function a few times to grab the information we want to display about the author. In this case, we're retrieving the author's email to pass into get_avatar.

Q Finally, we output the after_widget value.

Now that you've written all the functions required for your widget, it should correctly display the author info on single-post pages. Give it a try!

Here's the full author-data.php file:

chapter_06/v4/wicked/widgets/author-data.php (excerpt)

<?php class Author_Data_Widget extends WP_Widget { function Author_Data_Widget() { $widget_ops = array(

'description' => 'A widget that displays author info on single posts.'

2 http://php.net/manual/en/function.extract.php

3 http://codex.wordpress.org/Function_Reference/get_the_author_meta

$this->WP_Widget('author_data', 'Author Data', $widget_ops);

function form($instance) {

<label for="<?php echo $this->get_field_id('title'); ?>">Title: <input class="widefat"

id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text"

value="<?php echo attribute_escape($title); ?>" />

function update($new_instance, $old_instance) { $instance = $old_instance;

$instance['title'] = strip_tags($new_instance['title']); return $instance;

function widget($args, $instance) { extract($args, EXTR_SKIP);

echo $before_widget;

$title = apply_filters('widget_title', $instance['title']);

if (!empty($title)) { echo $before_title . $title . $after_title; }; echo '<div class="author-data">';

echo get_avatar(get_the_author_meta('user_email'), 150); echo '<h4>' . the_author_meta('display_name') . '</h4>';

// Is there an author description? if (get_the_author_meta('description')) { echo '<div class="description"><p>'

. get_the_author_meta('description') ■ '</p></div>';

register_widget('Author_Data_Widget'); ?>

Was this article helpful?

0 0

Post a comment