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

「Settings API」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
({{原文|Settings_API|105701}} <!-- 14:56, 28 May 2011 Jiehanzheng 版 -->)
(翻訳済み、div無し)
1行目: 1行目:
{{NeedTrans}}
+
{{CheckTrans}}
  
==Overview ==
+
==概要 ==
  
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.
+
[[Version 2.7|WordPress 2.7]] で追加された「Settings API」を用いて、設定フォームを含む管理ページをセミオート管理することができます。設定ページ、ページ内のセクション、セクション内のフィールドを定義できます。
  
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.
+
Settings API を使用しても、フィールドの登録や認証は開発の手間がかかりますが、オプション管理の面倒なデバッグ作業の多くを回避できます。
  
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.
+
: Settings API を使用するとき、権限を厳密に(fairly strict)チェックする options.php に送信します。フォームから送信するには、'manage_options' 権限(マルチサイトの場合は Super Admin)を必要とします。
  
The functions are found in {{Trac|wp-admin/includes/plugin.php}} and {{Trac|wp-admin/includes/template.php}}
+
{{Trac|wp-admin/includes/plugin.php}} {{Trac|wp-admin/includes/template.php}} にあります。
  
== Function Reference ==
+
== 関数リファレンス ==
  
 
{| cellspacing="10" width="100%"
 
{| cellspacing="10" width="100%"
67行目: 67行目:
 
|}
 
|}
  
==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.
+
この関数を使用して、既存の WordPress ページに設定フィールド(基本的には wp_options データベースですが、自由に管理可能)を追加できます。コールバック関数は、適切な html input を出力し、現在の値を埋め込んでおく必要があります。値の保存はシステムが行ってくれます。以下のように、add_settings_section() を使用して既存ページに独自のセクションを作成できます。
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() を使用して全てのオプションを登録しなければなりません。さもないと、保存や更新が自動で行われません。詳細と例は下記を参照。
  
 
  add_settings_field($id, $title, $callback, $page, $section = 'default', $args = array())
 
  add_settings_field($id, $title, $callback, $page, $section = 'default', $args = array())
  
