Settings API

目次 1 概要 2 関数リファレンス 3 設定フィールドを追加する 4 設定セクションを追加する 5 設定を登録する 6 フォームのレンダリングのオプション 7 用例 7.1 設定セクションと新規フィールドを追加する 8 外部資料

概要

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

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

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

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

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

関数リファレンス

Setting Register/Unregister register_setting()/en unregister_setting()/en

Add Field/Section add_settings_field()/en add_settings_section()/en

Options Form Rendering settings_fields()/en do_settings_sections()/en do_settings_fields()/en

Errors add_settings_error()/en

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

この関数を使用して、既存の 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';
 }
?> 

外部資料

• Settings API Explained by David Gwyer
• WordPress Settings API Tutorial by Otto
• Handling Plugin Options with register_setting() by Ozh
• Intro to the WordPress Settings API by BobGneu
• Incorporating the Settings API in WordPress Themes by Chip Bennett

最新英語版： WordPress Codex » Settings_API （最新版との差分）