トップレベルメニューの追加
WordPress の管理画面に新しいトップレベルメニューを追加するには、add_menu_page() 関数を使用します。
add_menu_page(
string $page_title,
string $menu_title,
string $capability,
string $menu_slug,
callable $function = '',
string $icon_url = '',
int $position = null
);
例
たとえば、「WPOrg」という新しいトップレベルメニューを追加したいとします。
第一のステップ では、HTML を出力する関数を作成します。この関数では、必要なセキュリティチェックを行い、設定 API を使って登録したオプションを書き出します。
wrap の <div> を使用することをおすすめします。
function wporg_options_page_html() {
?>
<div class="wrap">
<h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
<form action="options.php" method="post">
<?php
// output security fields for the registered setting "wporg_options"
settings_fields( 'wporg_options' );
// output setting sections and their fields
// (sections are registered for "wporg", each field is registered to a specific section)
do_settings_sections( 'wporg' );
// output save settings button
submit_button( __( 'Save Settings', 'textdomain' ) );
?>
</form>
</div>
<?php
}
第二のステップ では、WPOrg メニューを登録します。この登録は admin_menu アクションフックで行う必要があります。
add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
add_menu_page(
'WPOrg',
'WPOrg Options',
'manage_options',
'wporg',
'wporg_options_page_html',
plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
20
);
}
パラメータのリストとそれぞれの役割については、リファレンスの add_menu_page() を参照してください。
HTML 用 PHP ファイルの使用
移植可能なコードを作成するためのベストプラクティスは、PHP ファイルを require/include するコールバックを作成することです。
完璧を期すため、またレガシーコードを理解してもらうため、別の方法を示しましょう: これは、PHP ファイルパス を $menu_slug パラメータとして渡し、null $function パラメータを渡すものです。
add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
add_menu_page(
'WPOrg',
'WPOrg Options',
'manage_options',
plugin_dir_path(__FILE__) . 'admin/view.php',
null,
plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
20
);
}
トップレベルメニューの削除
WordPress の管理画面から登録したメニューを削除するには、remove_menu_page() 関数を使用します。
remove_menu_page(
string $menu_slug
);
例
たとえば、「ツール」メニューを削除したいとします。
add_action( 'admin_menu', 'wporg_remove_options_page', 99 );
function wporg_remove_options_page() {
remove_menu_page( 'tools.php' );
}
メニューが admin_menu フックに登録されていることを確認してから削除を試み、add_action() に高い優先順位を指定してください。
フォームの送信
オプションページでフォームの送信を処理するには、2つのものが必要です:
- フォームの
action属性としてページの URL を使用する。 add_menu_pageが返すスラッグをフックに追加する。
フォームのアクション属性
オプションページの $menu_slug パラメータを menu_page_url() の最初のパラメータとして使用します。この関数はデフォルトで自動的に URL をエスケープして出力するので、<form> タグ内で直接使用できます:
<form action="<?php menu_page_url( 'wporg' ) ?>" method="post">
フォームの処理
ページを追加するときに指定した $function は、ページを表示するときに初めて呼び出されるため、ブラウザーにヘッダー (リダイレクトなど) を送り返す必要がある場合には不適切です。
add_menu_page は $hookname を返し、WordPress は HTML が出力される前に "load-$hookname" アクションをトリガーします。これを利用して、フォームを処理する関数を割り当てることができます。
"load-$hookname" は、フォームが送信されていないときでも、オプションページが表示される前に毎回実行されます。
リターン・パラメータとアクションを念頭に置くと、上記の例は次のようになります:
add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
$hookname = add_menu_page(
'WPOrg',
'WPOrg Options',
'manage_options',
'wporg',
'wporg_options_page_html',
plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
20
);
add_action( 'load-' . $hookname, 'wporg_options_page_submit' );
}
wporg_options_page_submit は、必要に応じてプログラムできますが、以下のような必要なチェックをすべて手動で行わなければならないことを覚えておいてください:
- フォームが送信されているかどうか (
'POST' === $_SERVER['REQUEST_METHOD']) - CSRF 検証
- バリデーション
- サニタイゼーション