Dorokhov.codes

12. Administrative Interfaces

WordPress provides two core APIs to make the administrative interfaces easy to build (Settings API and Options API).

The Settings API focuses on providing a way for developers to create forms and manage form data.

It allows to define settings pages, sections within those pages and fields within the sections.

Page -> Sections -> Fields

1. Register settings

These functions should all be added to the admin_init action hook.

Setting is a parameter that will be stored in a DB. We used to call it option.

We must define a new setting using register_setting(), it will create an entry in the {$wpdb->prefix}_options table. It has no effect on the displaying fields.

function register_my_setting() {

    register_setting(
        string $option_group,               // A settings group name.
        string $option_name,                // The name of an option to sanitize and save.
        [                                   // array $args = array()
            string $type,                   // The data type for the option value (e.g., 'string', 'integer', 'boolean', etc.).
            string $description,            // A brief description of the setting.
            callable $sanitize_callback,    // A callback function to sanitize and validate the setting's value.
            bool|array $show_in_rest,       // Optional. Whether to expose this setting in the REST API. Can be a boolean or an array.
            mixed $default                  // Optional. The default value for the setting.
        ]
    );
}

add_action( 'admin_init', 'register_my_setting' );

Some notes about the elements in the $args parameter.

Settings are typically grouped together, and the option_group parameter helps organize them. It’s used in the settings_fields() function for security measures. It’s used to avoid conflicts between settings with similar names that might belong to different themes or plugins.

2. Creating sections

Section is a key concept. We create a section, then we attach it to some page, and add to this section settings fields.

We can’t show any settings without a section.

add_settings_section( 
    string $id,             // Slug-name to identify the section. Used in the 'id' attribute of tags.
    string $title,          // Formatted title of the section. Shown as the heading for the section.
    callable $callback,     // Function that echos out any content at the top of the section (between heading and fields).
    string $page,           // The slug-name of the settings page on which to show the section.
    array $args = array()
)

$page parameter can be any string. We only use it when we show this section:

do_settings_sections( string $page );

3. Add a field to a section

add_settings_field( 
    string $id,                     // Slug-name to identify the field. Used in the 'id' attribute of tags.
    string $title,                  // Formatted title of the field. Shown as the label for the field during output.
    callable $callback,             // Function that fills the field with the desired form inputs. The function should echo its output.
    string $page,                   // The slug-name of the settings page on which to show the section (general, reading, writing, ...).
    string $section = 'default', 
    array $args = array()
);

We can consider $page and $section combination as a namespace for the fields. Because section ID can be the same within the different pages.

Also, WordPress has magic interaction with the following keys: label_for, class. Settings are displayed in a table. Using label_for we can add label to the field name, and using class we can add a custom CSS class to the tr tag. Moreover, these parameters are accessible in the $callback function. It allows us to add an ID to inputs dynamically.

4. Creating a form on a page

if ( ! current_user_can( 'manage_options' ) ) {
    return;
}

?>
<div class="wrap">
    <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
    <form action="options.php" method="post">
        <?php
        // Outputs nonce, action, and option_page fields for a settings page.
        settings_fields( 'option_group' );
        
        // Outputs setting sections and their fields.
        do_settings_sections( 'my-settings-page' );
        
        // Outputs save settings button.
        submit_button( 'Save Settings' );
        ?>
    </form>
</div>

5. How everything works

The form is sent to the /wp-admin/options.php file.

We can update only options we registered with register_settings().

The option group is sent by the option_page parameter. It’s like a namespace. It means we can update settings only from one option group at once.