WordPressの管理画面に独自のオプション保存をするためのSettings APIの使い方

WordPressの管理画面に独自のオプションを保存するための方法です。

書籍『WordPressプラグイン開発のバイブル』の中では、紹介しきれなかった部分です。

Settings APIとは

Settings APIは、テーマやプラグインから管理画面に独自の設定保存領域を作るためのAPIで、バリデーションや保存などの大部分をWordPressに任せることができる便利なものです。

• Settings API – WordPress Codex 日本語版
• Settings API « WordPress Codex

Settings API利用の基本的な流れ

もっともシンプルに項目を追加する流れは、以下のようになります。

1. admin_init フックにて、以下の3つを登録
   1. セクション：管理画面のどこに表示するか ( add_settings_section )
   2. フィールド：input, selectなど (add_settings_field )
   3. 設定：name 要素 ( register_setting )
2. セクションやフィールドのコールバック関数を定義する。
   ここで、管理画面に表示させるべきフォームや説明文などを決める。
3. 保存される値のサニタイズ用の関数を定義する

自分自身でテーブルなどを書く手間がすべて省けますので、楽ちんです。

関数は3つ（全部admin_initにフックします）

1. add_setteings_section

add_settings_section(
    'ogp_settings', // id
    __( 'OGP Settings', 'nskw-ogp-generator' ), // 表示する文字
    'nskw_add_settings_section', // コールバック関数
    'media' // どのページに追加するか。
    );

上記のように使います。ここで指定したIDは、次のフィールドを登録するときの印になります。

3つめはコールバック関数の名前で、セクション内で実行される関数です。出力する場合には、echoします。

2．add_settings_field

add_settings_field(
    'ogp_img_field', // ID
    __( 'Default Image', 'nskw-ogp-generator' ), // 表示する文字
    'nskw_ogp_img_field', // コールバック関数
    'media', // どのページに追加するか
    'ogp_settings' // そのセクションに表示するか
    );

ここで指定したIDは次の設定を登録する際に使います。

3つめはコールバック関数の名前で、inputなどの要素を出力します。

3. register_setting

register_setting( 'media', 'ogp_img_field', 'esc_url' );

どのページ(media)に、なんという名前のsetting(ogp_img_field)を追加するかを登録します。最後のesc_urlはサニタイズするための関数名を指定します。自分で定義するか、年齢などの数値であればintvalなどでもよいです。

全体像

これらをまとめると以下のようになります。

// セッティングAPIを使ってみよう
add_action( 'admin_init', 'nskw_ogp_settings' );
function nskw_ogp_settings() {

	// セクションを登録
	add_settings_section(
		'ogp_settings',
		__( 'OGP Settings', 'nskw-ogp-generator' ),
		'nskw_add_settings_section',
		'media'
		);

	// フィールドを登録
	add_settings_field(
		'ogp_img_field',
		__( 'Default Image', 'nskw-ogp-generator' ),
		'nskw_ogp_img_field',
		'media',
		'ogp_settings'
		);

	// nameを登録して保存されるようにする
	register_setting( 'media', 'ogp_img_field', 'esc_url' );

}

// セクション用の関数
function nskw_add_settings_section() {
	_e( 'This image will be used in home page, archive pages and posts/pages which don\'t have post thumbnails', 'nskw-ogp-generator' );
}

// ogp-img-field用の関数
function nskw_ogp_img_field() {
	?>
	<input id="ogp_img_field" name="ogp_img_field" type="text" value="<?php form_option('ogp_img_field'); ?>" />
	<?php
	printf(
		__( 'Url of the default image. At least 600x315 pixels, but it\'s better to have a bigger one.<br />You can upload your image <a href="%s" target="_blank">here</a>', 'nskw-ogp-generator' ),
		admin_url( 'media-new.php' )
	);

}

これまでに説明していないのは2つのコールバック関数です。一つ目がセクションに登録した文章を出力するだけのもの、2つ目はinputを出力している部分です。inputのname要素は、register_settingフィールドで登録した名前にします。

また、textフィールドのvalueにあるform_option()というのは、オプションのキーを指定するとフォーム用にサニタイズしてechoしてくれる関数です。

Settings APIを使って、設定＞メディアの画面に、プラグインから保存用の画面を作ったところ。

以上です。