Validating User Input
There is still one callback function to define, pdev_plugin_validate_options(), as mentioned earlier when registering the settings.
In this example, users are asked to enter text, so your validation function simply makes sure that the input contains only letters.
<?php // Validate user input (we want text and spaces only) function pdev_plugin_validate_options( $input ) { $valid = array(); $valid['name'] = preg_replace( '/[^a-zA-Z\s]/', '', $input['name'] ); return $valid; } ?>
To validate the user input as letters only, a simple pattern matching (also known as regular expression) that strips all other characters is used here. This regex pattern also supports spaces between names.
This function is passed the $_POST data as a parameter. For enhanced security, start creating a new empty array named $valid and collect in this array only the values you are expecting. This way, if for some reason an unanticipated field is submitted in the form, your function not only validates the information you want but also blocks everything else. Refer to Chapter 4 for more tips and functions about data validation.
Rendering the Form
Now that you have defined these function calls, it's time to use them. At the beginning of this step‐by‐step example, you created an empty page. Go back to that and add the form fields and a Submit button.
// Create the option page function pdev_plugin_option_page() { ?> <div class="wrap"> <h2>My plugin</h2> <form action="options.php" method="post"> <?php settings_fields( 'pdev_plugin_options' ); do_settings_sections( 'pdev_plugin' ); submit_button( 'Save Changes', 'primary' ); ?> </form> </div> <?php }
The settings_fields() function call references the whitelisted option you have declared with register_setting(). The only required parameter is the settings group name. This should match the group name used in register_setting(). It takes care of the hidden fields, security checks, and form redirection after it has been submitted.
The second function call, do_settings_sections(), outputs all the sections and form fields you have previously defined. The only required parameter for this function is the slug name of the page whose settings sections you want to output.
The final function is submit_button(), which will display the form submission button. This function is extremely handy when building any form in WordPress and accepts the following parameters:
text: Text displayed on the button.
type: Type and CSS class or classes of the button.
name: HTML name of the button.
wrap: Boolean that defines whether the output button should be wrapped in a paragraph tag. Defaults to true.
other_attributes: Additional attributes that should be output with the button, such as a tabindex.
An alternative method is using the get_submit_button() function. This function supports the same parameters, but instead of displaying the button, it will return the submit button. This is useful if you are compiling a form but not ready to fully display it yet.
All Done!
Notice how little HTML you have laid down, and yet the plugin page is now complete and functional. This is a major reason this Settings API is rock solid: you focus on features and let WordPress create all the HTML with relevant tags and classes, handle the data submission, and escape strings before inserting them to the database.
NOTE Designing plugin pages using the Settings API is future‐proof. Imagine that you are creating a plugin for a client on a particular version of WordPress. Later, when the administration interface of WordPress changes (different layout, colors, HTML classes), your plugin will still seamlessly integrate because you did not hard‐code any HTML in it.
Wrapping It Up: A Complete Plugin Management Page
Some of the function calls used here need to be hooked into WordPress actions such as admin_init. Let's recapitulate all the steps covered bit by bit into a full‐fledged plugin.
<?php /* Plugin Name: Settings API example Plugin URI: https://example.com/ Description: A complete and practical example of the WordPress Settings API Author: WROX Author URI: http://wrox.com */ // Add a menu for our option page add_action( 'admin_menu', 'pdev_plugin_add_settings_menu' ); function pdev_plugin_add_settings_menu() { add_options_page( 'PDEV Plugin Settings', 'PDEV Settings', 'manage_options', 'pdev_plugin', 'pdev_plugin_option_page' ); } // Create the option page function pdev_plugin_option_page() { ?> <div class="wrap"> <h2>My plugin</h2> <form action="options.php" method="post"> <?php settings_fields( 'pdev_plugin_options' ); do_settings_sections( 'pdev_plugin' ); submit_button( 'Save Changes', 'primary' ); ?> </form> </div> <?php } // Register and define the settings add_action( 'admin_init', 'pdev_plugin_admin_init' ); function pdev_plugin_admin_init(){ $args = array( 'type' => 'string', 'sanitize_callback' => 'pdev_plugin_validate_options', 'default' => NULL ); // Register our settings register_setting( 'pdev_plugin_options', 'pdev_plugin_options', $args ); // Add a settings section add_settings_section( 'pdev_plugin_main', 'PDEV Plugin Settings', 'pdev_plugin_section_text', 'pdev_plugin' ); // Create our settings field for name add_settings_field( 'pdev_plugin_name', 'Your Name', 'pdev_plugin_setting_name', 'pdev_plugin', 'pdev_plugin_main' ); } // Draw the section header function pdev_plugin_section_text() { echo '<p>Enter your settings here.</p>'; } // Display and fill the Name form field function pdev_plugin_setting_name() { // get option 'text_string' value from the database $options = get_option( 'pdev_plugin_options' ); $name = $options['name']; // echo the field echo "<input id='name' name='pdev_plugin_options[name]' type='text' value='" . esc_attr( $name ) . "'/>"; } // Validate user input (we want text and spaces only) function pdev_plugin_validate_options( $input ) { $valid = array(); $valid['name'] = preg_replace( '/[^a-zA-Z\s]/', '', $input['name'] ); return $valid; } ?>
FIGURE 3‐4: Plugin management page
Activate this plugin and head to Settings ➪ PDEV Settings. You'll see a similar interface to the one shown in Figure 3‐4.
Improving Feedback on Validation Errors
The validation function you've previously defined could be slightly improved by letting the users know they have entered an unexpected value and that it has been modified so that they can pay attention to it and maybe amend their input.
The relatively unknown function add_settings_error() of the Settings API can handle this case. Here's how it is used:
<?php add_settings_error( setting, code, message, type ); ?>
This function call registers an error message that displays to the user. add_settings_error() accepts the following parameters:
setting: Title of the setting to which this error applies
code: Slug name to identify the error, which is used as part of the HTML ID tag
message: Formatted message text to display, which is displayed inside