概要

Settings APIは、WordPress 2.7で追加され、設定フォームを含む管理ページを半自動的に管理できるようにします。設定ページ、ページ内のセクション、およびセクション内のフィールドを定義できます。

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

フィールドの登録と検証を整理するには、Settings APIを使用する開発者の努力が必要ですが、基盤となるオプション管理の複雑なデバッグを大幅に回避できます。

注意: Settings APIを使用する場合、フォームはwp-admin/options.phpに投稿され、かなり厳格な権限チェックが行われます。ユーザーはmanage_optionsの権限が必要です（MultiSiteではスーパ管理者である必要があります）フォームを送信するには。

関数はwp-admin/includes/plugin.phpとwp-admin/includes/template.phpにあります。

関数リファレンス

設定の登録/登録解除:

フィールド/セクションの追加:

オプションフォームのレンダリング:

エラー:

設定フィールドの追加

この関数を使用して、既存のWordPressページに新しい設定フィールド（基本的にはwp_optionsデータベーステーブルのオプションですが、完全に管理されます）を追加できます。コールバック関数は、適切なHTML入力を出力し、古い値で埋める必要があります。保存は裏で行われます。add_settings_section()を使用して、既存のページに独自のセクションを作成できます。

注意:add_settings_field()で使用するオプションはすべて登録する必要があります。そうしないと、自動的に保存および更新されません。詳細と例については、以下を参照してください。 

  1. add_settings_field( $id, $title, $callback, $page, $section = 'default', $args = array() )
  • $id– タグの’id’属性で使用する文字列。
  • $title– フィールドのタイトル。
  • $callback– フィールドを希望の入力で埋める関数。入力の名前とidは、この関数に与えられた$idと一致する必要があります。関数はその出力をエコーする必要があります。
  • $page– フィールドを表示する設定ページのタイプ（一般、読み取り、書き込みなど）。
  • $section– ボックスを表示する設定ページのセクション（デフォルトまたはadd_settings_sectionで追加したセクション、既存のものを確認するにはソースのページを見てください。）
  • $args– コールバック関数に渡される追加の引数

設定セクションの追加

設定セクションは、共通の見出しを持つWordPress設定ページに表示される設定のグループです。プラグイン内で、全く新しいページを作成するのではなく、既存の設定ページに新しいセクションを追加できます。これにより、プラグインのメンテナンスが簡単になり、ユーザーが学ぶ新しいページが少なくなります。関連する既存のページで設定を変更するように指示するだけです。 

  1. add_settings_section( $id, $title, $callback, $page );
  • $id– タグの’id’属性で使用する文字列。
  • $title– セクションのタイトル。
  • $callback– セクションを希望のコンテンツで埋める関数。関数はその出力をエコーする必要があります。
  • $page– セクションを表示する設定ページのタイプ（一般、読み取り、書き込み、メディアなど）。

設定の登録

  1. register_setting( $option_group, $option_name, $args );
  1. unregister_setting( $option_group, $option_name );

注意:register_setting()および上記のadd_settings_*()関数はすべて、admin_initアクションフックのコールバック関数から呼び出す必要があります。「例」セクションを参照してください。

オプションフォームのレンダリング

APIを使用して既存のオプションページに設定を追加する場合、フォーム自体について心配する必要はありません。すでにページのために定義されています。新しいページをゼロから定義する場合は、実際のセクションとページの設定を出力するいくつかのタグを含む最小限のフォーム構造を出力する必要があります。

隠しフィールドを表示し、オプションフォームのセキュリティを処理するために、Settings APIはsettings_fields()関数を提供します。 settings_fields( $option_group );

$option_group(*string*) (*required*):**

設定グループ名。これは、register_setting()で使用されるグループ名と一致する必要があります。これは、フォームが表示されるページのスラッグ名です。デフォルト:なし

ページに割り当てられたセクションとその中に含まれる設定を表示するために、Settings APIはdo_settings_sections()関数を提供します。do_settings_sections( $page );

$page(*string*) (*required*):**

出力したい設定セクションのページのスラッグ名。これは、add_settings_section()で使用されるページ名と一致する必要があります。デフォルト:なし

do_settings_fields()関数は、特定のページとセクションに割り当てられたフィールドを出力するために提供されます。この関数を直接呼び出すべきではなく、do_settings_sections()を使用してセクションのコンテンツと関連するフィールドを出力してください。

オプションフォームには、送信ボタンも必要です。これを行うために、submit_button()関数を使用できます。

最後に、オプションのアクション先であるoptions.phpとPOSTメソッドを定義するHTML<form>タグを出力する必要があります。以下は、スラッグ名がmy-pageのページに追加されたすべてのセクションとフィールドを生成するオプションフォームコードの例です。 

  1. <form method="POST" action="options.php">
  2. <?php
  3. settings_fields( 'my-page' ); // pass slug name of page, also referred to in Settings API as option group name
  4. do_settings_sections( 'my-page' );  // pass slug name of page
  5. submit_button(); // submit button
  6. ?>
  7. </form>

例

新しいフィールドを持つ設定セクションの追加

  1. <?php
  2. /**
  3.  * Add all your sections, fields and settings during admin_init
  4.  */
  6. function wporg_settings_api_init() {
  7.      // Add the section to reading settings so we can add our
  8.      // fields to it
  9.      add_settings_section(
  10.         'wporg_setting_section',
  11.         'Example settings section in reading',
  12.         'wporg_setting_section_callback_function',
  13.         'reading'
  14.     );
  16.      // Add the field with the names and function to use for our new
  17.      // settings, put it in our new section
  18.      add_settings_field(
  19.         'wporg_setting_name',
  20.         'Example setting Name',
  21.         'wporg_setting_callback_function',
  22.         'reading',
  23.         'wporg_setting_section'
  24.     );
  26.      // Register our setting so that $_POST handling is done for us and
  27.      // our callback function just has to echo the <input>
  28.      register_setting( 'reading', 'wporg_setting_name' );
  29.  } // wporg_settings_api_init()
  31.  add_action( 'admin_init', 'wporg_settings_api_init' );
  33. /**
  34.  * Settings section callback function
  35.  *
  36.  * This function is needed if we added a new section. This function
  37.  * will be run at the start of our section
  38.  */
  40.  function wporg_setting_section_callback_function() {
  41.      echo '<p>Intro text for our settings section</p>';
  42.  }
  44. /*
  45.  * Callback function for our example setting
  46.  *
  47.  * creates a checkbox true/false option. Other types are surely possible
  48.  */
  50.  function wporg_setting_callback_function() {
  51.      echo '<input name="wporg_setting_name" id="wporg_setting_name" type="checkbox" value="1" class="code" ' . checked( 1, get_option( 'wporg_setting_name' ), false ) . ' /> <label for="wporg_setting_name">Explanation text</label>';
  52.  }

コードがどこに配置されるべきかのグラフィカルな表現

Settings - img1

外部参照

ジェネレーター

PHPクラス