Using the WordPress Settings API to Build a Custom Admin Page

For the functions of this tutorial, we’ll wrap this capability into a plugin, however, this may additionally be a part of a WordPress subject matter.

As the WordPress Codex says, the Settings API became delivered in WordPress 2.7 to streamline including specific settings fields and sections in administration pages.

Creating the Plugin
To begin, we’ll create and prompt a plugin to encapsulate our alternatives page. We’ll use WP CLI to simplify the advent, despite the fact that this leaves us with way greater documents than this guide desires.

Video Player

00:00
00: forty-nine

As we can see, we use wp scaffold plugin name to create the plugin. Once it’s created, we activate it — optionally additionally the use of WP CLI, with wp plugin set off plugin name.

Once it’s activated, we open the main plugin document — in this situation SitePoint-settings-API.Hypertext Preprocessor.

Creating the Admin Page
It isn’t essential to use WP CLI for this plugin. We ought to have really created a directory with the call of the plugin, and the PHP record inside it with the same name. Anyhow, the creation of the plugin has left us with a SitePoint-settings-API.The personal home page which looks like this:

To add our options page, we’ll use add_options_page() (more details about it here). This functImage result for Using the WordPress Settings API to Build a Custom Admin Pageion takes arguments as follows:

add_options_page( $page_title, $menu_title, $capability,
$menu_slug, $function );
All the arguments are self-explanatory. $menu_slug must be a unique string that WordPress will use internally, but will also be reflected in the URL. $function is a string with a name of the function that will provide HTML output for our admin page.

We will, therefore, add the following code to our plugin file:

add_action( ‘admin_menu’, ‘sitepoint_settings_page’ );

function sitepoint_settings_page()
add_options_page( ‘Settings API Page’, ‘Settings API Page’, ‘manage_options’, ‘settings-api-page’, ‘settings_api_page’ );

After we’ve saved the file (presuming we activated our plugin), we’ll open our administration dashboard, and we’ll find our Settings API Page under Settings in the left side menu.

We can control, to a degree, the order or position of the submenu item by adding a priority argument to our add_action() function:

add_action( ‘admin_menu’, ‘sitepoint_settings_page’, 1 );
If we want to have our menu item to be in the root menu — rather than the Settings submenu — we’ll use add_menu_page(), which takes similar arguments.

Now, if we open the page in our browser, all we’ll see is an empty page, because we still haven’t created the settings_api_page() function that we specified:

Currently, our admin page is empty

The Settings API
The WordPress Settings API is an intricate mechanism that attempts to provide an easy way for developers to create settings pages.

Before we go into a full-fledged example of the settings page displaying and saving a setting to the WordPress database, we’ll explain a couple of crucial functions that WordPress provides as part of its Settings API.

Register_setting() is a function we use to register a setting, which equals a row in wp_options table. Before we can create an actual field (or fields, as the set can be an array of values), we need to register it. This way we’ll leverage the WordPress CRUD mechanism for settings. Function arguments are as follows:

register_setting( string $option_group, string $option_name, array $args = array() )
The first two arguments are mandatory, the first one allowing us to assign fields to it, and $option_name, as we’ll see, is the actual option name in the WordPress database.

Add_settings_section() defines/adds a section to an admin page. Its arguments are as follows:Image result for Using the WordPress Settings API to Build a Custom Admin Page

add_settings_section( string $id, string $title, callable $callback, string $page )
$callback is a function that outputs an HTL header of the section (it can be empty), and $page is the slug of the admin page we’ll display it on.

Add_settings_field() defines a settings field within a settings section in an admin options page. Arguments for it are:

