The other place where we need to customize our widget's content is in the
manager—we need to provide a custom form for editing our widget's options. Let's start by adding a single option for the title. In order to do this, we need to implement another function in our widget and add some options:
1. Create a form() function that prints out some HTML. Later, this function will print out some HTML form elements, but for now, let's just make sure this works. Add the following function to your ContentRotatorWidget.php file:
/**
* Displays the widget form in the manager, used for editing its settings
*
* @param array $instance The settings for the particular instance of the widget
* @return none No value is returned directly, but form elements are printed.
*/
function form( $instance ) {
print "Form elements go here";
}
2. Save your file and refresh your manager page. You should see your handiwork when you open your widget for editing:
You may be thinking that all we need to do is print some form elements here, but the process here is deceptively complex because we need to handle multiple instances (and multiple HTML forms) of your widget. Each form element must have a unique name and ID. What to do? We let WordPress handle it via the WP_Widget class' get_field_id() and get_field_name() functions. We are going to build a simple template that allows you to adjust your form elements, and we will feed it the $control_options that we defined at the top of our ContentRotatorWidget class. Let's add a control option now.
3. Update your ContentRotatorWidget class and edit the $control_options array so we have a control option for "title". Later, we can expand this array to include as many options as our widget requires.
/* List all controllable options here along with a default value.
The values can be distinct for each instance of the widget. */
public $control_options = array(
'title' => 'Content Rotator', );
4. It's finally getting to the point where we need some helper functions that do things that are not directly related to this widget. We need to put the functions somewhere, but they don't necessarily belong in the ContentRotatorWidget class. So let's create a new class named ContentRotator, and save it inside the content-rotator/includes/
directory as ContentRotator.php. The following is what our ContentRotator.php looks like:
<?php /**
* ContentRotator
*
* Helper functions that assist the ContentRotatorWidget class
*/
class ContentRotator {
} /*EOF*/
It's empty for now. We will be adding a handful of functions to it later, but first let's test it.
5. Update the content-rotator/index.php file so it includes your new class.
Add the following line to your index.php file:
include_once('includes/ContentRotator.php');
Save your work and refresh your homepage to check for any errors. You should now have a helper class hooked up and ready for use.
6. The first helper function we are going add to ContentRotator.php is one we've used before: a simple parsing function. This lets us use simple templates and [+placeholders+] in order to avoid the confusing mess of PHP concatenation.
Add this static function to the ContentRotator class:
/**
* parse *
* A simple parsing function for basic templating.
*
* @param $tpl string A formatting string containing [+placeholders+]
* @param $hash array An associative array containing keys and values e.g. array('key' => 'value');
* @return string Placeholders corresponding to the keys of the hash will be replaced with the values the resulting string will be returned.
Save your work, refresh your homepage, and verify that no errors occurred.
7. Add a tpls/ folder to your plugin's folder if you haven't already, and add a widget_controls.tpl file that contains the following text:
<!--
This .tpl file is used when editing a widget's options in the WP manager.
It should only contain form *elements*; WordPress will supply the opening and closing <form> tags.
For each key in the ContentRotatorWidget::$control_options array, you will have
the following placeholders available:
[+your_key.id+] - used inside id attributes, e.g.
id="[+your_key.id+]"
[+your_key.name+] - used inside name attributes, e.g.
name="[+your_key.name+]"
[+your_key.value+] - contains the current value of the option
WordPress appends text to the names and id's to allow for multiple instances
of the widget, so don't try hard-coding values here.
-->
<label for="[+title.id+]">Title</label><br/>
<input id="[+title.id+]" name="[+title.name+]" value="[+title.
value+]" /><br/>
Notice that we've included a comment with some basic instructions for how to use this file. This is an important concept when it comes to good documentation: put the documentation where people need it.
We're preparing a system that can handle more complex widgets. The placeholders are pretty easy to read, and there's no danger of crashing PHP with a bad concatenation because it's only a text file—it does not execute.
Any frontend designer would be comfortable editing this template, and that's a big deal. Consistently throughout this book, we want to separate the logic from the presentation layer as much as possible because it makes for better code and better HTML.
We still need to hook this template up to the wagon, so let's update our form() function next so it outputs some form elements instead of just static text.
8. After the footwork of adding a helper class, we're ready to beef up the form() function in the ContentRotatorWidget class. Update the function so it looks like the following:
/**
* Displays the widget form in the manager, used for editing its settings
*
* @param array $instance The settings for the particular instance of the widget
* @return none No value is returned directly, but form elements are printed. */
public function form( $instance ) {
$placeholders = array();
foreach ( $this->control_options as $key => $val ) {
$tpl = file_get_contents( dirname(dirname(__FILE__)) .'/tpls/
widget_controls.tpl');
print ContentRotator::parse($tpl, $placeholders);
}
Save your work and refresh your admin page. We have just put together a handful of moving parts, so it may take a little debugging before they all work together. We are making use of the helper class' ContentRotator::parse() function, and we are also using PHP's __FILE__ constant, which returns the name of the current file (ContentRotatorWidget.php). We use this in order to get a full path to the widget_
controls.tpl file.
We are utilizing the parent class' get_field_id() and get_field_name() functions.
We call them using the $this variable. Since our child class does not contain these functions, PHP looks for these functions in the parent class. This is how we let WordPress handle the naming and identification of form fields. This ensures that we don't get into trouble when we have several instances of our widget active.
Once it all works, head to the widget administration page in your browser, and try adding a title to your activated widget. The default title, by the way, comes from the value you set back in the $control_options array at the top of ContentRotatorWidget.php. You may need to deactivate the widget and then drag a new instance into the primary widget area before everything refreshes. Remember to refresh your admin page frequently when developing widgets! Enter a new title for the widget instance and try saving it.
If you got this all working, then take a deep breath and congratulate yourself.
You have built a reusable component for your widgets, and it follows some good architectural design. That's no small feat! The next step is to tackle this widget's namesake—we need to generate some random content and put it into rotation.