• About Us
    • New York
  • Work
  • Capabilities
  • Careers
  • Technology
  • Blog
  • Contact Us
  • About Us
    • New York
  • Work
  • Capabilities
  • Careers
  • Technology
  • Blog
  • Contact Us
August 03, 2012

How to Use the WordPress Settings API

Posted by Christopher Davis

The WordPress settings api is a collection of functions that allows you to extend existing admin pages with your own fields or create new pages.  In this tutorial, we’ll cover how to do both.

Overview

The settings api is comprised of several functions.  The most important of which are:

  • register_setting – Registers our setting with WordPress, which lets us take advantage of using options.php to handle saving the data.
  • add_settings_section – Adds a section (meaning a collection of fields) to a page.
  • add_settings_field – Adds a field to a section on a given page.

All of this is very abstract.  So we’re going to start small.

The Simplest Example

The simplest possible example is adding a field to an already existing page and already existing section.  Let’s add a field to the general options page.

Registering the Setting

First up, we need to hook into admin_init and call register_setting.  register_setting takes two required arguments: the page on which the setting will live (“general” in this case) and the settings name.  The third argument is optional, but extremely useful – we’ll cover it later.


<?php

add_action(‘admin_init’, ‘pmgtut_simple_settings_register’);

/**

* Hooked into ‘admin_init’ this is the central function that takes care of

* registering the setting, addint sections and adding fields

*

* @since   1.0

* @uses    register_setting

* @uses    add_settings_section

* @uses    add_settings_field

*/

function pmgtut_simple_settings_register()

{

// our setting name

$name = ‘pmgtut_setting_simple’;

// our settings page, we’re going to add options to the “general” page

$page = ‘general’;

// The section to which we’ll add things

$section = ‘default’;

// ‘register_setting is the central call.  This Let’s WP know about your

// setting.  You **MUST** call this first

register_setting($page, $name, ‘pmgtut_simple_validator’);

}

Adding a Settings Field

The next step is example our function a bit to include a call to add_settings_field.  As the name implies, this function tells WP to add an additional input field.


<?php

function pmgtut_simple_settings_register()

{

// our setting name

$name = ‘pmgtut_setting_simple’;

// our settings page, we’re going to add options to the “general” page

$page = ‘general’;

// The section to which we’ll add things

$section = ‘default’;

// ‘register_setting is the central call. This Let’s WP know about your

// setting. You **MUST** call this first

register_setting($page, $name, ‘pmgtut_simple_validator’);

// at this point WP knows about your setting.

// Lets add a new field field to the default section

add_settings_field(

‘pmg-example-simple’, // field ID not used for much

__(‘Simple Field’, ‘pmg’), // the label for our field

‘pmgtut_simple_field_cb’, // this is the callback function

$page, // page to place our field on

$section // section to place our field in

);

}

The crucial argument of add_settings_field is the third.  This is the callback function. As the page where that setting was registered loads, WordPress will call your callback function.  This function is responsible for spitting out a form field.  Here’s the simple example:


<?php

function pmgtut_simple_field_cb()

{

echo ‘works’;

}

Example Settings Field

As exciting as that is, let’s make our field callback actually do something.  Most important thing here: the name attribute of our field MUST match up with the name of our registered setting.  This will become clear a bit later.


<?php

/**

* the settings callback function. This spits out the form field

*

* @since   1.0

* @uses    get_option

*/

function pmgtut_simple_field_cb()

{

// Name of our setting, same as we registered

$setting = ‘pmgtut_setting_simple’;

// step one: get the value in our option with get_option

$val = get_option($setting, ”);

// spit out the form field

printf(

‘<input type=”text” class=”regular-text” name=”%1$s” id=”%1$s” value=”%2$s” />’,

esc_attr($setting),

esc_attr($val)

);

}

Example Settings Field

Using the Validation Callback

Remember that third argument of register_setting?  That is a settings validation callback.

When you hit save on a given admin options page, WordPress submits a POST request to wp-admin/options.php.  From here, WordPress validates nonces and referrers for you.  Assuming everything is okay, WP will then look for fields named after all the registered settings assigned to each page.  If the third argument of register setting is present, WP will call that function name, passing in the values of all the fields with that settings name.  In this example, there’s only one field.

