• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

Settings API

提供: WordPress Codex 日本語版
移動先: 案内検索

WordPress 2.7 で追加された Settings API を用いて、半自動的に管理される設定フォームを管理画面に含めることができます。設定ページ、ページ内のセクション、セクション内のフィールドを定義できます。

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

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

参考: Settings API を使用すると、データはフォームから wp-admin/options.php へ送られ、かなり厳密なチェック(権限など)を受けます。フォームから送信するには、ユーザーは 'manage_options' 権限(マルチサイトの場合は Super Admin)を必要とします。

Settings API の関数は wp-admin/includes/plugin.phpwp-admin/includes/template.php にあります。

関数リファレンス

設定の登録と登録解除
フィールドやセクションの追加
オプションフォームの形成
エラー

設定フィールドの追加

この関数を使用して、既存の 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 要素の nameid はこの関数の $id と一致する必要がある。関数は出力を echo する必要がある。
  • $page - フィールドを表示する設定ページのタイプ(general, reading, writing 等)。
  • $section - ボックスを表示する設定ページのセクション(default または 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 )

注意: register_setting() や上で述べた add_settings_*() 関数は、'admin_init' アクションフックのコールバック関数から呼び出される必要があります。以下のを参照してください。

オプションフォームの形成

既存のオプションページにこの API を用いて設定を追加する場合、フォームそのものについては、既に定義されているので考慮する必要はありません。まったく新しくページを作る場合は、そのページでのセクションや設定項目を出力するわずかのタグを含む最低限のフォーム構造が必要です。

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

settings_fields( $option_group );
$option_group
文字列) (必須) 設定グループ名。register_setting() /en に用いたものと一致していなければならない。フォームが表示されるページのスラッグになる。
初期値: なし

あるページのセクション、つまりそこに含まれる設定項目を出力するために、Settings API は do_settings_sections() /en 関数を用意しています。

do_settings_sections( $page );
$page
文字列) (必須) セクションを表示させたいページのスラッグ。add_settings_section() /en に用いたページ名と一致する必要がある。
初期値: なし

do_settings_fields() /en 関数は、特定のページやセクションのフィールドを出力しますが、この関数を直接呼び出すべきではありません。do_settings_sections() を使ってフィールドを集約してセクションを出力します。

オプションのフォームには submit ボタンが必要です。submit_button() /en 関数を使ってください。

最後に、POST メソッドで options.php を送り先とする HTML の <form> タグを出力する必要があります。スラッグが 'my-page' のページにセクションとフィールドを生成するオプションフォームのコードの例を示します。

<form method="POST" action="options.php">
<?php settings_fields( 'my-page' ); // ページのスラッグ。これはまた
                                    // オプションのグループ名としても Settings API に参照される
do_settings_sections( 'my-page' );  // ページのスラッグ
submit_button();
?>
</form>

用例

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

 <?php 
 // ------------------------------------------------------------------
 // admin_init の中で設定のセクションとフィールドを追加
 // ------------------------------------------------------------------
 //
 
 function eg_settings_api_init() {
 	// reading 設定ページへフィールドを追加する準備として
 	// セクションを追加
 	add_settings_section(
		'eg_setting_section',
		'Example settings section in reading',
		'eg_setting_section_callback_function',
		'reading'
	);
 	
 	// その新しいセクションの中に
 	// 新しい設定の名前と関数を指定しながらフィールドを追加
 	add_settings_field(
		'eg_setting_name',
		'Example setting Name',
		'eg_setting_callback_function',
		'reading',
		'eg_setting_section'
	);
 	
 	// 新しい設定が $_POST で扱われ、コールバック関数が <input> を
 	// echo できるように、新しい設定を登録
 	register_setting( 'reading', 'eg_setting_name' );
 } // eg_settings_api_init()
 
 add_action( 'admin_init', 'eg_settings_api_init' );
 
  
 // ------------------------------------------------------------------
 // セクションのコールバック関数
 // ------------------------------------------------------------------
 //
 // 新規セクションを追加するために必要となる関数。
 // セクションのはじめに実行される。
 //
 
 function eg_setting_section_callback_function() {
 	echo '<p>設定セクションを説明する文章</p>';
 }
 
 // ------------------------------------------------------------------
 // 設定の例のためのコールバック関数
 // ------------------------------------------------------------------
 //
 // チェックボックスを生成。もちろん他のタイプも可。
 //
 
 function eg_setting_callback_function() {
 	echo '<input name="eg_setting_name" id="eg_setting_name" type="checkbox" value="1" class="code" ' . checked( 1, get_option( 'eg_setting_name' ), false ) . ' /> 説明文';
 }
?> 


日本語リソース

外部リソース

生成ツール

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