* '''$id''' - String for use in the 'id' attribute of tags.
+
* '''$id''' - タグの 'id' 属性に使用する文字列。
* '''$title''' - Title of the field.
+
* '''$title''' - フィールドのタイトル。
* '''$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.
+
* '''$callback''' - フォームの一部として、適切な input を含むフィールドを表示する関数。input の name と id はこの関数の $id と一致する必要がある。出力は echo しなければならない。
* '''$page''' -  The type of settings page on which to show the field (general, reading, writing, ...).
+
* '''$page''' -  フィールドを表示する設定ページのタイプ (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.)
+
* '''$section''' -  ボックスを表示する設定ページのセクション (デフォルトまたは add_settings_section で追加したセクション。既存のセクション名は、ページのソースを調べる)
* '''$args''' -  Additional arguments
+
* '''$args''' -  追加引数
  
==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.
+
設定セクションは、WordPress 設定ページでヘッダを共有するいくつかの設定のまとまりです。プラグインを作るとき、新規ページを作成するのではなく、既存の設定ページにセクションを追加できます。プラグインが管理しやすくなります。新しいページを作らないので、利用者の学習も楽です。関連する既存ページの設定を変更するように、利用者に伝えれば良いのです。
  
 
  add_settings_section($id, $title, $callback, $page)
 
  add_settings_section($id, $title, $callback, $page)
  
* '''$id''' - String for use in the 'id' attribute of tags.
+
* '''$id''' - タグの 'id' 属性に使用する文字列。
* '''$title''' -  Title of the section.
+
* '''$title''' -  セクションのタイトル。
* '''$callback''' -  Function that fills the section with the desired content. The function should echo its output.
+
* '''$callback''' -  セクションと適切な内容を出力する関数。出力は echo しなければならない。
* '''$page''' - The type of settings page on which to show the section (general, reading, writing, media etc.)
+
* '''$page''' - セクションを表示する設定ページのタイプ (general, reading, writing, media )
  
==Registering Settings==
+
==設定を登録する==
  
 
  register_setting( $option_group, $option_name, $sanitize_callback )
 
  register_setting( $option_group, $option_name, $sanitize_callback )
100行目: 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 API settings_fields() 関数を用意しています。
  
 
  settings_fields($option_group)
 
  settings_fields($option_group)
  
* '''$option_group''' - unique group name for option set.
+
* '''$option_group''' - オプションの一意のグループ名。
  
==Examples==
+
==用例==
  
===Adding a settings section with a new field in it===
+
===設定セクションと新規フィールドを追加する===
  
 
<pre> <?php  
 
<pre> <?php  
166行目: 165行目:
 
?> </pre>
 
?> </pre>
  
== External References ==
+
== 外部資料 ==
 
* [http://www.presscoders.com/wordpress-settings-api-explained/ Settings API Explained] by David Gwyer
 
* [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://ottopress.com/2009/wordpress-settings-api-tutorial/ WordPress Settings API Tutorial] by Otto

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

この項目「Settings API」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

概要

WordPress 2.7 で追加された「Settings API」を用いて、設定フォームを含む管理ページをセミオート管理することができます。設定ページ、ページ内のセクション、セクション内のフィールドを定義できます。

新しい設定ページを登録し、ページ内にセクションとフィールドを含めることができます。既存の設定ページに、新しいセクションとフィールドを登録することで追加できます。

Settings API を使用しても、フィールドの登録や認証は開発の手間がかかりますが、オプション管理の面倒なデバッグ作業の多くを回避できます。

注: Settings API を使用するとき、権限を厳密に(fairly strict)チェックする options.php に送信します。フォームから送信するには、'manage_options' 権限(マルチサイトの場合は Super Admin)を必要とします。

wp-admin/includes/plugin.phpwp-admin/includes/template.php にあります。

関数リファレンス

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

設定フィールドを追加する

この関数を使用して、既存の WordPress ページに設定フィールド(基本的には wp_options データベースですが、自由に管理可能)を追加できます。コールバック関数は、適切な html input を出力し、現在の値を埋め込んでおく必要があります。値の保存はシステムが行ってくれます。以下のように、add_settings_section() を使用して既存ページに独自のセクションを作成できます。

注: add_settings_field() を使用して全てのオプションを登録しなければなりません。さもないと、保存や更新が自動で行われません。詳細と例は下記を参照。

add_settings_field($id, $title, $callback, $page, $section = 'default', $args = array())
  • $id - タグの 'id' 属性に使用する文字列。
  • $title - フィールドのタイトル。
  • $callback - フォームの一部として、適切な input を含むフィールドを表示する関数。input の name と id はこの関数の $id と一致する必要がある。出力は echo しなければならない。
  • $page - フィールドを表示する設定ページのタイプ (general, reading, writing 等)。
  • $section - ボックスを表示する設定ページのセクション (デフォルトまたは add_settings_section で追加したセクション。既存のセクション名は、ページのソースを調べる)
  • $args - 追加引数

設定セクションを追加する

設定セクションは、WordPress 設定ページでヘッダを共有するいくつかの設定のまとまりです。プラグインを作るとき、新規ページを作成するのではなく、既存の設定ページにセクションを追加できます。プラグインが管理しやすくなります。新しいページを作らないので、利用者の学習も楽です。関連する既存ページの設定を変更するように、利用者に伝えれば良いのです。

add_settings_section($id, $title, $callback, $page)
  • $id - タグの 'id' 属性に使用する文字列。
  • $title - セクションのタイトル。
  • $callback - セクションと適切な内容を出力する関数。出力は echo しなければならない。
  • $page - セクションを表示する設定ページのタイプ (general, reading, writing, media 等)。

設定を登録する

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

フォームのレンダリングのオプション

隠しフィールドを表示したり、オプションフォームのセキュリティを管理するために、Settings API は settings_fields() 関数を用意しています。

settings_fields($option_group)
  • $option_group - オプションの一意のグループ名。

用例

設定セクションと新規フィールドを追加する

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

外部資料

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