Settings API

来自WordPress中文文档
跳转至: 导航搜索

wordpress.org.cn

Overview

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

New settings pages can be registered along with sections and fields inside them. Existing settings pages can also be added to by registering new settings sections or fields inside of them.

Organizing registration and validation of fields still requires some effort from developers using the Settings API, but avoids a lot of complex debugging of underlying options management.

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

The functions are found in onlyincludecodewp-admin/includes/plugin.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre检查到模板循环:模板:Trac/pre

Link to trunk: pre检查到模板循环:模板:Trac/pre

/div

wordpress.org.cn and onlyincludecodewp-admin/includes/template.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre检查到模板循环:模板:Trac/pre

Link to trunk: pre检查到模板循环:模板:Trac/pre

/div

wordpress.org.cn

Function Reference

Setting Register/Unregister
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 managed for you) to the existing WordPress pages using this function. Your callback function just needs to output the appropriate HTML input and fill it with the old value, the saving will be done behind the scenes. You can create your own sections on existing pages using add_settings_section() as described below.

NOTE: You MUST register 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, $callback, $page, $section = 'default', $args = array() )
  • $id - String for use in the '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. Name and id of the input should match the $id given to this function. The function should echo its output.
  • $page - The type of settings page on which to show the field (general, reading, writing, ...).
  • $section - The section of the settings page in which to show the box (default or a section you added with add_settings_section, look at the page in the source to see what the existing ones are.)
  • $args - Additional arguments

Adding Settings Sections

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

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

Registering Settings

register_setting( $option_group, $option_name, $sanitize_callback )
unregister_setting( $option_group, $option_name, $sanitize_callback )

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

Options Form Rendering

When using the API to add settings to existing options pages, you do not need to be concerned about the form itself, as it has already been defined for the page. When you define a new page 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 page.

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

tt$option_group/tt
(string) (required) A settings group name. This must match the group name used in register_setting(), which is the page slug name on which the form is to appear.
Default: Nonenoinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

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

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

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

The do_settings_fields() function is provided to output the fields assigned to a particular page 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 page who's slug name is 'my-page':

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

Examples

For a complete example using a PHP class,see the WordPress code for the Custom Background screen: onlyincludecodewp-admin/custom-background.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre检查到模板循环:模板:Trac/pre

Link to trunk: pre检查到模板循环:模板:Trac/pre

/div

wordpress.org.cn

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_callback_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_callback_function',
		'reading',
		'eg_setting_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');
 
  
 // ------------------------------------------------------------------
 // Settings section callback 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_callback_function() {
 	echo '<p>Intro text for our settings section</p>';
 }
 
 // ------------------------------------------------------------------
 // Callback function for our example setting
 // ------------------------------------------------------------------
 //
 // creates a checkbox true/false option. Other types are surely possible
 //
 
 function eg_setting_callback_function() {
 	echo '<input name="eg_setting_name" id="gv_thumbnails_insert_into_excerpt" type="checkbox" value="1" class="code" ' . checked( 1, get_option('eg_setting_name'), false ) . ' /> Explanation text';
 }
?> 

Graphical Representation of where all those code should go:

External References