WordPress offers many APIs for us to use. In our previous tutorials, we talked about how to create forms in the WordPress admin with HTML. While it was relatively simple, it’s time consuming to set up our form, validate the info, update and set values. Luckily, WordPress introduced the WordPress settings API in version 2.7.
Why use the WordPress Settings API?
The WordPress settings API was created by the WordPress team to help developers extend the core of WordPress. It makes validating, retrieving, updating, displaying and sanitizing data easier for us. While using HTML may seem simple, it can become really difficult to manage if you have hundreds of options. The WordPress settings API is only a couple of functions, but with a lot of parameters. I will break down and explain each one for you.
Create a new WordPress plugin named wpSettingsEx. Here’s our index.php file.
* Plugin Name: WP Settings API Example
* Plugin URI: http://jaskokoyn.com
* Description: A Basic WordPress to show how the Settings API works.
* Author: Jasko Koyn
* Version: 1.0
* Author URI: http://jaskokoyn.com
// Set up our WordPress Plugin
if ( version_compare( get_bloginfo( 'version' ), '3.1', '<' ) )
wp_die("You must update WordPress to use this plugin!");
if ( get_option( 'jk_social_data' ) === false )
$options_array['jk_social_youtube_username'] = 'jaskokoyn';
$options_array['jk_social_facebook_page'] = 'jaskokoyn';
$options_array['jk_social_twitter_username'] = 'jaskokoyn';
$options_array['jk_social_plugin_version'] = '1';
add_option( 'jk_social_data', $options_array );
register_activation_hook( __FILE__, 'jk_social_check_WP_ver' );
// Include or Require any files
// Action & Filter Hooks
Pretty simple what’s going on here. When our plugin is activated, we create an array of options. This plugin will manage social profile for YouTube, Facebook and Twitter. It sets some default values and then adds that option in the option table. You’ll also notice I prefix everything with jk_social to keep our plugin unique.
We then include 2 files that will include our functions that will handle displaying the menu and form. Create these 2 files in the inc folder right now and leave them blank for now.
Next, we add 2 actions that will hook into 2 things. In the first hook we’ll be adding the menu and the 2nd item is where we’ll begin adding our settings. Let’s open up our menu.inc.php file and add this bit of code.
add_options_page('Settings API', 'Settings API', 'administrator', __FILE__, 'jk_social_display_settings');
This function will run when our first hook is fired. We’re introduced to a new function called add_options_page(). This function is the same as the add_submenu_page(), but a big difference is that the add_submenu_page() can add a submenu to ANY top level menu while the add_options_page() can only add a submenu to the settings top level menu specifically. Let’s quickly go over what each parameter is for.
- Page Title – This will be displayed at the top of the browser.
- Menu Ttile – This is the title that will be displayed in our menu.
- Capability – What capability our user must have in order to be able to see this menu. A list of capabilities can be found here.
- Menu Slug – The menu slug that this page will be referred to. Must be unique.
- Function – The function that should be called when this menu item is active. This parameter is the only optional parameter in the function.
We’re doing nothing new here, but hopefully you understand what’s going on so far. Let’s open up our display-admin.inc.php file and add this bit of code.
Alright we have 2 empty functions here. Our jk_social_display_settings() is the function that will be called when the user clicks on out Settings option submenu. This function will be responsible for displaying our form.
Our next function is jk_social_init_register_settings(). If we visit our index.php file and take a look at our hook section, we can see that this function is called when we hook into the admin_init action. This function will register our setting. The difference between these 2 functions is that one will be displaying while the other will be preparing it. The admin_init action is called first way before the admin_menu hook is called. We need to set up our settings before we can call them. That way, when we display our settings, it can easily be called and not have everything mixed with one another.
That’s it for this part of the series. In the next part, we’ll be actually working with the settings API.