Make a Settings Page for a Custom WordPress Plugin @ TwentySixForty

In the last tutorial I explained How to Create a WordPress Plugin. This tutorial is going to build on that and explain how to create a settings page so the plugin will actually do something. If you need to build a plugin base, go back and see the last tutorial.

What is a WordPress Settings Page?

A WordPress settings page is a page accessible through the WordPress dashboard that allows an administrator to make changes to the website. As an example, all of the pages listed under Settings or Appearance in the dashboard sidebar menu are settings pages. Each of these pages will have a number of settings that allow you to edit functions on the website. Settings pages are usually built using the Settings and Options APIs. The Settings API allows you add sections,fields and settings to the page. The Options API lets you run the create, read, update and delete (CRUD) functions you need to interact with the database.

About the WordPress Settings API.

There are three main parts of the Settings API: sections, fields and settings. Sections simply group fields together. Fields are form controls used on the settings page like a text field or select field. A setting is the data that is actually stored in the database.

These are the functions we will be using in this tutorial from the WordPress Settings API:

register_setting()
add_settings_section()
add_settings_field()
settings_fields()
do_settings_sections()

register_setting()

Registers a settings group and its data.

register_setting( $option_group, $option_name, $args = array() )

$option_group: Name of the settings group. Required
$option_name: Name of an option to sanitize and save. Required
$args: Data used to describe the setting when registered. Optional

add_settings_section()

Adds a section to a settings page.

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

$id: Slug-name of the section. Required
$title: Title of the section. Required
$callback: Function that displays content at the top of the section between the heading and fields. The function should echo() its output. Required
$page: Slug-name of the settings page on which to show the section. Required

add_settings_field()

Adds a field to a section.

add_settings_field( $id, $title, $callback, $page, $section = 'default', $args = array() )

$id: Slug-name of the field. Required
$title: Title of the field. Required
$callback: Function to fill the field with form inputs. The function should echo() its output. Required
$page: Slug-name of the settings page on which to show the section. Required
$section: Slug-name of the section of the settings page in which to show the field. Optional
$args: Extra arguments for the callback function. Optional

settings_fields()

Outputs the nonce, action, and fields for the settings page.

settings_fields( $option_group )

$option_group: The settings group name. Should match the group name used in register_setting() function. Required

do_settings_sections()

Outputs the sections and fields defined in the add_settings_section() and add_settings_field() functions.

do_settings_sections( $page )

$page: Slug name of the page to output the settings sections. Required

About the WordPress Options API.

The WordPress Options API lets you create, read, update and delete (CRUD) data in the database. Options are store in the wp_options table (or whatever prefix you are using).

This is the function we will be using from the Options API:

get_option()

Gets an option value based on the option name.

get_option( $option, $default = false )

$option: Name of the option you want to get. Required
$default: Default value to return if the option does not exist. The default value is false. Optional

How to Create a WordPress Settings Page.

Step 1: Add the Settings Page in WordPress.

I covered this in the last tutorial so I won’t go into too much depth. The main plugin file should have the following code placed after the header comments substituted with your values. This adds a settings page to your plugin.

function add_xxx_plugin_menu() {
    add_submenu_page('options-general.php', 'XXX Plugin', 'XXX Plugin', 'manage_options', 'xxx-plugin', 'xxx_plugin_function');
}
add_action('admin_menu', 'add_xxx_plugin_menu');

Step 2: How to Add a Settings Section and Fields.

The following code:

Registers a settings group called xxx-setting.
Adds a settings section called XXX Section.
Adds three settings fields to the XXX Section called Text Input X, Text Input XX and Select Input XXX.

function xxx_settings_init() {
    register_setting( 'xxx-setting', 'xxx_settings' );
    add_settings_section('xxx-plugin-section', __( 'XXX Section', 'xxx-plugin' ), 'xxx_settings_section_callback', 'xxx-setting' );
    add_settings_field( 'xxx_text_1', __( 'Text Input X:', 'xxx-plugin' ), 'xxx_text_1', 'xxx-setting', 'xxx-plugin-section' );
    add_settings_field( 'xxx_text_2', __( 'Text Input XX:', 'xxx-plugin' ), 'xxx_text_2', 'xxx-setting', 'xxx-plugin-section' );
    add_settings_field( 'xxx_select_1', __( 'Select Input XXX:', 'xxx-plugin' ), 'xxx_select_1', 'xxx-setting', 'xxx-plugin-section' );
}
add_action( 'admin_init', 'xxx_settings_init' );

Step 3: How to Add a Section Description.

The following code adds a description to the top of the section.

function xxx_settings_section_callback(  ) {
    echo __( 'This is the Section Description', 'xxx-plugin' );
}

Step 4: Create the Callback Function for Each Setting.

The third parameter of the add_settings_field() function is the callback. You can use this function to create the input field for the option.


function xxx_text_1(){
    $options = get_option( 'xxx_settings' ); ?>
    <input type='text' name='xxx_settings[xxx_text_1]' value='<?php echo $options["xxx_text_1"]; ?>'> <?php
}
function xxx_text_2(){
    $options = get_option( 'xxx_settings' ); ?>
    <input type='text' name='xxx_settings[xxx_text_2]' value=''> <?php
}
function xxx_select_1(){
    $options = get_option( 'xxx_settings' ); ?>
    <select name='xxx_settings[xxx_select_1]'>
        <option value='1' <?php selected( $options["xxx_select_1"], 1 ); ?>>Option 1</option>
        <option value='2' <?php selected( $options["xxx_select_1"], 2 ); ?>>Option 2</option>
        <option value='3' <?php selected( $options["xxx_select_1"], 3 ); ?>>Option 3</option>
    </select> <?php
}

Step 5: Write the Callback Function to Output the Content to the Page.

This function is called from the add_submenu_page() function. I am using the settings_fields(), do_settings_sections() and submit_button() functions.


function xxx_plugin_function(){ ?>
    <form action='options.php' method='post'> <?php
        settings_fields( 'xxx-setting' );
        do_settings_sections( 'xxx-setting' );
        submit_button(); ?>
    </form> <?php
}

If you visit the settings page you should see something like this:

WordPress Options