The Settings API is an intricate series of callbacks that allow plugin developers to streamline the creation of administration pages and to automatically store user options.

This self-contained plugin recipe starts with the creation of a new set of default options, to avoid inadvertently deleting options from previous recipes.

The code continues with registering a function to be called whenever admin pages are prepared for display using the admin_init action hook. Upon getting called, the callback function takes care of registering a new setting group, a setting section belonging to this group, and two fields that will display the desired options within the section. As can be seen throughout this code, additional functions are registered to validate the user-submitted data, to display custom text at the beginning of the section, and to display the two different types of fields required to capture and display user input.

Taking a closer look at each of the functions that were just used, the first function has three parameters, which are as follows:

register_setting( $option_group, $option_name, $sanitize_callback );

Within these parameters, the first option is a unique identifier for the settings group, the second is the name of the options array that will be used to store configuration data in the site database, while the third is the name of a callback function that will receive user input for validation.

Moving on to the second function used in this example, add_settings_section, the four parameters that it requires respectively indicate a unique identifier for the section, the title string that will be displayed when the section is rendered, a callback function that will be used to display a description for the section, and finally a page identifier that will be used to render all similar functions later within the plugin code:

add_settings_section( $id, $title, $callback, $page );

The third function of the Settings API used in this recipe, add_settings_field, is called multiple times to define the fields that make up each section:

add_settings_field( $id, $title, $callback, $page, $section, [$args] );

Similar to the other functions, the first parameter is a unique identifier for the field, the second parameter is a label that will be displayed next to the field, and the third parameter is a callback function that will be executed to output the necessary HTML code to display the field. The next three parameters indicate the page that the field belongs to, the section that it is contained in, and an optional array of additional data to be sent to the callback function. As can be seen in the rest of this recipe, we are leveraging this optional additional data argument to send data to the field processing function to make them more generic.

When the configuration page is visited, the top-level form is created using regular HTML code, setting the action to options.php. This script is responsible for automating the processing of user data. The rest of the form is quite simple, since it gets generated by the settings_fields and do_settings_sections functions.

When they are called, the setting group created earlier is rendered, followed by calls to the functions designed to draw all the sections that it contains and all the registered fields within these sections.

While the Settings API provides full control over the layout of the form fields themselves, its use dictates the general layout of the configuration page, creating a two-column table that contains the labels for each field in the first column and the code produced by the plugin's callback functions in the second one. As the functions for each type of field are called, they receive the array data that was associated with each of them and use it to retrieve the current field values and to specify the name of each field to be stored back upon user input.

The last piece of the puzzle is the validation function that was registered when the setting group was first created. The purpose of this function is to allow plugin developers to perform data type or content validation as user data is submitted through the form, similar to the way we validate user-submitted data in the Processing and storing plugin configuration data recipe.