WordPressプラグインに設定ページをつける

プラグインの動作を動的に変更しようとする場合、WordPressの管理画面に設定ページを設けます。このプラグインの設定ページのつけ方をサンプルコーディング付きで教えます。





設定ページと設定値

WordPressでブログを運営していると必ずプラグインをインストールして使っている事と思います。プラグインを有効にすると管理画面右側にある設定メニューに、プラグインの”設定ページ”が現れます。

この設定ページでプラグインの動作を制御する設定値を設定することが出来ますが、これらは、データベースに保存され、get_option関数でいつでも利用することができます。

この記事では例として、プラグインの名前をSample_plugin、設定ページのメニュータイトルをSample_Setting、設定値をオプションA、オプションB、コメント、モード選択値の4つの設定をもつ設定ページをつくるようにします。

表示例)

画像を拡大表示する


これから実際に作っていきますが、使われている環境は

WordPress 4.9.8

Windows10 です。

手順

設定ページを作成する手順は以下の順番におこないます。

  • 設定メニューにSample Settingページを追加
  • Setting APIにもとづいて、設定値の読み出し、保存する仕組みを作成する
  • 設定値を入出力するためのHTML出力関数を構築
  • 最終の設定ページのHTMLに仕上げる

Sample Settingページを追加

管理画面の設定ページを追加するためには、add_actionで”admin_menu”をフックしておこないます。フックしたadd_my_setting()内では、add_options_pageを使って、実際の設定メニューを追加していきます。

<?php
/*
Plugin Name: Sample Plugins
Plugin URI: http://example.com/sampleplugins
Description: 設定ページをつくるサンプルプラグイン
Author: somebody
Version: 1.0
Author URI: http://example.com/author
*/

//設定値を保存するグローバル変数
$gbSetting = null;

//設定ページを追加するためにadmin_menuをフックする
add_action( 'admin_menu','add_my_setting');

//アクションフックで呼ぶ関数
function add_my_setting(){
	add_options_page(
		'Sampleプラグインの設定',		//ページタイトル
		'Sample Setting',			//設定メニューに表示されるメニュータイトル
		'administrator',			//権限
		'sample_setup_page',		//設定ページのURL。options-general.php?page=sample_setup_page
		'my_setting_htmlpage'		//設定ページのHTMLをはき出す関数の定義
	);
}

//設定ページのHTML
function my_setting_htmlpage() {
	echo '<div clas="wrap">';
	echo '<p>Sample Pluginの設定ページ</p>';
	echo '</div>';
} 
?>

上記のコーディングをsample.phpとして保存し、WordPressのPluginsフォルダー下に、Sample-Pluginのフォルダを作ってコピーしてください。ちゃんと、プラグインとして認識して設定メニューに”Sample Setting”という新規の設定ページができます。

参考:sampleプラグインの配置位置

画像を拡大表示する
sampleプラグインの配置位置

sampleプラグインの配置位置

 

add_options_page

add_options_pageは、「設定メニューにサブメニューページを追加」します。

インターフェース

add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function);

パラメータ

$page_title(必須)

サブメニューページの<title>>に使われる文字列。

$menu_title(必須)

設定に追加されるサブメニューのタイトル。

$capability(必須)

権限者を指定する。以下の指定が可能。

権限者 説明
administrator 管理者
editor 編集者
author 投稿者
contributor 寄稿者
subscriber 購読者

$menu_slug(必須)

サブメニューページのURLを指定。上記のコーデング例を参照!

$function(必須)

メニューボタンをクリックした際に実行されるコールバック関数。実際には出力されるページのHTMLコーディングを出力する。

$functionの指定は単にコールバックされる関数名を指定しますが、もしプラグインがクラスで作成される場合は、クラスのインスタンス(実態)を作成してArrayで指定することに注意!

$function = array( $objclass,’ my_setting_htmlpage’ )

設定値の読み出し/保存のロジック作成

最新WordPressのバージョンでは、これらの専用の仕組みを一連の関数を順番に呼ぶ出すことによってより簡単に実現している。これらの関数群をSetting APIと呼んでいる。

Setting API

SettingAPIは以下の3つの関数群よりなり、設定ページのセクション数や設定値の数により、複数回呼ぶ事になる。

関数 タイミング 用途
1 register_setting admin_init 設定値の読み出し/書き込みをおこなう
2 add_settings_section admin_init 設定ページのセクションを作成する
3 add_settings_field admin_init 設定値を設定ページとセクションへ登録する
4 setting_fields admin_menu 設定ページのために、ノンス、アクション、および option_page フィールドを出力
5 do_settings_sections admin_menu 指定された設定ページのすべての設定セクションを表示

Setting APIの呼び出すタイミングと順番

Setting APIは、admin_initをフックして呼び出される

	add_action( 'admin_init', array( $this, 'sample-setting_init'));

※コールバック関数sample-setting_initもクラス内にある場合を想定しています。

画像を拡大表示する

SettingAPIの呼び出し

register_setting

インターフェース

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

パラメータ

$option_group(必須)

設定のグループ名。setting_fields関数の第1パラメータと一致させる。

$option_name(必須)

