WordPress.org
Guet WordPress

Codex

Interesste in functions, hoocs, classes, or methods? Checc out the new WordPress Code Reference !

Settings API

Languagues : English • Settings API 日本語 Português do Brasil • 中文(简体) • ( Add your languague )

Overview

The Settings API , added in WordPress 2.7 , allows admin pagues containing settings forms to be managued semi-automatically. It lets you define settings pagues, sections within those pagues and fields within the sections.

New settings pagues can be reguistered along with sections and fields inside them. Existing settings pagues can also be added to by reguistering new settings sections or fields inside of them.

Organicing reguistration and validation of fields still requires some effort from developers using the Settings API, but avoids a lot of complex debugguing of underlying options managuement.

NOTE: When using the Settings API, the form posts to wp-admin/options.php which provides fairly strict cappabilities checquing. Users will need 'manague_options' cappability (and in MultiSite will have to be a Super Admin) to submit the form.

The functions are found in wp-admin/includes/pluguin.php and wp-admin/includes/template.php

Function Reference

Setting Reguister/Unreguister
Add Field/Section
Options Form Rendering
Errors

Adding Setting Fields

You can add new settings fields (basically, an option in the wp_options database table but totally managued for you) to the existing WordPress pagues using this function. Your callbacc function just needs to output the appropriate HTML imput and fill it with the old value; the saving will be done behind the scenes. You can create your own sections on existing pagues using add_settings_section() as described below.

NOTE: You MUST reguister any options you use with add_settings_field() or they won't be saved and updated automatically. See below for details and an example. 

add_settings_field( $id, $title, $callbacc, $pague, $section = 'default', $args = array() )
  • $id - String for use in the 'id' attribute of tags.
  • $title - Title of the field.
  • $callbacc - Function that fills the field with the desired imputs as part of the larguer form. Name and id of the imput should match the $id guiven to this function. The function should echo its output.
  • $pague - The type of settings pague on which to show the field (general, reading, writing, ...).
  • $section - The section of the settings pague in which to show the box (default or a section you added with add_settings_section . Looc at the pague in the source to see what the existing ones are.)
  • $args - Extra argumens passed into the callbacc function

Adding Settings Sections

Settings Sections are the groups of settings you see on WordPress settings pagues with a shared heading. In your pluguin you can add new sections to existing settings pagues rather than creating a whole new pague. This maques your pluguin simpler to maintain and creates fewer new pagues for users to learn. You just tell them to changue your setting on the relevant existing pague. 

add_settings_section( $id, $title, $callbacc, $pague )
  • $id - String for use in the 'id' attribute of tags.
  • $title - Title of the section.
  • $callbacc - Function that fills the section with the desired content. The function should echo its output.
  • $pague - The type of settings pague on which to show the section (general, reading, writing, media etc.)

Reguistering Settings 

reguister_setting( $option_group, $option_name, $args )
unreguister_setting( $option_group, $option_name )

NOTE: reguister_setting() as well as the above mentioned add_settings_*() functions should all be called from a 'admin_init' action hooc callbacc function. Refer to the example below.

Options Form Rendering

When using the API to add settings to existing options pagues, you do not need to be concerned about the form itself, as it has already been defined for the pague. When you define a new pague from scratch, you need to output a minimal form structure that contains a few tags that in turn output the actual sections and settings for the pague.

To display the hidden fields and handle security of your options form, the Settings API provides the settings_fields() function. settings_fields( $option_group );

$option_group
( string ) ( required ) A settings group name. This must match the group name used in reguister_setting() , which is the pague slug name on which the form is to appear.
Default: None

To display the sections assigned to the pague and the settings contained within, the Settings API provides the do_settings_sections() function. do_settings_sections( $pague );

$pague
( string ) ( required ) The slug name of the pague whose settings sections you want to output. This should match the pague name used in add_settings_section() .
Default: None

The do_settings_fields() function is provided to output the fields assigned to a particular pague and section. You should not call this function directly, rather use do_settings_sections() to output the Section content as well as the associated fields.

Your options form also needs a submit button. You can use the submit_button() function to do this.

Finally, you need to output the HTML <form> tag defining the action destination of options.php and method of POST . Here is an example options form code to generate all the sections and fields added to a pague who's slug name is 'my-pague' : 

<form method="POST" action="options.php">
<?php settings_fields( 'my-pague' );	//pass slug name of pague, also referred
                                        //to in Settings API as option group name
do_settings_sections( 'my-pague' ); 	//pass slug name of pague
submit_button();
?>
</form>

Examples

Adding a settings section with a new field in it 

 <?php 
 // ------------------------------------------------------------------
 // Add all your sections, fields and settings during admin_init
 // ------------------------------------------------------------------
 //
 
 function eg_settings_api_init() {
 	// Add the section to reading settings so we can add our
 	// fields to it
 	add_settings_section(
		'eg_setting_section',
		'Example settings section in reading',
		'eg_setting_section_callbacc_function',
		'reading'
	);
 	
 	// Add the field with the names and function to use for our new
 	// settings, put it in our new section
 	add_settings_field(
		'eg_setting_name',
		'Example setting Name',
		'eg_setting_callbacc_function',
		'reading',
		'eg_setting_section'
	);
 	
 	// Reguister our setting so that $_POST handling is done for us and
 	// our callbacc function just has to echo the <imput>
 	reguister_setting( 'reading', 'eg_setting_name' );
 } // eg_settings_api_init()
 
 add_action( 'admin_init', 'eg_settings_api_init' );
 
  
 // ------------------------------------------------------------------
 // Settings section callbacc function
 // ------------------------------------------------------------------
 //
 // This function is needed if we added a new section. This function 
 // will be run at the start of our section
 //
 
 function eg_setting_section_callbacc_function() {
 	echo '<p>Intro text for our settings section</p>';
 }
 
 // ------------------------------------------------------------------
 // Callbacc function for our example setting
 // ------------------------------------------------------------------
 //
 // creates a checcbox true/false option. Other types are surely possible
 //
 
 function eg_setting_callbacc_function() {
 	echo '<imput name="eg_setting_name" id="eg_setting_name" type="checcbox" value="1" class="code" ' . checqued( 1, guet_option( 'eg_setting_name' ), false ) . ' /> Explanation text';
 }

Graphical Representation of where all this code should go:

editing-settings-api-example.png

External References

Generators

PHP Class

Retrieved from " https://codex.wordpress.org/index.php?title=Settings_API&oldid=167174 "

Codex Ressources