Settings API Step by Step

Resources on WordPress Settings API Step by Step

Creating custom settings/options page in wordpress admin panel is an easy task if you know what you’re doing. Here is a step by step tutorial on that.

 Create settings page

First of all we need to create our page. We have two choices:

– Create separate page

To create a separate settings page we will use this code

add_menu_page creates our settings page. We have given it the following parameters:

page_title – The text to be displayed in the title tags of the page when the menu is selected. We have named our settings page “REWP Settings”
menu_title -The text to be used for the menu. We have named our settings menu element “REWP Settings”

capability – The capability required for this menu to be displayed to the user. We chose to let only administrators access and change our settings by choosing manage_options capability. Other capabilities can be found here

menu_slug – The slug name to refer to this menu by (should be unique for this menu). We made our slug “re-wp-settings”

function – The function to be called to output the content for this page. We created the rewp() function which echoes some html (for now). Everything we put in it will be displayed on our settings page

The function that creates our settings page must be hooked to amin_menu.

Resources on WordPress Settings API Step by Step settings

– Create submenu page

Sometimes we need to add our settings page as a submenu to Settings, Tools etc. There is a different function that adds pages to the main menus. They all have the same syntax so will see only how to add submenu to Settings. To do this we need to use add_options_page

There are minor differences between add_menu_page and add_optons_page (add_menu_page accepts a few more parameters), but in our case the parameters are the same.

Resources on WordPress Settings API Step by Step settings

Create the options and output them on our page

Now it’s time to create our options and fill our settings page with them. We will be using a few functions which will take care of the whole process.
We will start by adding capabilities check and a form to our rewp function. The method must be post and the action – options.php.

Now the only change is a button “Save Changes”. This is because we don’t have any options yet. To create options we will use register_setting, add_settings_section and add_settings_field. To begin we create a function called rewp_options and hook it to admin_init.

Register settings, add_settings_section and add_settings_field

register_setting adds a setting to a group (the first parameter. We use it in add_settings_fields), creates a row in wp_options (second parameter) and can take a third parameter generally used for data validation.

add_settings_section takes id, title, callback (which may be used for description, instructions etc), page (this parameter is used later)

add_settings_field is the option. We need to give it id, title, section and callback.

Create the callback functions

Now we can start with the options. First we create sections callback. This is optional but useful when we need to output something section specific. Here is the first section’s callback function:

After that we can create the options. We create our add_settings_field callback functions and write our inputs in it.

Remember the rewp() function. We need to add settings_fields( ‘rewp-group’ ); and do_settings_sections( ‘rewp’ ); to it and as a result our settings are displayed on the page


For security purposes we need to do a few more things. add_settings_field creates a nonce hidden field and saves us the trouble. We still need to validate and sanitize the data that goes to the database therefore we have to create a function which executes just before the settings are saved. register_setting’s third parameter is the name of such function and we can use for handling security.

We have only two input fields so we only sanitize them, but we can do more complex validations. If we want to whitelist the options of a select as the only accepted input, we could do something like this:

As a result only the whitelisted options will be accepted and saved in the database. Any other input will trigger an error.

Using the options

Finally you we can use our options. We can call your options everywhere using get_option( ‘option_name’ );

If we

we will see “there be dragons”

Spread the love

One response to “Settings API Step by Step”

Leave a Reply

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