It's time to flesh out the widget() function. This is the function that prints out the content that is visible on the frontend, and we want it to print out some random content. We are going to approach this in phases so that we can test it.
1. Firstly, add a helper function to ContentRotator.php that generates some random content. For now, we're going to generate a random number. Later, we will pull up some random content from the database, but always keep things simple the first time around so you can test them. Add the following static function to ContentRotator.php:
/**
Fetch and return a piece of random content
*/
static function get_random_content() {
return rand(1, 1000000);
}
This relies on PHP's rand() function, and it returns a random number between one and 1,000,000. It will suffice for our current testing.
Before we go much further, let's "templatize" our widget output. This is another case where the solutions offered on most websites and in most books would have you concatenating a messy bunch of PHP and HTML, but we want to avoid that.
2. Create a new template file named widget.tpl inside your content-rotator/tpls/ directory:
What's all that about? Well, remember how the widget() function takes two arguments? Those arguments are directly related to the widget's output, and we are going to use those arguments to create [+placeholders+] so we can easily control the output and formatting of our widget. If you had added a print_r($args) statement to your widget() function, you can inspect the arguments that WordPress is sending this function:
// Output of print_r($args) from inside the widget() function;
Array (
[name] => Primary Widget Area [id] => primary-widget-area
[description] => The primary widget area
[before_widget] => <li id="contentrotatorwidget-6"
class="widget-container ContentRotatorWidget">
[after_widget] => </li>
[before_title] => <h3 class="widget-title">
[after_title] => </h3>
[widget_id] => contentrotatorwidget-6 [widget_name] => Content Rotator )
Changing what these arguments are is beyond the scope of this chapter, but we are going to allow you a way to use these values as you customize your widget display. Unfortunately, we can't provide documentation in a comment because it may throw things off. For example, if our widget were used to returning bits of Google Adsense JavaScript, they would still execute even if they were inside an HTML comment. However, we have an obligation to explain the format and purpose of this .tpl file to our users, so we are going to create a readme.txt file with further information.
3. Create a content-rotator/tpls/readme.txt file with the following instructions in it:
The file called widget_controls.tpl contains the form elements necessary to edit a widget's settings. See widget_controls.tpl for more instructions on using that file.
The widget.tpl template is used to format the output of the widget as it is seen by the outside world, for example, on your homepage.
There are 4 primary built-in placeholders which are dictated by the template in use:
[+before_widget+]
[+after_widget+]
[+before_title+]
[+after_title+]
There are also placeholders corresponding to the
ContentRotatorWidget::$control_options array keys. The values of these are bound to an instance of the widget, so two instances of the same widget may have completely different values. These placeholders include:
[+seconds_shelf_life+]
[+title+]
Lastly, the most important placeholder:
[+content+] -- contains the random text as defined in the plugin's administration page
There are additional placeholders created from the widget() function's $args array, for example:
Array (
[name] => Primary Widget Area [id] => primary-widget-area
[description] => The primary widget area
[before_widget] => <li id="contentrotatorwidget-6"
class="widget-container ContentRotatorWidget">
[after_widget] => </li>
[before_title] => <h3 class="widget-title">
[after_title] => </h3>
[widget_id] => contentrotatorwidget-6 [widget_name] => Content Rotator )
Each key in this array corresponds to a placeholder. For example [+name+] and [+id+] are placeholders you can use in your widget.
tpl file.
The documentation for the available placeholders occurs in this readme.txt file so that it does not display publicly.
We won't bother repeating ourselves and we'll assume you read the readme.
txt file—we have listed a few placeholders that we haven't implemented yet.
If our templating method is too unorthodox for you, have a look at the official documentation for more conventional examples: http://codex.wordpress.
org/Widgets_API.
4. Next, let's call the get_random_content() helper function in the ContentRotatorWidget.phpwidget() function so our widget can get some random content. Currently, our random content consists of a random number, but the important thing here is to get it so it displays on the frontend. Update the widget() function so it looks like the following:
/**
* Displays content to the front-end, using the tpls/widget.tpl template.
*
* @param array $args Display arguments
* @param array $instance The settings for the particular instance of the widget
* @return none No direct output. This should instead print output directly.
*/
public function widget($args, $instance) {
$placeholders = array_merge($args, $instance);
$placeholders['content'] = ContentRotator::get_random_
content();
$tpl = file_get_contents( dirname(dirname(__FILE__)) .'/
tpls/widget.tpl');
print ContentRotator::parse($tpl, $placeholders);
}
Save your work and refresh your homepage. You should now see a new random number each time you refresh your homepage. Furthermore, the format of the output should be entirely controlled by the widget.tpl file. To test this, you can edit it to include some additional HTML formatting, but we will leave that up to you.