Let's face it: a static manager page isn't very useful for anything other than testing.
We want to use this page to add our custom content, so what we really need on it is a form. There are many ways to store content and randomize it, and what we are going to show you isn't necessarily the best way, but it will demonstrate how you can store options in the database using a custom manager page. A more thorough solution would not be as valuable as a teaching tool.
We are going to build a form with two fields: one that allows the user to enter a block of content, and another that accepts the character (or characters) that separates that content into units. For example, this could be our content block:
man, bear, pig
Then, our separator would be a simple comma (","). If your content is more complex, you may need a more complex separator.
We need to store two settings in the database, so let's make the following changes.
First, update your admin_page.php file so it contains two form elements:
<div class="wrap">
<?php screen_icon(); ?>
<h2>Content Rotator Administration</h2>
<?php print $msg; ?>
<form action="" method="post" id="content_rotation_admin_
options_form">
<h3><label for="separator">Separator</label></h3>
<p>This separates units of content. It can be simple like a comma, or complex like <!--SEPARATOR--><br/>
<input type="text" id="separator" name="separator"
value="<?php print esc_attr( get_option('content_rotation_content_
separator') ); ?>" /></p>
<h3><label for="content_block">Content Block</label></h3>
<p>
Use the separator above to separate blocks of content, e.g. <code>man, bear, pig</code><br/>
or <code><a href="http://mysite.com/">MySite.
com</a><--SEPARATOR-->
<a href="http://yoursite.com/">YourSite.com</
a></code><br/>
<textarea rows="5" cols="50" id="content_block"
name="content_block"><?php print get_option('content_rotation_content_
block'); ?></textarea>
</p>
<p class="submit"><input type="submit" name="submit"
value="Update" /></p>
<?php wp_nonce_field('content_rotation_admin_options_
update','content_rotation_admin_nonce'); ?>
</form>
</div>
Notice that we're using WordPress' get_option() function to supply values to our form elements. Also, have a gander at the wp_nonce_field() function. What is a nonce? A nonce is a "number used only once", and it is an important security feature.
By including a nonce as a hidden field on your forms, you can reduce the risk of your form being hijacked by a cross-site request forgery (CSRF). WordPress generates a unique value for this form which gets validated when the form is submitted. This makes it harder to post malicious data to your form. The full explanation of this technique is beyond the scope of this book, but you should use it for security reasons.
Any time we create a form, we also must handle the submission of that form. We need to program some code that handles the form data after it has been submitted.
Let's do that next.
We need to save the form values if they were properly submitted. We do this by updating our controller function inside of ContentRotator.php:
/**
* Controller that generates admin page
*/
static function generate_admin_page() {
$msg = ''; // used to display a success message on updates
if ( !empty($_POST) && check_admin_referer('content_rotation_admin_
options_update','content_rotation_admin_nonce') )
{
update_option('content_rotation_content_separator', stripslashes($_POST['separator']) );
update_option('content_rotation_content_block', stripslashes($_POST['content_block']) );
$msg = '<div class="updated"><p>Your settings have been
<strong>updated</strong></p></div>';
}
include('admin_page.php');
}
If you have built PHP form handlers in the past, you may be more familiar with a big if-else statement which decides whether it displays the form or processes the form based on whether or not it has been submitted. Our approach here is simpler.
The check_admin_referer() function will terminate the script if the submission was not authentic, so we can't use an if-else construct. Instead we use a simple if-statement.
It's important to summarize the exact syntax that needs to be used for the wp_nonce_
field() and the check_admin_referer() functions because they need to match up.
Some of the official documents for these functions are confusing, so here's the short syntax:
wp_nonce_field($action_name, $nonce_name);
check_admin_referer($action_name, $nonce_name);
Where $action_name is the name of the action and $nonce_name is the name of the nonce. If you have a page with multiple forms on it, it's important that you give unique values to each instance of the wp_nonce_field() function. However, the most important thing to remember here is that the arguments passed to the check_
admin_referer() function must match exactly the values passed to the wp_nonce_
field() function. If they do not match, WordPress will exit with a message. Oddly the message reads "Are you sure you want to do this?" which gives little inkling as to the root cause.
We use WordPress' update_option() function to store the options in the database, and we are using PHP's stripslashes() function to help sanitize the data. Note that the option names here match the names used by the get_option() functions in the admin_page.php page. So once again we have a pair of functions whose inputs must match.
Lastly, we are using a simple $msg variable to store a message to show whether or not the options have been updated. We are using some standard WordPress styling information by using a <div class="updated"> block here, and we encourage you to do the same.
Save your work and refresh your manager page. You should now be able to save custom configuration details and have them persist when you revisit the configuration page. For testing, we recommend that you use a comma separator and a simple comma-separated list. Enter in some text now before proceeding.