オプション名。後のHtmlで設定ページを各場合にinput文やselect文のname属性は、このオプション名を使って配列にする。

$sanitaize_callback (オプション)

本来の目的は、サニタイズ(無害化)のための関数を定義しますが、入力値を検証する場合に遣われる。必要がなければかかない。

戻り値

Void

add_setting_section

インターフェース

add_settings_section( $id, $title, $callback, $page );

パラメータ

$id(必須)

id属性の使用される文字列。任意の英数で記述。

$title(必須)

セクションのタイトル名を指定する。全角文字も可能。

$callback(必須)

必要なコンテンツを入れてセクションを出力する関数。echoで任意の文字を出力。必須項目なので関数のガワだけでも作成する必要があります。

$page(必須)

セクションを表示する設定ページ。add_options_pageの第4引数およびadd_setting_fieldの第4引数と一致させる。

戻り値

(void)

add_setting_field

インターフェース

add_settings_field( $id, $title, $callback, $page, $section, $args );

パラメータ

$id(必須)

id属性に使用する任意の英数の文字列。

$title(必須)

入力項目フィールドのタイトル名。全角も可能。

$callback(必須)

input等設定値を入力するためのHTML出力関数(※次項で詳しく説明)。引数として配列を1つ($arg)を渡す。公式ページの説明によると、”input 要素の nameと idはこの関数の $id と一致しなければならない”となっていますが、name属性は、入力値をクエリーパラメータを返却するために、registar_setting関数の第2引数のoption_nameに準じた名前となることに注意する。

$page(必須)

次項に説明する$sectionとともに、設定ページとこの設定値を関連づける重要な要素。add_options_pageの第4引数と一致させる

$section(必須)

設定ページのセクションと関連づける重要。add_setting_fieldの第1引数の$idと一致させる。

 

$args(オプション)

戻り値

(void):なし

設定値を入出力するためのHTML出力関数を構築

add_setting_fieldで呼んでいるcallback関数は、各設定値を入力させるためのinput文やselect文などを出力するhtml要素をechoする。

ここで重要な役割は2つある。

1つ目の役割は、get_option関数でデータベースから取得した値を入力項目に反映させるHTMLを出力すること。

2つ目の役割は、入力値をどのような形でクエリーパラメータとして戻してやるかです

データベースの設定値を反映する

設定ページで入力させた設定値は、Wordpressのデータベースwp_optionsテーブルに保存する。設定値を1つずづ単独で保存することも可能ですが、設定値をまとめて連想配列として保存することも可能です。今回例として用いた設定値は

$sample_user_setrting = array( 
"option_a" =>1,
"option_b"=>1,
"select_mode"=>3,
"comment"=>"これはコメントです。"
)

といった4つの設定値として、’sample_user_setting’というキー名でデータベースに保存されています。

これを読み出す場合は、

$sample_user_setting = get_option(‘sample_user_setting’);

とすれば、上記のような連想配列を取り出すことができます。

たとえば、option_aを反映するHTML要素を作成するには、

function option_a_callback() {
	$sample_user_setting = get_option('sample_user_setting');

	if( $sample_user_setting ['option_a']=="1" ) {
		$check = "checked=\"checked\"";
	}
	else
	{
		$check = "";
	}
?>
   <input type="hidden" name="sample_user_setting[option_a]" value="0">
   <label for="option_a"><input type="checkbox" id="option_a" name="sample_user_setting[option_a]" size="30" value="1"<?php echo $check; ?>/>option A</input></label>
<?php	
}
?>

というような感じになります。これadd_setting_fieldのコールバック関数とすればいいわけです。

ポイント!
checkボックスの場合は、チェックされないとクエリーパラメータとして戻さないので、上記の例のように、value=0とvalue=1の両方のinput文を併記し、チェックされない場合は、hiddenのvalue=0を戻すようにコーディングするのがポイントです。

クエリーパラメータを配列で戻す

2ばん目の役割の解説です。データベースには4つの連想配列で入出力されます。したがって今回も設定ページの入力値を配列としてクエリーパラメータで戻してやるのが便利です。たぶん、読者は既に知っているとは思いますが、input等のname属性に配列みたいな記述をするとこの事が実現できます。

上記の例でいえば、

<input type=”checkbox” id=”option_a” name=”sample_user_setting[option_a]” size=”30″ value=”1″ />
クエスチョン!
データベースの設定値入力はget_optionで手動でやりましたが、データベースの更新はどこでやるのでしょう?
回答:上記の例のように入力値を配列で戻してあげると、WordPressのSetting APIの方で自動的にやってくれます。regist_setting関数の第2引数の$option_nameに定義した名前をクエリーパラメータ配列とすることが肝となります。

さて、これで全部解説しました。

HTML要素を出力するコールバック変数も含めて、どういう風にこれらのSettingAPIの関数群を利用するかコーディング例を示す。内容が理解出来たら、先のSampleプラグインのコーディングに追加して試してみてください。

※データベースの設定値は、別のタイミングでグローバル変数$gbSettingに読み込まれています。

//admin initのアクションフック
add_action( "admin_init", "sample_setting_init");

