The WordPress Settings API allows developers to create settings and settings pages for their plugins/themes. In terms of functionality – the Settings API works in a similar way to the Options API when using it for only a few settings – but becomes more robust the further you dig. Below is a description of the Settings API from the Codex:

The Settings API, added in WordPress 2.7, allows admin pages containing settings forms to be managed semi-automatically. It lets you define settings pages, sections within those pages and fields within the sections.

New settings pages can be registered along with sections and fields inside them. Existing settings pages can also be added to by registering new settings sections or fields inside of them.

Organizing registration and validation of fields still requires some effort from developers using the Settings API, but avoids a lot of complex debugging of underlying options management.

An Example

For the example we will be looking at specific parts of a weather plugin. The plugin requires an API key so that’s what we will be saving as our setting. This is actually just the code from my DobsonDev Weather Plugin. I created it one day because I was having trouble with the other weather plugins that I normally use for clients – but the CSS is hard to maintain for every website so it still needs some work in that department for sure. But the backend code works great and that’s what we’re looking at today.

Create the Menu

The first thing we have to do is create the menu item. We can do this be using the following code:

There are a couple of important things to note when using the Settings API that come up here. Lets look at the call to add_submenu_page( … ) first. Below is the usage for the function:

First – note that we call ‘options-general.php’ as our parent slug. This means that our settings page will appear under the “Settings” heading on the backend of WordPress. You can view all the different parent page slugs on the Codex page. Using the __FILE__ as our menu slug will give the page the slug ?page=dobsondev-weather-app/dobsondev-weather-app.php. This is fine for me because I don’t really mind it looking like that and it guarentees it will be unique – but if you want a bit of a nicer URL just fill in whatever you want there. Finally we define our function that generates the page: ‘dobsondev_weather_settings’.

You’ll also most likely notice we made a call to add_action( … ) during the ‘admin_init’ to a function called ‘dobsondev_weather_settings_register’. This is actually where we register our setting and we will be looking at that next. The call to add_action( ‘admin_menu’, ‘dobsondev_weather_create_menu’ ) simply adds our new menu items to the menu.

Register Our API Key Setting

The ‘dobsondev_weather_settings_group’ is the settings group for the setting. If we had more than one setting they would still all be in the same group since they all work with the plugin (most likely – there are exceptions to this of course). This also needs to match the call we make to settings_fields( … ) later – so keep the group name you choose in mind.

‘dobsondev_weather_api_key’ is the name of the individual setting – in this case our API key. It belongs to the settings group we defined before it and it is access by calling get_option(‘dobsondev_weather_api_key’).

The Setting Page

The code above is everything needed to generate and manage your API key setting. I won’t be going over the basic HTML stuff here because I want to concentrate on the PHP, so hopefully you can follow along with whats happening with the HTML.

There is only one important PHP function call in this section. The settings_fields( ‘dobsondev_weather_settings_group’ ); function call is super important as it creates the nonce, action, and option_page fields for our settings page. It’s very important to note that you have to do this call from within the form or it will not work.

Once you have made your call to settings_fields( ‘dobsondev_weather_settings_group’ ); you can access your settings using get_option( ‘setting_name’ ). If you have more than one setting this will still work you just have to use the other settings name. It’s also important to make sure the input’s have the same name as their settings name – that way they will automatically save when the submit button is hit.

Conclusion

That’s all you really need to know to get your Settings working on your project. The rest of the plugin that I created is the widget and shortcode that output the weather application window. If you want to see all the code just download the DobsonDev Weather Plugin from the repository and check out the source code. It will have everything you need to see in there. Hopefully this will help those who weren’t aware of the settings a solid example that they can then modify for their own use.

As always thank you for reading and please share it around as much as you can! Please feel free to put any suggestions or ideas for future tutorials in the comments section below.