関数リファレンス/register setting

このページ「関数リファレンス/register setting」は参考節以降が未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています。

この項目「関数リファレンス/register setting」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

説明

設定項目と無害化用コールバックを登録します。

これは Settings API の一部です。設定項目を登録し、出力を制御するわずかなコールバックを使って、wp-admin 設定ページを自動的に生成します。

この関数を使って、"media" や "general" のような WordPress のデフォルトの設定ページに設定項目を登録することもできます。（WordPress 4.1 以降、この関数は "permalink" ページへ追加された設定を保存しません。）設定項目を登録すると、add_settings_field() で既存のセクションへ追加したり、add_settings_section() で作った新規セクションへ追加したりできます。

使い方

<?php register_setting( $option_group, $option_name, $sanitize_callback ); ?>

パラメータ

$option_group

（文字列） （必須） 設定のグループ名。register_setting() を呼び出す前に存在する必要がある。settings_fields() のグループ名と一致しなければならない。

初期値： なし

$option_name

（文字列） （必須） 無害化して保存するオプションの名前。

初期値： なし

$sanitize_callback

（コールバック） （オプション） オプションの値を無害化するコールバック関数。

初期値： なし

戻り値

(void) 

この関数は値を返さない。

用例

function register_my_setting() {
	register_setting( 'my_options_group', 'my_option_name', 'intval' ); 
} 
add_action( 'admin_init', 'register_my_setting' );

参考

• データは無害化コールバック関数へ 2 回通されるようです。この例の場合、文字列に感嘆符が 2 個つきます: function append_exclamation ( $input ) { return $input . '!'; }

これは wp_options テーブルにオプションがまだ無いときに発生します。問題は options.php が使っているテクニックにあります。まず update_option() を呼び出し、オプションがまだ無いことをフォールバックで検出したときに add_option() を呼び出します。update_option() も add_option() も sanitize_option を呼び出すので計 2 回になります。

• 「エラー: 設定ページが見つかりません。」 問題（解決方法と説明）:

これは、あなたのデータに対する正しいインデックスを 'whitelist_options' フィルターが受け取れないという問題です。これは options.php の 98 行目（WordPress 3.4）で行われます。

register_settings() adds your data to the global $new_whitelist_options. This then gets merged with the global $whitelist_options inside the option_update_filter() (resp. add_option_whitelist()) callback(s). Those callbacks add your data to the global $new_whitelist_options with the $option_group as index. When you encounter "Error: options page not found." it means your index hasn't been recognized. The misleading thing is that the first argument is used as index and named $options_group, when the actual check in options.php#112 happens against $options_page, which is the $hook_suffix, which you get as @return value from add_submenu_page().

要約すると、簡単な解決方法は $option_group を $option_name に一致させます。

Another cause for this error is having an invalid value for $page parameter when calling either add_settings_section( $id, $title, $callback, $page ) or add_settings_field( $id, $title, $callback, $page, $section, $args ).

Hint: $page should match $menu_slug from Function Reference/add theme page.

• Make sure that the sanitization callback function input type is consistent with the $option_name type. For example, the absint function wouldn't work properly if $option_name is an array.

変更履歴

新規導入: 2.7.0

ソースファイル

register_setting() is located in wp-admin/includes/plugin.php.

リソース

• Handling Plugins Options in WordPress 2.8 with register_setting()
• WordPress Settings API Tutorial

関連項目

Settings API: register_setting(), unregister_setting(), add_settings_field(), add_settings_section(), add_settings_error(), get_settings_errors(), settings_errors(), settings_fields(), do_settings_sections(), do_settings_fields()

関数リファレンス、テンプレートタグ目次もご覧ください。

最新英語版： WordPress Codex » Function_Reference/register_setting （最新版との差分）