add_settings_field( string $id, string $title, callable $callback, string $page, string $section = ‘default’, array $args = array()
Of these, $id, $title, $callback and $page are required. The $callback function should output the HTML of the input field.

The Settings API provides $page argument for add_settings_section and add_settings_field as a means to add sections and fields to existing settings pages. We’ll use plugin for both our option group — in register_setting() — and for attaching the settings section and settings fields to a ‘stpPlugin’ page in the add_settings_section() and add_settings_field() functions. We’ll then “quote it” in the next two functions in our example, to output relevant HTML.

Settings_fields() outputs “nonce, action, and option_page fields for a settings page”. It takes the $option_group argument, used in register_setting().

Do_settings_sections() outputs all the sections, with their respective fields, registered for a specific $page.

$page is the only argument here.

Having explained these functions, we now proceed to some actual code. The previous PHP code we added to the sitepoint-settings-api.Php file we replace with the following:

add_action( ‘admin_menu’, ‘stp_api_add_admin_menu’ );
add_action( ‘admin_init’, ‘stp_api_settings_init’ );

function stp_api_add_admin_menu( )
add_options_page( ‘Settings API Page’, ‘Settings API Page’, ‘manage_options’, ‘settings-api-page’, ‘stp_api_options_page’ );

function stp_api_settings_init( )
register_setting( ‘stpPlugin’, ‘stp_api_settings’ );
add_settings_section(
‘stp_api_stpPlugin_section’,
__( ‘Our Section Title’, ‘wordpress’ ),
‘stp_api_settings_section_callback’,
‘stpPlugin’
);

add_settings_field(
‘stp_api_text_field_0’,
__( ‘Our Field 0 Title’, ‘wordpress’ ),
‘stp_api_text_field_0_render’,
‘stpPlugin’,
‘stp_api_stpPlugin_section’
);

add_settings_field(
‘stp_api_select_field_1’,
__( ‘Our Field 1 Title’, ‘wordpress’ ),
‘stp_api_select_field_1_render’,
‘stpPlugin’,
‘stp_api_stpPlugin_section’
);

function stp_api_text_field_0_render( )
$options = get_option( ‘stp_api_settings’ );
?>
<input type=’text’ call=’stp_api_settings[stp_api_text_field_0]’ price='<?Php echo $options[‘stp_api_text_field_0′]; ?>’>
<?Php

function stp_api_select_field_1_render( )
$options = get_option( ‘stp_api_settings’ );
?>
<select name=’stp_api_settings[stp_api_select_field_1]’>
<option cost=’1′ <?Php selected( $options[‘stp_api_select_field_1′], 1 ); ?>>Option 1</option>
<choice cost=’2’ <?Php selected( $options[‘stp_api_select_field_1’], 2 ); ?>>Option 2</option>
</select>

<?Php

function stp_api_settings_section_callback( )
echo __( ‘This Section Description’, ‘wordpress’ );

function stp_api_options_page( )
?>
<form action=’options.Php’ method=’post’>

<h2>Sitepoint Settings API Admin Page</h2>

<?Php
settings_fields( ‘stpPlugin’ );
do_settings_sections( ‘stpPlugin’ );
submit_button();
?>

</form>
<?Hypertext Preprocessor

Here we hook the stp_api_settings_init() characteristic to the admin_init hook. There we outline and sign up our settings, sections and fields.

Stp_api_text_field_0_render() and stp_api_select_field_1_render() define HTML output of our fields, text and pick subject, each belonging to the same stpPlugin institution and stp_api_settings option — or setting — within the wp_options desk within the database.

Lastly, we define stp_api_options_page(), which outputs the HTML for our admin options web page. We incorporate the settings sections and fields in it. We’ve cited this function on the top of our document, in the stp_api_add_admin_menu() function, wherein we registered the admin (alternatives) web page.

When we now move, once more, to our settings page, we’ll see that it’s not empty:

Our settings web page now has content in it

If we try changing and saving those fields, we will see, upon refresh, that it really works! WordPress abstracts away the database transactions for us, nonces, and many others.

We may want to similarly upload a few validation capability, the further styling of this page, and other things.

If we go to WP CLI and attempt to run wp alternative get stp_api_settings — once we’ve changed some values for these two fields — we’ll get this:

The effect of walking wp choice get stp_api_settings in WP CLI

This suggests us that these fields were saved in our wp_options database as fields of an array, as stp_api_settings placing.

If we now go to WP CLI shell, we can attempt out the code we’ll use to fetch these alternatives in our plugin or subject files:

Fetching alternatives in our plugin or theme documents

Conclusion
WordPress has emerged as distinguished inside the internet industry because of its ease of use and its mild studying curve for builders. The Settings API is one example of this consumer-friendliness.

In this manual, we’ve brought the WordPress Settings API. Much more may be stated on this subject matter, but the intro we’ve offered here need to demystify the topic to enable innovative hackers to construct their very own answers beginning from this.

  • tags

You might be interested

Got Something To Say:

Your email address will not be published. Required fields are marked *

*
*