WordPress Settings Api

 The WordPress Settings API was added in WordPress 2.7 and is one of the most popular WordPress APIs. The Settings API allows admin pages to have fields for customizing the way the WordPress theme works. The Settings API is a set of functions to support adding Custom Menus, WordPress Theme options and other Option Pages for themes. These also include API for saving, validating, and retrieving values from user input. Theme developers can use the API to add more powerful and interactive options to their themes. Settings API is a convenient and secure method to add WordPress theme options and validating user inputs. The Settings API is a complete package that handles all aspects of adding admin options in WordPress. Using the Settings API involves some coding effort for the developers. However, they no longer need to work on complex debugging of the options management framework. Using the Settings API is not mandatory. Developers can still write their settings page without using this API. Nevertheless, the Settings API offers developers with several benefits that cannot be overlooked:

• Visual Consistency with WordPress UI: The settings page would look like other administrative content.
• Ease of Use for developers: The WordPress API adds lots of inbuilt support like for handling retrieving and storing of settings data.
• WordPress hardened security with extra security measures: WordPress developers get access to secure methods of sanitizing data.
• Robustness for the website: The API code is well tested and maintained making it more stable.
• Compatibility with WordPress Core: This provisions that any updates automatically handle the custom settings page.

How WordPress Settings API work

The Settings API offer the developers with complete capabilities to customise the settings page. They can register new settings pages or modify existing settings pages and register new settings or fields. Let us look at the structure of a theme setting and how developers can create and add their own settings.

Components of a Theme Setting

A theme setting that is added to the customizer screen consists of three parts:

1. Section is a collection of fields. There should be at least one field in every section on a page. You can add new sections to existing settings pages or create a whole new settings page.
2. Fields are the individual settings that you want to provide users with control to modify the values.
3. Settings are combinations of the fields and sections and are registered in the database. You need to register the setting after defining both Fields and Sections.

The sample code demonstrates the use of this API to add a new section to the default “Reading” settings page. Place this code in your functions.php file for the theme.

Take note that the API is called from the test_custom_settings function defined earlier where we added the theme section named “first_section”.

Function test_custom_settings () {

add_settings_section (

'first_section', //section name for the section to add

'New Reading Settings', //section title visible on the page

'reading_section_description', //section description

'Reading'//page to which section will be added.

);

add_settings_field (

'first_field_option' //ID for the settings field to add

'TestField', //settings title visible on the page

'options_callback', //callback for displaying the settings field

'Reading', // settings page to where option is displayed

'first_section'// section id for parent section.

);

}

//callback for displaying setting description

function reading_section_description () {

echo '<p>This is the new Reading section. </p>';

}

//callback for displaying the setting field

function options_callback ($args){

echo '<p>This is the new Reading setting callback. </p>';

}

//admin hook defined in functions.php. This calls the above function at

// initialization time.

add_action('admin_init', 'test_custom_settings' );

API: get_option – Retrieves an option value based on an option name. Use this API to get the default option value saved in the database or the value entered by the user in the theme setting UI. Use this API when you want to take further action based on what the user has selected. This includes changing the theme layout, adding specific features to the theme etc.