WP Settings Api notes

Posted on January 16, 2017May 10, 2017 by PeterPan

The Settings API, lets you define settings pages, sections within those pages, and fields within the sections.

The form posts to wp-admin/options.php which provides strick capabilities checking and users will need to ‘manage_options’ capability to submit the form.

These are my quick notes for personal use, and they only resume the official wp codex.

Setting API functions

Basic example

Copy&paste this code to your functions.php file and then you’ll see an additional form appearing at settings-&gr;reading section.

 function eg_settings_api_init() {
 	// Add the section
 	add_settings_section( 
		'eg_setting_section', //id
		'Example settings section in reading', //title
		'eg_setting_section_callback_function',//callback
		'reading'//page
	); 
 	
 	// Add a field into the section
  	add_settings_field(
		'eg_setting_name',//id
		'Example setting Name',//title
		'eg_setting_callback_function', //callback
		'reading',//page
		'eg_setting_section'//section
	);
 	
 	// Register our setting so that $_POST handling is done for us and
 	// our callback function just has to echo the <input>
 	register_setting( 'reading', 'eg_setting_name' );
 } /* eg_settings_api_init() */
 
 add_action( 'admin_init', 'eg_settings_api_init' );

 // This function is needed if we added a new section. 
 // Will be run at the start of our section

 function eg_setting_section_callback_function() {
 	echo '<p>Intro text for our settings section</p>';
 }

 // creates a checkbox true/false option. Other types are surely possible
 
 function eg_setting_callback_function() {
 	echo '<input name="eg_setting_name" id="eg_setting_name" type="checkbox" value="1" class="code" ' . checked( 1, get_option( 'eg_setting_name' ), false ) . ' /> Explanation text';
 }

Register/Unregister settings

register_setting( $option_group, $option_name , $sanitize_callback )

$option_group: must already exists, and to match the group name in settings_fields().
$option_name: the name of an option to sanitize and save.
$sanitize_callback:(opt.) sanitizes the option’s value.

unregister_setting( $option_group, $option_name , $sanitize_callback )

$sanitize_callback: (opt.) fills the section with the desired content. Should echo it’s output.

Add field/section

add_settings_field( $id, $title, $callback, $page, $section, $args )

$id: ‘id attribute of tags’
$title: title of the field
$callback : function that fills the field with the desired inputs as part of the larger form. passed a single argument, the $args array. Given $id and $name should match with the input’s. The func should echo it’s output.
$page: the menu page on which to display this field. Should match $mmenu_slug from add_theme_page or from do_settings_sections.
$section: The section of the settings page in which to show the box.
$args: Additional args are passed to the $callback.

add_settings_section( $id, $title, $callback, $page )

Options Form Rendering

setting_fields( $option_group )

$option_group: A setting group name. This should match the name used in register_settings().

do_settings_sections( $page )

$page: The slug name of the page whose settings sections you want to output. Should match the page name used in add_settings_section()

do_settings_fields( $page, $section )

$page: Slug title of the admin page.

Errors

add_settings_error( $setting, $code, $message, $type )

$setting: slug title of the setting to which the erroe applies.
$message: the formatted text to display to the user(shown inside >div< and >p<).
$type: will add an html class to the outmost div.(default .error)

get_settings_errors( $settings, $sanitize )

$settings: slug title of the specific setting.
$sanitize: whether to re-sanitize before returning errors.

settings_errors( $setting, $sanitize, $hide_on_update )

$setting: optional slug of the specific setting.
$sanitize: whether re-sanitize.
$hide_or_update: if set true, errors will not be shown if the page has already been submitted.

Referances
WordPress Codex