To plugin developers WordPress offers the Settings API. It lets us
define settings pages, sections within those pages and fields within the sections.
WordPress Settings API
We use WordPress options to store configuration variables for our plugins. The settings API lets us create pages in the WordPress back-end dashboard to allow users to enter and update those configuration variables.
The Settings API lets us add pages, sections, and settings to the dashboard. Those maintain an options object with one or more fields in it. The objective is to make it so other code in the plugin can use a call like get_option( ‘my-plugin-options’ ) to access the options object.
Example
Let’s use a simple example. Let’s say we’re working on a plugin named “My Plugin”. And let’s say we need two fields, named level and authcode, in its options. Here are the names we need to get started.
All these names are short text strings, and none need be localized to other human languages.
| Item | Item Name | Explanation | Notes |
|---|---|---|---|
| Plugin Slug | my-plugin | Short name for the plugin | Must be unique among all plugins. |
| Options Name | my-plugin-options | The name of the options object. | Must be unique among all options. |
| Options field names | level, authcode | The names of fields in the options object. | Associative array elements in the options object. |
| Settings page slug | my-plugin-settings-page | A name for the settings page. | Often the same as the plugin slug. |
| Settings section slug | section1 | A name for the section in the settings page | |
| Settings field slugs | level, authcode | Names for fields in the settings section. |
We need to use these names correctly in the code for our settings page.
Code
Notice where the various names appear in this sample code. Putting the correct names in the correct parameters to all the function calls allows WordPress to weave together, present, and update the desired options page.
Especially notice, in the callbacks from the two add_settings_field calls, how the name attributes of the <input> tags are "my-plugin-options[level]" and "my-plugin-options[authcode]".
function my_plugin_admin_menu() {
/* Make sure default option field settings are available. */
$option = get_option( 'my-plugin-options' );
if ( ! $option || ! is_array( $option ) ) {
update_option( 'my-plugin-options',
[ 'level' => '0', 'authcode' => 'Not Yet Set' ] );
}
/* Tell WordPress about these settings */
register_setting(
'my-plugin-settings-page',
'my-plugin-options',
[
'sanitize_callback' => function ( $option ) {
/* A filter to check the option's fields when the user pushes Submit */
return $option;
},
] );
/* set up the page in the dashboard */
add_options_page(
__( 'Option for My Plugin', 'my-plugin' ),
__( 'My Plugin', 'my-plugin' ),
'manage_options',
'my-plugin-settings-page',
function () {
/* A callback to render the options page HTML. */
/* No user privilege? No page. */
if ( ! current_user_can( 'manage_options' ) ) {
return;
}
/* emit the page. */
settings_errors( 'my-plugin-settings-page' ); ?>
<div class="wrap">
<h2 class="wp-heading-inline"><?php echo get_admin_page_title(); ?></h2>
<form id="my-plugin-optons" method="post" action="options.php">
<?php
settings_fields( 'my-plugin-settings-page' );
do_settings_sections( 'my-plugin-settings-page' );
submit_button();
?>
</form>
</div>
<?php
} );
add_settings_section(
'my-plugin-options',
__( 'Configuration', 'my-plugin' ),
function () {
/* empty, intentionally */
},
'my-plugin-settings-page'
);
add_settings_field(
'level',
__( 'Level', 'my-plugin' ),
function () {
$options = get_option( 'my-plugin-options' );
$optionName = 'level';
$optionValue = $options[ $optionName ];
?>
<input type="text"
id="<?php echo $optionName ?>"
name="my-plugin-options[level]"
size="50"
value="<?php echo esc_attr( $optionValue ); ?>"/>
<p class="description">
<?php echo esc_html__( 'Level', 'my-plugin' ) ?>
</p>
<?php
},
'my-plugin-settings-page',
'my-plugin-options' );
add_settings_field(
'authcode',
__( 'Authorization Code', 'my-plugin' ),
function () {
$options = get_option( 'my-plugin-options' );
$optionName = 'authcode';
$optionValue = $options[ $optionName ];
?>
<input type="text"
id="<?php echo $optionName ?>"
name="my-plugin-options[authcode]"
size="50"
value="<?php echo esc_attr( $optionValue ); ?>"/>
<p class="description">
<?php echo esc_html__( 'Authorization Code', 'my-plugin' ) ?>
</p>
<?php
},
'my-plugin-settings-page',
'my-plugin-options' );
}
add_action( 'admin_menu', 'my_plugin_admin_menu' );