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

Settings API

提供: WordPress Codex 日本語版
2011年6月3日 (金) 07:45時点におけるMizuno (トーク | 投稿記録)による版 (翻訳済み、div無し)

移動先: 案内検索

この項目「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最新版との差分