Settings API で WordPress 管理画面を作る

WordFes Nagoya 2015のセッションで取り上げるサンプルプラグインの解説です。

管理画面の登録

管理画面をまず作る処理です。add_options_pageを使います。このページへの実際の出力はコールバック関数で設定します。

Settings APIの場合、「ページ」「セクション」「フィールド」の順に作っていきます。

// 設定画面を追加する
function my_slider_settings_menu() {
    add_options_page(
        'スライダー詳細設定', // ページのタイトル
        'スライダー詳細設定', // メニューのタイトル
        'manage_options', // このページを操作する権限
        'my_slider_settings', // ページ名
        'my_slider_settings_plugin_options' // コールバック関数。この関数の実行結果が出力される
    );
}
add_action('admin_menu', 'my_slider_settings_menu');

// フォームの枠組を出力する
function my_slider_settings_plugin_options() {
?>
    <div class="wrap">
        <form action="options.php" method="post">
<?php do_settings_sections('my_slider_settings'); // ページ名 ?>
<?php settings_fields('my_slider_settings-group'); // グループ名 ?>
<?php submit_button(); ?>
        </form>
    </div>
<?php
}

do_settings_sectionsで設定セクションを作ります。 settings_fieldsは画面が正当であることを証明するコード等を出力します。つまり、settings_fieldsを入れるだけで、面倒な処理をWPが面倒見てくれます。

画面上にセクションを作成

次に、セクションを作ります。add_settings_sectionを使います。4番目の引数は、先ほどdo_settings_sectionsで設定したページ名に合わせます。

// 管理画面の作成
function my_slider_settings_init() {
    add_settings_section(
        'my_slider_settings_section', // セクション名
        'スライダーの設定', // タイトル
        'my_slider_settings_section_callback_function', // コールバック関数。この関数の実行結果が出力される
        'my_slider_settings' // このセクションを表示するページ名。do_settings_sectionsで設定
    );
}
add_action('admin_init', 'my_slider_settings_init');

function my_slider_settings_section_callback_function() {
    echo '<p>スライダーの詳細設定を行います</p>';
}

画面上にフィールドを作成

さて、ようやくフィールドを作ります。このフィールドのところが、入力項目を作る部分になります。 add_settings_fieldを使います。4番目の引数は、先ほどdo_settings_sectionsで設定したページ名に合わせます。5番目の引数は、先ほどadd_settings_sectionで設定したセクション名に合わせます。

入力項目の処理は、register_settingで設定します。1番目の引数は、先ほどsettings_fieldsで設定したグループ名に合わせます。実際の処理内容は、3番目の引数でコールバック関数を指定します。

// フィールドの追加1
function my_slider_field1() {

    add_settings_field(
        'num_of_slides', // フィールド名
        '枚数', // タイトル
        'num_of_slides_callback_function', // コールバック関数。この関数の実行結果が出力される
        'my_slider_settings', // このフィールドを表示するページ名。do_settings_sectionsで設定
        'my_slider_settings_section' // このフィールドを表示するセクション名。add_settings_sectionで設定
    );

    register_setting(
        'my_slider_settings-group', // グループ名。settings_fieldsで設定
        'my_slider_settings_num_of_slides', // オプション名
        'my_slider_settings_num_of_slides_check' // 入力値をサニタイズする関数
    );
}
add_action('admin_init', 'my_slider_field1', 15);

// フォーム項目を表示する
function num_of_slides_callback_function() {
    echo '<input name="my_slider_settings_num_of_slides" id="my_slider_settings_num_of_slides" type="text" value="';
    form_option( 'my_slider_settings_num_of_slides' );
    echo '" />';
}

// 入力値「スライド枚数」を検証する
// 必要に応じてエラーメッセージを出す
function my_slider_settings_num_of_slides_check( $input ) {
    $filter_option = array(
        'options' => array(
            'min_range' => 1,
        ),
    );
    if ( filter_var( $input, FILTER_VALIDATE_INT, $filter_option) ) {
        return $input;
    } else {
        add_settings_error(
            'my_slider_settings',
            'invalid_num',
            '枚数: ' . intval( $filter_option['options']['min_range'] ) . ' 以上の数字を指定してください。',
            'error'
        );
        return intval( get_option( 'my_slider_settings_num_of_slides' ) );
    }
}

コールバック関数my_slider_settings_num_of_slides_checkの内部で、入力が適切かどうかをチェックします。この例では、PHPの標準機能であるフィルタ機能を使って、「入力が数値である&1以上である」をチェックしています。

入力が条件を満たさなかった場合

コールバック関数内で検証した結果、入力が条件を満たさなかった場合は、add_settings_errorでエラーメッセージを設定することができます。こうしておくと、WPがエラーメッセージを表示してくれます。このようにWPの標準機能を使うと、画面遷移等の面倒な処理を自分で記述する必要はありません。

フィールドの数だけ繰り返す

複数のフィールドが有る場合は、add_settings_fieldとregister_settingを繰り返し記述してください。

(データベースで一つの項目として保存したい場合は、記述を変更する必要がありますが、今回はSettings APIの使い方の説明を中心にしたので、単純な方式で記述しています。)

// フィールドの追加2
function my_slider_field2() {

    add_settings_field(
        'random', // フィールド名
        'ランダム表示', // タイトル
        'random_callback_function', // コールバック関数。この関数の実行結果が出力される
        'my_slider_settings', // このフィールドを表示するページ名。do_settings_sectionsで設定
        'my_slider_settings_section' // このフィールドを表示するセクション名。add_settings_sectionで設定
    );

    register_setting(
        'my_slider_settings-group', // グループ名。settings_fieldsで設定
        'my_slider_settings_random', // オプション名
        'intval' // 入力値をサニタイズする関数
    );
}
add_action('admin_init', 'my_slider_field2', 25);

// フォーム項目を表示する
function random_callback_function() {
    echo '<input name="my_slider_settings_random" id="my_slider_settings_random" type="checkbox" value="1" ';
    checked( 1, get_option( 'my_slider_settings_random' ) ) ;
    echo ' />';
    echo 'ランダム表示する';
}

WordPress 管理画面を効率よく、安全に作成する方法 from Fumito Mizuno

管理画面の登録

画面上にセクションを作成

画面上にフィールドを作成

入力が条件を満たさなかった場合

フィールドの数だけ繰り返す

新着ブログ記事