当サイト、Codex 日本語版は今後積極的な更新は行わない予定です。後継となる新ユーザーマニュアルは、https://ja.wordpress.org/support/ にあります。
万が一、当サイトで重大な問題を発見した際などは、フォーラムWordSlack #docs チャンネルでお知らせください。</p>

「Settings API」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(3.0 のコアパッケージからリンクされているので en:Settings_API rev. 84450 から新規作成。要翻訳。)
 
({{原文|Settings_API|105701}} <!-- 14:56, 28 May 2011 Jiehanzheng 版 -->)
1行目: 1行目:
 
{{NeedTrans}}
 
{{NeedTrans}}
 +
 
==Overview ==
 
==Overview ==
  
[[Version 2.7|WordPress 2.7]] adds a Settings API for inserting settings and setting sections into the existing WordPress settings panels. This means directly in those pages and not as a new page.  
+
The '''Settings API''', added in [[Version 2.7|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 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 {{Trac|wp-admin/includes/plugin.php}} and {{Trac|wp-admin/includes/template.php}}
 
The functions are found in {{Trac|wp-admin/includes/plugin.php}} and {{Trac|wp-admin/includes/template.php}}
8行目: 15行目:
 
== Function Reference ==
 
== Function Reference ==
  
{| cellspacing="10" border="0""
+
{| cellspacing="10" width="100%"
 
|- valign="top"
 
|- valign="top"
 
| width="50%" |
 
| width="50%" |
  
{| class="widefat" style="border:1px solid #eee"
+
{| class="widefat"
 
|- style="background:#464646; color:#d7d7d7;"
 
|- style="background:#464646; color:#d7d7d7;"
 
! '''Setting Register/Unregister'''
 
! '''Setting Register/Unregister'''
23行目: 30行目:
 
| width="50%" |
 
| width="50%" |
  
{| class="widefat" style="border:1px solid #eee"
+
{| class="widefat"
 
|- style="background:#464646; color:#d7d7d7;"
 
|- style="background:#464646; color:#d7d7d7;"
 
! '''Add Field/Section'''
 
! '''Add Field/Section'''
30行目: 37行目:
 
* <tt>[[関数リファレンス/add settings field|add_settings_field()]]/[[:en:Function Reference/add settings field|en]]</tt>
 
* <tt>[[関数リファレンス/add settings field|add_settings_field()]]/[[:en:Function Reference/add settings field|en]]</tt>
 
* <tt>[[関数リファレンス/add settings section|add_settings_section()]]/[[:en:Function Reference/add settings section|en]]</tt>
 
* <tt>[[関数リファレンス/add settings section|add_settings_section()]]/[[:en:Function Reference/add settings section|en]]</tt>
 +
|}
 +
 +
|}
 +
 +
{| cellspacing="10" width="100%"
 +
|- valign="top"
 +
|
 +
 +
{| class="widefat"
 +
|- style="background:#464646; color:#d7d7d7;"
 +
! '''Options Form Rendering'''
 +
|-
 +
|
 +
* <tt>[[関数リファレンス/settings fields | settings_fields()]]/[[:en:Function_Reference/settings fields |en]]</tt>
 +
* <tt>[[関数リファレンス/do settings sections | do_settings_sections()]]/[[:en:Function Reference/do settings sections |en]]</tt>
 +
* <tt>[[関数リファレンス/do settings fields | do_settings_fields()]]/[[:en:Function Reference/do settings fields |en]]</tt>
 +
|}
 +
 +
| width="50%" |
 +
 +
{| class="widefat"
 +
|- style="background:#464646; color:#d7d7d7;"
 +
! '''Errors'''
 +
|-
 +
|
 +
* <tt>[[関数リファレンス/add settings error | add_settings_error()]]/[[:en:Function Reference/add settings error |en]]</tt>
 
|}
 
|}
  
66行目: 99行目:
  
 
  unregister_setting( $option_group, $option_name, $sanitize_callback )
 
  unregister_setting( $option_group, $option_name, $sanitize_callback )
 +
 +
==Options Form Rendering==
 +
 +
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''' - unique group name for option set.
  
 
==Examples==
 
==Examples==
78行目: 119行目:
 
   
 
   
 
  function eg_settings_api_init() {
 
  function eg_settings_api_init() {
  // Add the section to reading settings so we can add our fields to it
+
  // Add the section to reading settings so we can add our
  add_settings_section('eg_setting_section', 'Example settings section in reading', 'eg_setting_section_callback_function', 'reading');
+
// 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 the field with the names and function to use for our new
  add_settings_field('eg_setting_name', 'Example setting Name', 'eg_setting_callback_function', 'reading', 'eg_setting_section');
+
// 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 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');
 
  register_setting('reading','eg_setting_name');
 
  }// eg_settings_api_init()
 
  }// eg_settings_api_init()
111行目: 162行目:
 
   
 
   
 
  function eg_setting_callback_function() {
 
  function eg_setting_callback_function() {
  $checked = "";
+
  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';
+
  }
// Mark our checkbox as checked if the setting is already true
+
if (get_option('eg_setting_name'))
+
$checked = " checked='checked' ";
+
+
echo "<input {$checked} name='eg_setting_name' id='gv_thumbnails_insert_into_excerpt' type='checkbox'
+
value='eg_setting_name' class='code' /> Explanation text";
+
  } // eg_setting_callback_function()
+
 
?> </pre>
 
?> </pre>
  
 
== External References ==
 
== External References ==
* [http://ottodestruct.com/blog/2009/wordpress-settings-api-tutorial/ WordPress Settings API Tutorial] by Otto
+
* [http://www.presscoders.com/wordpress-settings-api-explained/ Settings API Explained] by David Gwyer
 +
* [http://ottopress.com/2009/wordpress-settings-api-tutorial/ WordPress Settings API Tutorial] by Otto
 
* [http://planetozh.com/blog/2009/05/handling-plugins-options-in-wordpress-28-with-register_setting/ Handling Plugin Options with register_setting()] by Ozh
 
* [http://planetozh.com/blog/2009/05/handling-plugins-options-in-wordpress-28-with-register_setting/ Handling Plugin Options with register_setting()] by Ozh
 +
* [http://blog.gneu.org/2010/09/intro-to-the-wordpress-settings-api/ Intro to the WordPress Settings API] by BobGneu
 +
* [http://www.chipbennett.net/2011/02/17/incorporating-the-settings-api-in-wordpress-themes/ Incorporating the Settings API in WordPress Themes] by Chip Bennett
  
{{原文|Settings_API|84450}} <!-- 2010-03-19T16:15:08 Jorbin 版 -->
+
{{原文|Settings_API|105701}} <!-- 14:56, 28 May 2011 Jiehanzheng 版 -->
  
 
{{DEFAULTSORT:}}
 
{{DEFAULTSORT:}}
 
[[Category:上級トピック]]
 
[[Category:上級トピック]]
 
[[Category:WordPress の開発]]
 
[[Category:WordPress の開発]]
[[Category:API]]
 
[[Category:UI Link]]
 
 
[[en:Settings_API]]
 

2011年6月3日 (金) 07:09時点における版

このページ「Settings API」は未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

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 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 wp-admin/includes/plugin.php and wp-admin/includes/template.php

Function Reference

Setting Register/Unregister
Add Field/Section
Options Form Rendering
Errors

Adding Setting Fields

You can add new settings fields (basically, an option for 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 less 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 )

Options Form Rendering

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 - unique group name for option set.

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_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';
 }
?> 

External References

最新英語版: WordPress Codex » Settings_API最新版との差分