Let’s pretend we want to make sure that an email is entered in that field.  We can use the built in is_email function to check.  If it is a valid email, we’ll simply return the value from our callback function.  Otherwise, we’ll add a settings error to give our user feedback.


<?php

/**

* Validation callback function. Makes sure we have an email address or adds

* a settings error to give the user feedback.

*

* @since   1.0

* @uses    add_settings_error

* @uses    is_email

* @return  string The email or an empty string

*/

function pmgtut_simple_validator($value)

{

if(is_email($value))

{

// we have a valid email, return it

return $value;

}

// not a valid email. Add a settings error.

add_settings_error(

‘pmgtut_setting_simple’, // setting name

‘pmgtut-no-email’, // Code, used int he ID att of the error

__(‘Please enter a valid email’, ‘pmg’), // error message

‘error’ // type of error: updated?  error, in this case

);

// return an empty string

return ”;

}

Settings Error Example

Slightly More Complicated Example

Instead of just adding a field, let’s add an entire section and add several fields to that section.  We start off the same way: hook into admin_init and register the setting.  At that point, we also need to add a section with add_settings_section.

add_settings_section takes four arguments: a section id (we’ll use this later to add fields), The section title, a callback to spit out something like help text, and the page (options group) on which the section will reside.


<?php

add_action(‘admin_init’, ‘pmgtut_settings_register’);

/**

* Hooked into ‘admin_init’ this is the central function that takes care of

* registering the setting, adding sections, and adding fields

*

* @since   1.0

* @uses    register_setting

* @uses    add_settings_section

* @uses    add_settings_field

*/

function pmgtut_settings_register()

{

// our setting name

$name = ‘pmgtut_setting’;

// our settings page, we’re going to add options to the “general” page

$page = ‘general’;

// The name of our section

$section = ‘example-section’;

// ‘register_setting is the central call. This Let’s WP know about your

// setting.  You **MUST** call this first

register_setting($page, $name, ‘pmgtut_validator’);

// at this point WP knows about your setting.

// Lets add a new section

add_settings_section(

$section, // our section id

__(‘Example Section’, ‘pmg’), // the title.  Gets put in an <h3> in the admin area

‘pmgtut_section_cb’, // name of our callback function.

$page // what page the section lives on

);

}

Of particular note is the callback function for add_settings_section. This can be used to spit out help text.  Our example is simple:


<?php

/**

* Section callback function.  Can be used to spit out some help text or

* whatever you like.

*

* @since   1.0

* @uses    esc_html__

* @return  null

*/

function pmgtut_section_cb()

{

echo ‘<p class=”description”>’ . esc_html__(‘Help text here’, ‘pmg’) . ‘</p>’;

}

Example Settings Section

If you don’t want to mess with a callback, you can pass in __return_false — a built in WordPress function that as, the name implies returns false — to add_settings_section.  In this case __return_false will do nothing.


<?php

add_settings_section(

$section, // our section id

__(‘Example Section’, ‘pmg’), // the title.  Gets put in an <h3> in the admin area

‘__return_false’, // name of our callback function.

$page // what page the section lives on

);

 

Adding Fields

Just like our simple example above, we can add fields with add_settings_field. Let’s add two fields in this case: one for an email and one for a string.


<?php

/**

* Hooked into ‘admin_init’ this is the central function that takes care of

* registering the setting, adding sections, and adding fields

*

* @since   1.0

* @uses    register_setting

* @uses    add_settings_section

* @uses    add_settings_field

*/

function pmgtut_settings_register()

{

// our setting name

$name = ‘pmgtut_setting’;

// our settings page, we’re going to add options to the “general” page

$page = ‘general’;

// The name of our section

$section = ‘example-section’;

// ‘register_setting is the central call.  This Let’s WP know about your

// setting.  You **MUST** call this first

register_setting($page, $name, ‘pmgtut_validator’);

// at this point WP knows about your setting.

// Lets add a new section

add_settings_section(

$section, // our section id

__(‘Example Section’, ‘pmg’), // the title.  Gets put in an <h3> in the admin area

‘pmgtut_section_cb’, // name of our callback function.

$page // what page the section lives on

);

// We’ve now registered our setting and section.  Add the fields!

add_settings_field(

’email-field’, // field id

__(‘Your Email’, ‘pmg’), // field label

‘pmgtut_email_field_cb’, // field callback

$page, // option page/group

$section // settings section

);

add_settings_field(

‘normal-text-field’,

__(‘Some Text’, ‘pmg’),

‘pmgtut_normal_field_cb’,

$page,

$section

);

}