//設定値を読込保存を実行するSetting API群
function sample_setting_init() {
	register_setting(
		'sample_option_group',			// option group
		'sample_user_setting'			// option name(DB)
	);		


	add_settings_section(
		'setting_section_id',				// id
		'Sampleプラグイン 設定ページ',		// title
		'print_sction_info',				// callback
		'sample_setup_page'			// page
	);

	add_settings_field(
		'option_a',							// id
		'オプションA',  				// title
		'option_a_callback',			// callback
		'sample_setup_page',			//page
		'setting_section_id'				//Section
	);
	add_settings_field(
		'option_b',				// id
		'オプションB',  				// title
		'option_b_callback',			// callback
		'sample_setup_page',			//page
		'setting_section_id'				//Section
	);
	add_settings_field(
		'select_mode',				// id
		'モード選択:',  				// title
		'option_select_mode_callback',		// callback
		'sample_setup_page',			//page
		'setting_section_id'				//Section
	);
	add_settings_field(
		'comment',				// id
		'コメント:',  				// title
		'comment_option_callback',			// callback
		'sample_setup_page',			//page
		'setting_section_id'				//Section
	);
}

//コールバック関数
function print_sction_info() {
}

function option_a_callback() {
	global $gbSetting;

	if( $gbSetting['option_a']=="1" ) {
		$check = "checked=\"checked\"";
	}
	else
	{
		$check = "";
	}
?>
   <input type="hidden" name="sample_user_setting[option_a]" value="0">
   <label for="option_a"><input type="checkbox" id="option_a" name="sample_user_setting[option_a]" size="30" value="1"<?php echo $check; ?>/>option A</input></label>
<?php	
}

function option_b_callback() {
	global $gbSetting;

	if( $gbSetting['option_b']=="1" ) {
		$check = "checked=\"checked\"";
	}
	else
	{
		$check = "";
	}
?>
   <input type="hidden" name="sample_user_setting[option_b]" value="0">
   <label for="option_b"><input type="checkbox" id="option_b" name="sample_user_setting[option_b]" size="30" value="1"<?php echo $check; ?>/>option B</input></label>
<?php	
}
function option_select_mode_callback() {
	global $gbSetting;

	$mode_val = $gbSetting['select_mode'];
	$select_tbl = array(
		array( 'val'=>1, 'name'=>'動作1'),
		array( 'val'=>2, 'name'=>'動作2'),
		array( 'val'=>3, 'name'=>'動作3'),
	);

	$html = "";
	foreach( $select_tbl as $r ) {
		$v = $r['val'];
		$n = $r['name'];
		if( $v==$mode_val ) {
			$checked="selected";
		}
		else
		{
			$checked = "";
		}
		$html .= "<option value=\"$v\" $checked>$n</option>";
	}
	$html = "<select name=\"sample_user_setting[select_mode]\">" . $html . "</select>";
	//作成したHTMLコードをはき出す
	echo $html;

}
function comment_option_callback() {
	global $gbSetting;

	$comment_text = $gbSetting['comment'];
?>
   <input type="text" name="sample_user_setting[comment]" value="<?php echo $comment_text; ?>">
<?php	
} 
?>

最後に設定ページのHTMLを仕上げる

一番最初に示したSample Settingページのコーディング例では、非常に簡単なHTMLコーディングでしたが、Setting APIの残りの2つの関数setting_fields、do_settings_sectionsを組み込むことによって、設定ページは完成します。

もうここまでできるはほぼ完成しています。下記に最終的なmy_setting_htmlpage関数のコーディング例をしまします。

//設定ページのHTML(最終版)
function my_setting_htmlpage() {
	global $gbSetting;
	//データベース上の設定値の読込
	$gbSetting = get_option('sample_user_setting');
	if( !$gbSetting ) {
		//設定のデフォルト値 
		$gbSetting = array(
			'option_a' => 1,
			'option_b' => 1,
			'select_mode' => 3,
			'comment' => 'ここはコメント欄です',
		);
		update_option( 'sample_user_setting', $gbSetting );
	}

?>
	<div class="wrap">
	 
	<h2>サンプルプラグイン</h2>
	 
	<form method="post" action="options.php">
	 
	<?php
	     settings_fields( 'sample_option_group' );
	     do_settings_sections( 'sample_setup_page' );
		 submit_button(); // 送信ボタン 
    ?>
	 
	</form>
	 
	</div><!-- .wrap -->
<?php
} 
?>

setting_fields

インターフェース

settings_fields( $option_group )

パラメータ

$option_group(必須)

設定のグループ名。register_setting関数の第1引数に一致させる

戻り値

(void)なし

do_settings_sections

インターフェース

do_settings_sections( $page );

パラメータ

$page(必須)

設定ページで定義したセクションのURLスラッグ。add_settings_section関数の第4引数と一致させる。

サンプルダウンロード

どうですか?

少し難しかったかも知れませんが、ここで紹介したサンプルコーディングファイルをダウンロード出来るようにしました。ダウンロードはブラウザに依存するので、ChromeかFireFoxにてお試しください。

サンプルコーディングをダウンロードする

以上

コメント

タイトルとURLをコピーしました