select it echo "<option value='" .$item. "' " .selected( $fav_holiday, $item, false ).">" . esc_html( $item ) . "</option>"; } echo "</select>"; }
This example registers a new select drop‐down field allowing the user to select their favorite holiday. First, you call get_option() to load the current setting value, if it exists. If the value does not exist, meaning the user has not selected and saved the selection yet, the default is set to Halloween. Next you set the $items variable to an array of available holiday options to choose from.
Now it's time to loop through the available holiday options and display each one in the drop‐down field. We're using the WordPress core function selected(), which compares two values and, if they match, returns selected="selected", which will select that option value in the drop‐down.
Now let's look at the custom function for displaying the radio button field, pdev_plugin_setting_beast_mode().
// Display and set the Beast Mode radio button field function pdev_plugin_setting_beast_mode() { // Get option 'beast_mode' value from the database // Set to 'disabled' as a default if the option does not exist $options = get_option( 'pdev_plugin_options', [ 'beast_mode' => 'disabled' ] ); $beast_mode = $options['beast_mode']; // Define the radio button options $items = array( 'enabled', 'disabled' ); foreach( $items as $item ) { // Loop the two radio button options and select if set in the option value echo "<label><input ".checked( $beast_mode, $item, false )." value= '" . esc_attr( $item ) . "' name='pdev_plugin_options[beast_mode]' type='radio'/>" . esc_html( $item ) . "</label><br/>"; } }
This example registers a new radio button field allowing the user to select if they want to enable beast mode or not. Again, you'll use get_option() to load the current setting value, and if it doesn't exist, the default value disabled is set. Next, you'll define the two values in the $items array. Now you need to loop through the two options displaying the radio button. The checked() function is used to compare the saved value against the display value and, if they are the same, to input checked="checked" on the radio button form field.
Now that you have registered two new settings fields and created the custom functions to display both fields, you need to update your validate function to accept those values and sanitize them as needed.
// Validate user input for all three options function pdev_plugin_validate_options( $input ) { // Only allow letters and spaces for the name $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' ); } // Sanitize the data we are receiving $valid['fav_holiday'] = sanitize_text_field( $input['fav_holiday'] ); $valid['beast_mode'] = sanitize_text_field( $input['beast_mode'] ); return $valid; }
The only update here is to run the two new option values through the sanitize_text_field() WordPress function to sanitize the user‐inputted data. Even though the values are hard‐coded in the form, that doesn't stop a user from modifying the frontend form code and posting unknown data to these setting fields. You'll cover this more in Chapter 4.
That's it! You now have a more robust settings page for your plugin. Let's review the entire plugin source code with your new settings fields.
<?php /* Plugin Name: Settings API example - Multiple Fields 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(){ // 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' ); } // Draw the section header function pdev_plugin_section_text() { echo '<p>Enter your settings here.</p>'; } // Display and fill the Name text 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 ) . "'/>"; } // 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 value, select it echo "<option value='" . esc_attr( $item ) . "' ".selected( $fav_holiday, $item, false ).">" . esc_html( $item ) . "</option>"; } echo "</select>"; } // Display and set the Beast Mode radio button field function pdev_plugin_setting_beast_mode() { // Get option 'beast_mode' value from the database // Set to 'disabled' as a default if the option does not exist $options = get_option( 'pdev_plugin_options', [ 'beast_mode' => 'disabled' ] ); $beast_mode = $options['beast_mode']; // Define the radio button options $items = array( 'enabled', 'disabled' ); foreach( $items as $item ) { // Loop the two radio button options and select if set in the option value echo "<label><input " . checked( $beast_mode, $item, false ) . " value='" . esc_attr( $item ) . "' name='pdev_plugin_options[beast_mode]' type='radio'/> " . esc_html( $item ) . "</label><br/>"; } } // Validate user input for all three options function pdev_plugin_validate_options( $input ) { // Only allow letters and spaces for the name $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' ); } // Sanitize the data we are receiving $valid['fav_holiday'] = sanitize_text_field( $input['fav_holiday'] ); $valid['beast_mode'] = sanitize_text_field( $input['beast_mode'] ); return $valid; } ?>
Adding Fields to an Existing Page
You have seen how to create a new custom settings page for a plugin and its associated entry in the administration menus. Doing so makes sense if your plugin features a lot of settings and its administration page shows a lot of content.
Sometimes, though, it is not worth adding a new menu entry for just one or a few plugin options. Here again the Settings API will prove to be useful, allowing plugin setting fields to easily be added to the existing WordPress setting pages.
How