And our simple settings callbacks to test things:


<?php

/**

* Callback function for our email field

*

* @since   1.0

* @uses    get_option

*/

function pmgtut_email_field_cb()

{

echo ‘works’;

}

/**

* Callback function for our normal text field

*

* @since   1.0

* @uses    get_option

*/

function pmgtut_normal_field_cb()

{

echo ‘also works’;

}

Example Settings Section with Fields

Filling Out the Fields

Rather than clutter our database up with options, we’re going to save both those fields under the same option name as an array.  To do this, we need to make sure the name attribute of each of the fields follows this formula: settings_name[field_key] or name="pmgtut_setting[the_field]".  Our new settings fields callbacks follow.  You’ll notice a lot of repeated code, which sucks.  We’ll talk about how to get around that later.


<?php

/**

* Callback function for our email field

*

* @since   1.0

* @uses    get_option

*/

function pmgtut_email_field_cb()

{

// variable to use later

$setting = ‘pmgtut_setting’;

$field = ’email’;

// get our options

$opts = get_option($setting, array());

// Set up the value with a ternary statment

$val = isset($opts[$field]) ? $opts[$field] : ”;

// actually print the field

printf(

‘<input type=”text” class=”regular-text” id=”%1$s[%2$s]” name=”%1$s[%2$s]” value=”%3$s” />’,

esc_attr($setting),

esc_attr($field),

esc_attr($val)

);

}

/**

* Callback function for our normal text field

*

* @since   1.0

* @uses    get_option

*/

function pmgtut_normal_field_cb()

{

$setting = ‘pmgtut_setting’;

$field = ‘normal’;

// get our options

$opts = get_option($setting, array());

// Set up the value with a ternary statment

$val = isset($opts[$field]) ? $opts[$field] : ”;

// actually print the field

printf(

‘<input type=”text” class=”regular-text” id=”%1$s[%2$s]” name=”%1$s[%2$s]” value=”%3$s” />’,

esc_attr($setting),

esc_attr($field),

esc_attr($val)

);

}

Validating Options

When you save more than one value per option, your validation callback function will receive an associative array as its argument rather than a string.  You simply look for each of your fields, validate each, and return the array.


<?php

/**

* settings validation callback

*

* @since   1.0

* @uses    add_settings_error

* @uses    esc_attr

* @uses    is_email

* @return  array The cleaned options

*/

function pmgtut_validator($dirty)

{

$clean = array();

if(isset($dirty[’email’]) && is_email($dirty[’email’]))

{

// hooray email!

$clean[’email’] = $dirty[’email’];

}

else

{

add_settings_error(

‘pmgtut_setting’,

‘pmg-invalid-email’,

__(‘Please enter a valid email’, ‘pmg’),

‘error’

);

}

$clean[‘normal’] = isset($dirty[‘normal’]) ? esc_attr($dirty[‘normal’]) : ”;

return $clean;

}

Removing Duplicate Code

The settings API is amazing because it makes it easy for other developers to extend your work.  That’s why the WordPress core itself uses it.  The downside, of course, is that you end up with a lot of code to just do some simple stuff like printing out a form field. Having multiple fields means using multiple callback functions in most cases.  If you have two of the same field type, however, you can get around that.

add_settings_field takes an option sixth argument: an array of args.  This array is then passed into your callback function.  You can use this to pass in different options keys like the code below does.  First we have to modify our call to add_settings_field to include the final argument as well as a call to a unified callback.


<?php

/**

* Hooked into ‘admin_init’ this is the central function that takes care of

* registering the setting, adding sections, and adding fields

*

* @since   1.0

* @uses    register_setting

* @uses    add_settings_section

* @uses    add_settings_field

*/

function pmgtut_settings_register()

{

// our setting name

$name = ‘pmgtut_setting’;

// our settings page, we’re going to add options to the “general” page

$page = ‘general’;

// The name of our section

$section = ‘example-section’;

// snip snipp

// unified callback

$fields = array(

’email’  => __(‘Your Email’, ‘pmg’),

‘normal’ => __(‘Some Text’, ‘pmg’)

);

foreach($fields as $key => $label)

{

add_settings_field(

$key,

$label,

‘pmgtut_field_cb’,

$page,

$section,

array(‘key’ => $key) // option args

);

}

}

