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 styled <div> and <p> tags
type: Type of message, error or update
You can improve the validating function with a user notice if applicable, as shown here:
<?php function pdev_plugin_validate_options( $input ) { $valid['name'] = preg_replace( '/[^a-zA-Z\s]/', '', $input['name'] ); if( $valid['name'] !== $input['name'] ) { add_settings_error( 'pdev_plugin_text_string', 'pdev_plugin_texterror', 'Incorrect value entered! Please only input letters and spaces.', 'error' ); } return $valid; } ?>
The function now compares the validated data with the original input and displays an error message if they differ (see Figure 3‐5).
FIGURE 3‐5: Error message
Expanding with Additional Field Types
You've now covered the different ways to create a settings page using the WordPress Settings API. Let's expand on that by adding additional form field types to your settings page. This is a more real‐world example showing how elaborate your settings page could be. At the end of this section, you'll review the entire plugin code as a whole.
First, you need to define additional settings fields using the add_settings_field() function. The following example updates the registration of those fields in your custom pdev_plugin_admin_init() function:
// Register and define the settings add_action('admin_init', 'pdev_plugin_admin_init'); function pdev_plugin_admin_init(){ //define the setting args $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' ); //create our settings field for favorite holiday add_settings_field( 'pdev_plugin_fav_holiday', 'Favorite Holiday', 'pdev_plugin_setting_fav_holiday', 'pdev_plugin', 'pdev_plugin_main' ); //create our settings field for beast mode add_settings_field( 'pdev_plugin_beast_mode', 'Enable Beast Mode?', 'pdev_plugin_setting_beast_mode', 'pdev_plugin', 'pdev_plugin_main' ); }
As you can see in the preceding code sample, you register two new form fields for Favorite Holiday and Beast Mode. Both call custom functions for displaying each field on your settings page. Let's look at the pdev_plugin_setting_fav_holiday() function first.
// Display and select the favorite holiday select field function pdev_plugin_setting_fav_holiday() { // Get option 'fav_holiday' value from the database // Set to 'Halloween' as a default if the option does not exist $options = get_option( 'pdev_plugin_options', [ 'fav_holiday' => 'Halloween' ] ); $fav_holiday = $options['fav_holiday']; // Define the select option values for favorite holiday $items = array( 'Halloween', 'Christmas', 'New Years' ); echo "<select id='fav_holiday' name='pdev_plugin_options[fav_holiday]'>"; foreach( $items as $item ) { // Loop through the option values // If saved option matches the option
