配列を使った設定APIの例
私はWrox WordPressプラグイン開発本を新しいプラグインを始めるための主な参考資料として使っています。すべての設定を1つの配列として保存できることは理解できますが、この例では説明できません。 Web上での検索は、例ごとに大きく異なるようです。 Konstantinによる ポストの後半 は私を親密にしますが、私は本当に複数のフィールドを持つより完全な例を見たいです。
簡単な答え：あなたのname属性値はスキーマoption_name[array_key]を使わなければなりません。だから、あなたが使うときは…
<input name="option_name[key1]">
<input name="option_name[key2]">
検証関数のオプション値として配列を取得します。
array (
'key1' => 'some value',
'key2' => 'some other value'
)
PHPはあなたのためにそれをします、これはWordPressの機能ではありません。 :)
設定APIでそれを機能させる方法は？
たとえば、このオプションページが必要で、すべての値を1つのオプションに格納し、1つの関数で検証する必要があります。
オプションページ
フックadmin_menuと2つの関数が必要です。1つはページを登録するためのもの、もう1つは出力をレンダリングするためのものです。
add_action( 'admin_menu', 't5_sae_add_options_page' );
function t5_sae_add_options_page()
{
add_options_page(
'T5 Settings API Example', // $page_title,
'T5 SAE', // $menu_title,
'manage_options', // $capability,
't5_sae_slug', // $menu_slug
't5_sae_render_page' // Callback
);
}
function t5_sae_render_page()
{
?>
<div class="wrap">
<h2><?php print $GLOBALS['title']; ?></h2>
<form action="options.php" method="POST">
<?php
settings_fields( 'plugin:t5_sae_option_group' );
do_settings_sections( 't5_sae_slug' );
submit_button();
?>
</form>
</div>
<?php
}
actionの形式はoptions.phpである必要があります。そうしないと検証が呼び出されません。 wp-admin/options-permalink.phpのPHPソースを見てください - 隠れたトラップdo_settings_sections('permalink');があります - しかし、形式actionが間違っているのでそれは動作できません。
さあ、カスタムページに戻りましょう。私たちはWordPressよりも良くしています。
設定、セクション、フィールドを登録する
必要なときにadmin_init にフックして そして登録関数を呼び出します。
if ( ! empty ( $GLOBALS['pagenow'] )
and ( 'options-general.php' === $GLOBALS['pagenow']
or 'options.php' === $GLOBALS['pagenow']
)
)
{
add_action( 'admin_init', 't5_sae_register_settings' );
}
ここで重要なのは、$GLOBALS['pagenow']はoptions-general.php（出力用）またはoptions.php（検証用）のいずれかでなければならないということです。各要求で次のコードをすべて呼び出さないでください。ほとんどのチュートリアルとほとんどすべてのプラグインはこれを誤解しています。
さて、狂ったように登録しましょう：
私たちは自分のページのオプション値を取得し、いくつかのデフォルトに対してそれらを解析します。かなり基本的です。
設定グループを
plugin:t5_sae_option_groupという名前で登録します。私は接頭辞のついた名前が好きです、それらはソートしてこの方法を理解するのがより簡単です。次に、2つのセクション、1と2を登録します。
そして3つのセクションを追加します。2つは最初のセクション、もう1つは2番目のセクションです。各フィールドのコールバック関数にオプション名と エスケープ 値を渡します。出力ハンドラはデータを変更するべきではなく、単にHTMLを追加するだけです。
function t5_sae_register_settings()
{
$option_name = 'plugin:t5_sae_option_name';
// Fetch existing options.
$option_values = get_option( $option_name );
$default_values = array (
'number' => 500,
'color' => 'blue',
'long' => ''
);
// Parse option values into predefined keys, throw the rest away.
$data = shortcode_atts( $default_values, $option_values );
register_setting(
'plugin:t5_sae_option_group', // group, used for settings_fields()
$option_name, // option name, used as key in database
't5_sae_validate_option' // validation callback
);
/* No argument has any relation to the prvious register_setting(). */
add_settings_section(
'section_1', // ID
'Some text fields', // Title
't5_sae_render_section_1', // print output
't5_sae_slug' // menu slug, see t5_sae_add_options_page()
);
add_settings_field(
'section_1_field_1',
'A Number',
't5_sae_render_section_1_field_1',
't5_sae_slug', // menu slug, see t5_sae_add_options_page()
'section_1',
array (
'label_for' => 'label1', // makes the field name clickable,
'name' => 'number', // value for 'name' attribute
'value' => esc_attr( $data['number'] ),
'option_name' => $option_name
)
);
add_settings_field(
'section_1_field_2',
'Select',
't5_sae_render_section_1_field_2',
't5_sae_slug', // menu slug, see t5_sae_add_options_page()
'section_1',
array (
'label_for' => 'label2', // makes the field name clickable,
'name' => 'color', // value for 'name' attribute
'value' => esc_attr( $data['color'] ),
'options' => array (
'blue' => 'Blue',
'red' => 'Red',
'black' => 'Black'
),
'option_name' => $option_name
)
);
add_settings_section(
'section_2', // ID
'Textarea', // Title
't5_sae_render_section_2', // print output
't5_sae_slug' // menu slug, see t5_sae_add_options_page()
);
add_settings_field(
'section_2_field_1',
'Notes',
't5_sae_render_section_2_field_1',
't5_sae_slug', // menu slug, see t5_sae_add_options_page()
'section_2',
array (
'label_for' => 'label3', // makes the field name clickable,
'name' => 'long', // value for 'name' attribute
'value' => esc_textarea( $data['long'] ),
'option_name' => $option_name
)
);
}
セクションとフィールドのすべてのコールバックハンドラは、ページでdo_settings_sections( 't5_sae_slug' );を呼び出すと自動的に呼び出されます。私たちはすでにそれをしたので、私たちはただ…
フィールドを印刷する
name属性がどのように構築されているかに注意してください。渡されたoption_nameは最初の部分で、配列キーは括弧[]で続きます。
function t5_sae_render_section_1()
{
print '<p>Pick a number between 1 and 1000, and choose a color.</p>';
}
function t5_sae_render_section_1_field_1( $args )
{
/* Creates this markup:
/* <input name="plugin:t5_sae_option_name[number]"
*/
printf(
'<input name="%1$s[%2$s]" id="%3$s" value="%4$s" class="regular-text">',
$args['option_name'],
$args['name'],
$args['label_for'],
$args['value']
);
// t5_sae_debug_var( func_get_args(), __FUNCTION__ );
}
function t5_sae_render_section_1_field_2( $args )
{
printf(
'<select name="%1$s[%2$s]" id="%3$s">',
$args['option_name'],
$args['name'],
$args['label_for']
);
foreach ( $args['options'] as $val => $title )
printf(
'<option value="%1$s" %2$s>%3$s</option>',
$val,
selected( $val, $args['value'], FALSE ),
$title
);
print '</select>';
// t5_sae_debug_var( func_get_args(), __FUNCTION__ );
}
function t5_sae_render_section_2()
{
print '<p>Makes some notes.</p>';
}
function t5_sae_render_section_2_field_1( $args )
{
printf(
'<textarea name="%1$s[%2$s]" id="%3$s" rows="10" cols="30" class="code">%4$s</textarea>',
$args['option_name'],
$args['name'],
$args['label_for'],
$args['value']
);
}
ああ、私は関数t5_sae_debug_var()を導入しました。ここにあります：
function t5_sae_debug_var( $var, $before = '' )
{
$export = esc_html( var_export( $var, TRUE ) );
print "<pre>$before = $export</pre>";
}
期待したものが得られたかどうかを確認するのに役立ちます。
さて、これはかなりうまくいきます、私たちはただ一つのことを必要とします：
オプション配列を検証する
大括弧表記を使用したので、値は配列です。各要素を調べて検証するだけです。
function t5_sae_validate_option( $values )
{
$default_values = array (
'number' => 500,
'color' => 'blue',
'long' => ''
);
if ( ! is_array( $values ) ) // some bogus data
return $default_values;
$out = array ();
foreach ( $default_values as $key => $value )
{
if ( empty ( $values[ $key ] ) )
{
$out[ $key ] = $value;
}
else
{
if ( 'number' === $key )
{
if ( 0 > $values[ $key ] )
add_settings_error(
'plugin:t5_sae_option_group',
'number-too-low',
'Number must be between 1 and 1000.'
);
elseif ( 1000 < $values[ $key ] )
add_settings_error(
'plugin:t5_sae_option_group',
'number-too-high',
'Number must be between 1 and 1000.'
);
else
$out[ $key ] = $values[ $key ];
}
elseif ( 'long' === $key )
{
$out[ $key ] = trim( $values[ $key ] );
}
else
{
$out[ $key ] = $values[ $key ];
}
}
}
return $out;
}
これはかなり醜いです。私は本番環境ではそのようなコードを使用しません。しかし、それは本来あるべきことをします：それは検証された値の配列を返します。 WordPressは配列をシリアライズし、データベースにオプション名で格納し、get_option()を呼び出したときにシリアライズされていない状態で返します。
これらすべてはうまくいきますが、それは不必要に複雑で、1998年からのマークアップ（<tr valign="top">）、そして多くの冗長性があります。
必要に応じて設定APIを使用してください。別の方法としてフォームアクションとしてadmin_url( 'admin-post.php' )を使用し（そのソースを見てください）、あなた自身の、おそらくもっと洗練されたコードで完全な設定ページを作成してください。
実際には、ネットワークプラグインを書くときにそれをしなければなりません、設定APIがそこで働かないからです。
私がここで言及しなかったEdgeのケースと不完全な部分もいくつかあります - あなたがそれらを必要とするとき、あなたはそれらを見つけるでしょう。 :)