Guide to WordPress Settings API

I have decided to explain how to use the WordPress Settings API after having pulled out most my hair whilst googling for a easy to understand explanation.

The reason I wanted to use the WordPress Settings API was because whilst making plugins, I found that my code for my options page was getting a little messy. I had also read, that if you use the Settings API, you don’t ever have to use the update_option() function.

Finally, being a WordPress API, I would like to think that this make my plugins a little more future-proof against wordpress upgrades.

Please note that in this walkthrough I am storing the options into an array.

So this is how it is done:

add_action('admin_menu', 'create_plugin_options_page');
add_action('admin_init', 'register_and_build_plugin_options');

function create_plugin_options_page() {
  //register the menu item
  add_menu_page('Plugins Option', 'Plugin Options', 'administrator', 'option-page-name', 'plugin_options_page');
}

function register_and_build_plugin_options(){
  //register the option value you will be using.
  //N.B. the second parameter must be the same as what you have named the option in your plugin activation
  register_setting('settings_option','plugin_settings', 'validate_option');
  add_settings_section('first_setting_section', 'Settings Section 1','section1_callback','option-page1');
  add_settings_field('setting_text','Text Field: ','text_field','option-page1','first_setting_section');
}

You can have lots of fields in lots of sections. Important things to note when using add_settings_section, add_settings_field, register_setting:

  • The 3rd parameter of register_setting is a callback for validation. In the example above, I have a function (shown later) called validate_option which contains any required validation. This field is optional.
  • The 4th parameter of add_settings_field must correlate to a 1st parameter of add_settings_section
  • The 4th parameter of add_settings_section which should be the same as the 4th parameter of add_settings_field (‘option-page1′) is what you will later use to load this section by using the function do_settings_section();
  • The 3rd parameter of add_settings_section is a callback function. It can be a blank function if you want it to be.
  • The 3rd parameter of add_settings_field is a callback function that contains the input field that you want.
This is the callback function with input field:
function text_field(){
	  $optionValue = get_option('plugin_settings');
    $option = "";
    $option .= "";
    echo $option;
}

You must name the field by the option name so it will save correctly, like I have done above with name=\”plugin_settings[text_field]\”.

Now finally, the function that brings it all together:

function plugin_options_page() {
?>
<div id="theme-options-wrap">
<h2>Plugin Title</h2>
<div><form action="options.php" method="post"> 
<p class="submit"><input class="button-primary" type="submit" name="Submit" value="<?php esc_attr_e('Save Changes'); ?>" /></p>

</form></div>
</div>
<div id="theme-options-wrap">
<h2>Plugin Title</h2>
<div><form action="options.php" method="post"> 
<p class="submit"><input class="button-primary" type="submit" name="Submit" value="<?php esc_attr_e('Save Changes'); ?>" /></p>

</form></div>
</div>
<?php
}

function validate_option($option){
    //put any validation on the options here.
    return $option;
}

function section1_callback(){}

function section2_callback(){
	$html = "An example of some text in the callback function";
	echo $html;
}

function text_field(){
	  $optionValue = get_option('plugin_settings');
    $option = "";
    $option .= "
<input id=\"text_field\" type=\"text\" name=\"plugin_settings[text_field]\" value=\"{$optionValue['text_field']}\"?-->";
    echo $option;
}

function select_field(){
    $options = get_option('plugin_settings');
    $items = array("Red", "Green", "Blue", "Orange", "White", "Violet", "Yellow");
    $html = "
    <select id="select_field" name="plugin_settings[select_field]">";
    foreach($items as $item) {
        $selected = ($options['select_field']==$item) ? 'selected="selected"' : ''; $html .= " <option selected="selected" value="$item">$item</option> ";
    }
    $html .= "</select>";
    echo $html;
}
function checkbox_field(){
    $optionValue = get_option('plugin_settings');
    $option = "";
    $option .= " <input type="\"checkbox\"" name="\"plugin_settings[checkbox_field]\"" value="\&quot;1\&quot;" checked="checked" />";
    echo $option;
}
function radio_field(){
    $optionValue = get_option('plugin_settings');
    $option = "";
    $option .= " <input type="\"radio\"" name="\"plugin_settings[radio_field]\"" value="\"value1\"" checked="checked" />Value1 ";
    $option .= " <input type="\"radio\"" name="\"plugin_settings[radio_field]\"" value="\"value2\"" checked="checked" />Value2 ";
    echo $option;
}

This will allow you to have a settings page that looks like:

Quite a Mouthful! However I hope this really helps for people trying to get to grips with API. Admittedly, I have written this partly as a response to lack of documentation on the API!

If you would like more help, I found this documentation helpful: http://www.presscoders.com/wordpress-settings-api-explained/

2 thoughts on “Guide to WordPress Settings API”

  1. It’s the fifth “parameter of add_settings_field must correlate to a 1st parameter of add_settings_section” not 4th ;-)

Leave a Reply

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

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>