How to create a custom settings page with custom settings fields and sections in WordPress

The default settings in WordPress serve a general purpose, but customizing your own settings page allows you to align your website precisely with your vision and requirements. From tweaking design elements to adding specialized functionalities, the possibilities are endless.

Getting started

The journey begins in your theme’s functions.php file. This is where you’ll add WordPress hooks to manipulate the settings page. Let’s set the stage with a simple example:

function pe_custom_settings_page() {
    add_menu_page('Project settings', 'Project settings', 'manage_options', 'project-settings', 'project_settings_callback' );
}
add_action('admin_menu', 'pe_custom_settings_page');

function project_settings_callback() {

    ob_start(); ?>

    <div class="wrap">
        <h2>Project settings</h2>

    </div>

    <?php

    $html = ob_get_contents();
    ob_get_clean();

    echo $html;
}

This code creates a new menu item labeled “Project settings” in the WordPress admin menu and it is added at the bottom of the list.

add_menu_page

The add_menu_page function in WordPress serves as a pivotal tool for developers seeking to create a customized settings page tailored to their website’s specific needs. Let’s dissect its parameters to understand how each contributes to the seamless integration of a personalized menu item into the WordPress admin dashboard.

Firstly, the $page_title parameter sets the text that appears in the title tag of the web page, influencing how users perceive the page in their browser. Simultaneously, the $menu_title parameter determines the label displayed in the WordPress admin menu, offering a quick and recognizable identifier for users navigating the dashboard.

The $capability parameter establishes the user role required to access the custom settings page. By default, it is set to 'manage_options', granting access to administrators. Adjusting this parameter provides fine-grained control over who can interact with the settings.

The $menu_slug parameter is a unique identifier crucial for constructing URLs and screen IDs. It needs to be distinct to avoid conflicts with existing slugs. Additionally, the $callback function parameter specifies the function responsible for rendering the content of the settings page. This function typically includes HTML and form elements for user interaction.

For a visual touch, the optional $icon_url parameter allows developers to include an icon next to the menu item. This can be a URL or a dashicons class, aiding in quick visual identification. Lastly, the $position parameter, also optional, determines where the menu item appears in the admin menu. By default, it’s placed at the bottom, but developers can customize its position with a numeric value.

In essence, the add_menu_page function is a versatile tool that, when utilized effectively, empowers developers to integrate a seamlessly customized settings page into the WordPress environment, enhancing both functionality and user experience.

Adding settings sections and fields

This code is a WordPress function that registers custom settings for a plugin or theme. Let’s break down the code and understand its components:

function pe_register_option_settings() {
    add_settings_section(
        'pe_project_settings_section_post_state', // string $id
        __( 'Engine page', 'projectsengine' ), // string $title
        'pe_project_settings_section_post_state_callback', // callable $callback
        'project-settings', // string $page
        array( 
            'before_section' => '',
            'after_section' => '',
            'section_class' => ''
        )
    );

    add_settings_field(
        'pe_post_state_page_field',
        __( 'Select page', 'projectsengine' ),
        'pe_post_state_page_field_callback',
        'project-settings',
        'pe_project_settings_section_post_state'
    );

    register_setting( 'project-settings', 'pe_eninge_page_options' );
}

add_action('admin_init', 'pe_register_option_settings' );

The add_settings_section function adds a new section to the settings page in the WordPress admin. The parameters are as follows: $id, $title, $callback, $page, $args.

The add_settings_field function adds a new field to a settings section. The parameters are as follows: $id, $title, $callback, $page, $section_id.

And here are the callbacks:

/**
 * Settings section description.
 *
 */
function pe_project_settings_section_post_state_callback() {
    ob_start(); ?>

    <p>Discover expert tips, step-by-step tutorials, and insider knowledge on PHP, WordPress, HTML5, CSS3, JavaScript, Git, and more.</p>

    <?php

    $html = ob_get_contents();
    ob_get_clean();

    echo $html;
}

/**
 * Renders the custom "Select page" field.
 *
 * @param array $args
 */
function pe_post_state_page_field_callback( $args ) {
    $id = 'pe_post_state_page_field';
    
    wp_dropdown_pages( array(
        'name'              => $id,
        'show_option_none'  => '&mdash; Select &mdash;',
        'option_none_value' => '0',
        'selected'          => get_option( $id ),
    ) );
}

/**
 * Adds pe_post_state_page_field to the white-listed options, which are automatically
 * updated by WordPress.
 *
 * @param array $options
 */
add_filter( 'whitelist_options', function ( $options ) {
    $options['project-settings'][] = 'pe_post_state_page_field';

    return $options;
} );

The field callback can be anything you want: checkbox, input field, or another select field.

Once this is done, update the project_settings_callback, it should be like this:

function project_settings_callback() {

    ob_start(); ?>

    <div class="wrap">
        <h2>Project settings</h2>

        <form action="options.php" method="post"> 

            <?php

            settings_fields('project-settings');
            do_settings_sections('project-settings');

            submit_button(); ?>

        </form>

    </div>

    <?php

    $html = ob_get_contents();
    ob_get_clean();

    echo $html;
}

Creating a custom settings page in WordPress opens the door to endless possibilities.