The unified field callback will just look in the args for a key and use that as the field name.  Otherwise it’s the same as our previous field callbacks.


<?php

/**

* Example of a unified callback

*

* @since   1.0

* @uses    get_option

*/

function pmgtut_field_cb($args)

{

// settings name

$setting = ‘pmgtut_setting’;

// get our options

$opts = get_option($setting, array());

// Set up the value with a ternary statment

$val = isset($opts[$args[‘key’]]) ? $opts[$args[‘key’]] : ”;

// actually print the field

printf(

‘<input type=”text” class=”regular-text” id=”%1$s[%2$s]” name=”%1$s[%2$s]” value=”%3$s” />’,

esc_attr($setting),

esc_attr($args[‘key’]),

esc_attr($val)

);

}

Concerning Multiple Calls to get_option

get_option fetchs values from the wp_options table in the database.  It’s goes without saying that hitting the database every time you need an option might get expensive and slow things down.

Fortunately, WordPress caches options from the start.  Calling get_option multiple times is no more expensive than calling any other function.

The Best Way to Use the Setting API

Wrapping all your settings api functionality inside a class is a great way to go.  It allows you to set up some class constants and other convenient things to make your life easier.  Our examples don’t benefit a ton from being wrapped in a class, but you can view an example on github.

Using the Settings API on Custom Admin Pages

This is also super easy.  AFter registering your page with add_options_page, you need to do a few specialized things inside the page callback.

settings_fields will take care of outputting a nonce and referrer field for you and do_settings_sections will make WordPress output all the fields.

Your page callback function might look something like this:


<?php

/**

* Menu page callback function

*

* @since   1.0

* @access  public

* @uses    settings_field

* @uses    do_settings_section

* @uses    screen_icon

*/

public static function menu_page_cb()

{

?>

<div class=”wrap”>

<?php screen_icon(); ?>

<h2><?php esc_html_e(‘Sample Options Page’, ‘pmg’); ?></h2>

<form action=”<?php echo admin_url(‘options.php’); ?>” method=”post”>

<?php

settings_fields(‘option_group_or_page’);

do_settings_sections(‘option_group_or_page’);

submit_button(__(‘Save Settings’, ‘pmg’));

?>

</form>

</div>

<?php

}

You can see a complete example on Github along with the rest of the code.

Developmentwordpresswordpress apiwordpress settings api
Previous
Next

Latest White Papers

  • Shifting Plans for 2020 & Beyond
  • Game On: How Brands Can Log Into A Diverse Multi-Billion Dollar Industry
  • What CCPA Means For Brands
  • How Google is Improving Consumer Data Privacy
  • Ways to Prepare for the Cookieless Future
  • See all White Papers

Featured Posts

  • Ad Age Names PMG #1 Best Place to Work in 2021
  • Hindsight 2020 & Looking Ahead to 2021
  • Preparing for Streaming’s Growth & The Future of TV Buying
  • MediaPost Names PMG Independent Agency of the Year
  • PMG Client Portfolio Trends During Amazon Prime Day 2020

Categories

  • Consumer Insights
  • Content
  • Creative Design
  • Data Analytics
  • Development
  • Digital TV & Video
  • Ecommerce
  • Industry News
  • Local
  • Mobile
  • Paid Search
  • PMG Culture
  • Programmatic & Display
  • SEO
  • Social Media
  • Structured Data
Fort Worth

2845 West 7th Street
Fort Worth, TX 76107

Dallas

3102 Oak Lawn Avenue
Suite 650
Dallas, TX 75219

Austin

823 Congress Avenue
Suite 800
Austin, TX 78701

London

33 Broadwick Street
London
W1F 0DQ

New York

120 East 23rd Street
New York, NY 10010

Get in touch

(817) 420 9970
info@pmg.com

Subscribe to the PMG Newsletter
© 2021 PMG Worldwide, LLC, All Rights Reserved
  • Contact
  • Privacy Policy
 Tweet
 Share
 Tweet
 Share
 Tweet
 Share
 LinkedIn
We and our partners use cookies to personalize content, analyze traffic, and deliver ads. By using our website, you agree to the use of cookies as described in our Cookie Policy.