The Settings API enables you to handle these simple tasks:
Tell WordPress that you are going to use some new options and how you want them displayed.
Specify a function that will sanitize user inputs.
while WordPress transparently manages for you these cumbersome and repetitive parts:
Draw most of the option page itself.
Monitor form submission and handle $_POST data.
Create and update options if needed.
Wield all the required security measures and hidden fields for nonces, covered in detail in Chapter 4, “Security and Performance.”
Now it's time to dissect the Settings API; you'll learn to use it through a step‐by‐step example.
Settings API Functions
The Settings API functions consist of three steps:
1 Tell WordPress the new settings you want it to manage for you. Doing so adds your settings into a list of authorized options (also known as whitelisting).
2 Define the settings (text areas, input boxes, and any HTML form element) and how they will be visually grouped together in sections.
3 Tell WordPress to display your settings in an actual form.
But first, you create a setting management page for your plugin.
Creating the Plugin Administration Page
The plugin page will be located at Settings ➪ PDev Settings:
<?php // 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"> </form> </div> <?php } ?>
This page is empty for now. You will add form inputs later. Creating pages for plugins is covered in detail earlier in the “Plugin Settings” section of this chapter, so refer to it for more explanation about this code.
Registering New Settings
The next step is to register your new settings. The function you need here is register_setting() and three parameters, used as follows:
<?php register_setting( option group, option name, args ); ?>
The register_setting()function accepts the following parameters:
option_group: Group name for your settings.
option_name: Name of an option to sanitize and save.
args: Data used to describe the setting when registered.type: Type of data associated with this setting. Valid values are string, boolean, integer, and number.description: Description of the data for this setting.sanitize_callback: Callback function to sanitize the option's value.show_in_rest: Whether the data with this setting should be included in the REST API.default: Default value when calling get_option().
Now let's register your plugin settings using the register_setting() function. The first parameter you'll set is the setting group name, and the second parameter is the option name as you would use it in a get_option() call. The group name can be anything actually, but it's just simpler to name it the same as the option that will get stored in the database.
The third parameter is an array of additional arguments defining the type of data. In this case, it's a string and references your callback function, here named pdev_plugin_validate_options(), that will be passed all the settings saved in your form. You'll define this function later.
<?php $args = array( 'type' => 'string', 'sanitize_callback' => 'pdev_plugin_validate_options', 'default' => NULL ); register_setting( 'pdev_plugin_options', 'pdev_plugin_options', $args ); ?>
Defining Sections and Settings
Now define what the settings will be more precisely by using the function add_settings_field() and how they will be visually grouped with the function add_settings_section().
<?php add_settings_section( id, title, callback, page ); add_settings_field( id, title, callback, page, section, args ); ?>
The first function call, add_settings_section(), defines how the section on the page will show. The four required parameters it uses follow:
id: HTML ID tag for the section
title: Section title text that will show within an <H2> tag
callback: Name of the callback function that will echo some explanations about that section
page: Settings page on which to show the section (that is, the ?page=pdev_plugin part of the page URL)
The second function call, add_settings_field(), describes how to add the form input. Its required parameters follow:
id: HTML ID tag for the section
title: Formatted title of the field, which is displayed as the label for the field on output
callback: Name of the callback function that will echo the form field
page: Settings page on which to show the section
section: Section of the settings page in which to show the field, as defined previously by the add_settings_section() function call
args: Additional arguments used when outputting the field
Now let's implement these new functions for your plugin settings as follows:
<?php add_settings_section( 'pdev_plugin_main', 'PDEV Plugin Settings', 'pdev_plugin_section_text', 'pdev_plugin' ); add_settings_field( 'pdev_plugin_name', 'Your Name', 'pdev_plugin_setting_name', 'pdev_plugin', 'pdev_plugin_main' );
You now need to define two simple callback functions: one to display a few explanations about the section and one to output and fill the form field.
<?php // 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 ) . "'/>"; }?>
This second function call fetches the option value name that is stored in an array.
When outputting the HTML input field, note its name. This is how you tell the browser to pass this value back into an array with the same name as the option you'll save, as defined earlier in the register_setting() function call. Any field that has not been previously registered and whitelisted will be ignored by WordPress.
You'll also notice you are using the esc_attr() function. This is used to escape the HTML attribute value for display. You'll learn more about this in Chapter