万が一、当サイトで重大な問題を発見した際などは、フォーラムや WordSlack #docs チャンネルでお知らせください。</p>
管理メニューの追加
目次
はじめに
一般にプラグインやテーマの作者は、カスタマイズ用の設定画面、オプション画面を提供する必要があります。もっとも良い設定画面の提供方法は管理メニュー項目を作成することでしょう。ユーザーは管理画面を使用して設定画面にアクセスできます。この記事ではプラグインの作者を対象に、管理メニューや管理画面の追加方法について説明します。注意 : ここではプラグインの作成、およびアクションやフィルターの プラグイン API について基本的な知識を仮定します。
関数リファレンス
|
|
どこでもフックが必要
管理メニューを追加するには、次の3つのステップが必要です。
- メニュー作成用のコードを含む関数を作成する
- admin_menu/en アクションフックを使用してステップ1で作成した関数を登録する。ネットワーク に管理メニューを追加する場合は、代わりにnetwork_admin_menu/en を使用する。
- メニュー項目をクリックした際に表示されるページ、または画面の HTML 出力を作成する
新米プラグイン開発者が見落としがちなのがステップ2です。メニュー作成用のコードは単純に呼び出せません。コードは関数の中に入れ、この関数を登録する必要があります。
上の3つのステップの非常に簡単な例を示します。このプラグインは管理画面のトップレベルメニュー「設定」の下に、サブレベルのメニュー項目を追加します。メニュー項目をクリックするとシンプルな画面を表示します。注意: このコードはメインのプラグイン PHP ファイル、または個別の PHP インクルードファイルに追加します。
<?php
/** 上のテキストのステップ2 */
add_action( 'admin_menu', 'my_plugin_menu' );
/** ステップ1 */
function my_plugin_menu() {
add_options_page( 'My Plugin Options', 'My Plugin', 'manage_options', 'my-unique-identifier', 'my_plugin_options' );
}
/** ステップ3 */
function my_plugin_options() {
if ( !current_user_can( 'manage_options' ) ) {
wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
}
echo '<div class="wrap">';
echo '<p>オプション用のフォームをここに表示する。</p>';
echo '</div>';
}
?>
この例では、関数 my_plugin_menu() が add_options_page() 関数を使用して管理画面の設定メニューに新しい項目を追加します。注意: より複雑な複数のメニュー項目も追加できます。後半を参照してください。
ステップ2の add_action() 呼び出しにより、admin_menu/en フックに関数 my_plugin_menu() が登録される点に注意してください。add_action() 呼び出しを忘れると、プラグインを有効化した際に PHP エラー undefined function(未定義の関数) が投げられます。最後に add_options_page() 呼び出しは関数 my_plugin_options() を参照します。my_plugin_options() にはユーザーがメニュー項目をクリックした際に表示される実際のページ、および処理用の PHPコードが含まれます。
これらのプロセスについては以下の節で詳細に説明します。繰り返しになりますが、プロセス全体を適切なタイミングで始めるには、必ずメニューやページを作成するコードを関数内に定義し、admin_menu フック を使用してください。
新しいメニュー位置の決定
新しいメニューを作成する前に、まずメニューを トップレベル のメニューにするか、サブレベル のメニュー項目にするかを決めます。トップレベルメニューは管理画面の新しいセクションとして表示され、サブレベルメニュー項目を含みます。サブレベルメニューは、既存のメニュー内のメンバーとなるメニュー項目です。
プラグインでトップレベルメニューの作成が必要となることはまれです。仮にプラグインが WordPress にまったく新しいコンセプトや機能を導入し、その実現に多くの画面が必要であれば、新しいトップレベルメニューが必要でしょう。トップレベルメニューの追加は、WordPress に元々設計に組み込まれていない機能の実現に複数の関連する画面が本当に必要な場合にのみ検討すべきです。新しいトップレベルメニューの例としては業務の管理や会議の管理などがあります。なお標準の 投稿タイプ の登録により、その機能管理のため WordPress は自動的にトップレベルメニューを作成することに注意してください。
トップレベルメニューの作成が不要な場合は、次にどのトップレベルメニューの下にサブレベルメニュー項目を置くかを決めます。参考までにほとんどのプラグインは既存の WordPress トップレベルメニューの下にサブレベルメニュー項目を追加します。たとえば Backup プラグインはトップレベルメニュー「ツール」にサブレベルメニューオプションを追加します。なお タクソノミー の登録により、その機能管理のため WordPress は自動的に適切なトップレベルメニューの下にサブレベルメニューを作成することに注意してください。
次の WordPress トップレベルメニューのガイドを使用して正しい位置にサブレベルメニュー項目を置いてください。
- ダッシュボード
- サイトに関する情報のセンター。WordPressのコア、プラグイン、およびテーマを更新する「更新」オプションが含まれる。
- 投稿
- 時系列コンテンツの「投稿」を書くためのツールを表示
- メディア
- 画像、動画、オーディオのアップロードと管理
- 固定ページ
- 「固定ページ」と呼ばれる静的コンテンツを書くためののツールを表示
- コメント
- コメントの管理と、投稿に返信可能なユーザーの制御
- 外観
- テーマやスタイルファイル、サイドバーなどを編集するコントロールの表示
- プラグイン
- プラグイン管理を扱うコントロールの表示。プラグインそのものの構成オプションは含まれない。
- ユーザー
- ユーザー管理のコントロールを表示
- ツール
- エクスポート、インポート、ブログデータのバックアップの管理
- 設定
- 管理者だけが参照可能なプラグインのオプションを表示。「設定ページの作成」も参照
- ネットワーク管理
- ネットワークに配置されるプラグインのオプションを表示。"admin_menu" の代わりに "network_admin_menu" を使用する必要がある。ネットワークの作成 も参照
トップレベルメニュー、サブレベルメニューのどこに追加するかが決まったら、次に WordPress に対して新しいページを伝えます。これは 'admin_menu' アクションに登録する関数によって行われます。動作可能な例については節末尾を参照してください。
トップレベルメニュー
プラグインに新規のトップレベルメニューが必要と決定した場合、まず初めに add_menu_page を使用してメニューページを作成する必要があります。注意: トップレベルメニューが必要ない場合は「サブレベルメニュー」に進んでください。
<?php add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position ); ?>
パラメータの値 :
- page_title
- メニューが選択された際にページのタイトルタグに表示されるテキスト
- menu_title
- 管理画面のメニュー上での表示名
- capability
- ユーザーがこのメニュー表示する際に必要な権限。フォームの処理に Settings API を使用している場合は 'manage_options' を使用してください。ユーザーがオプションを保存できません。
- menu_slug
- このメニューを参照するスラッグ名。このメニュー固有の必要があります。Version 3.0 以前は file パラメータ、または handle パラメータと呼ばれていました。function パラメータを省略する場合、menu_slug にはメニューページコンテンツの表示を処理する PHP ファイルを指定する必要があります。
- function
- メニューページのコンテンツを表示する関数
- 技術的には functionパラメータはオプションですが、指定されていない場合、WordPress は基本的にインクルードされた PHP ファイルが、関数の呼び出しなしで管理画面を生成するものと仮定します。ページ生成コードはメインのプラグインファイル内の関数に実装できます。
- function パラメータを指定する場合は menu_slug パラメータに任意の文字列を使用できます。?page=my-super-plugin/admin-options.php の代わりに ?page=my_super_plugin_page のようなページを使用できます。
- function は次の2つのどちらかの方法で参照する必要があります:
- 関数がプラグイン内のクラスのメンバーである場合、array( $this, 'function_name' ) として参照する必要があります。
- その他のすべての場合、関数名を使用すれば十分です。
- icon_url
- このメニューで使用されるアイコンの URL 。このパラメータはオプション。
- position
- このメニューが表示されるメニュー順の位置。このパラメータを省略すると、デフォルトではメニュー構造の一番下に表示されます。現在のメニュー位置について参照するには、メニューがロードされた後で print_r($GLOBALS['menu']) を使用してください。
サブレベルメニュー
トップレベルメニューを定義するか、既存の WordPress トップレベルメニューの使用を選択したら、次に add_submenu_page 関数を使用して 1つ以上のサブレベルメニュー項目を定義します。サブレベルメニュー項目は表示する順番に追加してください。
<?php add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function); ?>
パラメータの値 :
- parent_slug
- 親メニューのスラッグ名。またはサブメニューを追加する先のトップレベルメニューを実装する標準 WordPress 管理ファイルのファイル名。またはサブメニューを追加する先のカスタムトップレベルメニューを実装するプラグインファイル
- 例:
- ダッシュボード用: add_submenu_page('index.php',...)
- 投稿用: add_submenu_page('post-new.php',...)
- メディア用: add_submenu_page('upload.php',...)
- 固定ページ用: add_submenu_page('edit.php?post_type=page',...)
- コメント用: add_submenu_page('edit-comments.php',...)
- カスタム投稿タイプ用: add_submenu_page('edit.php?post_type=your_post_type',...)
- 外観用: add_submenu_page('themes.php',...)
- プラグイン用: add_submenu_page('plugins.php',...)
- ユーザ用: add_submenu_page('users.php',...)
- ツール用: add_submenu_page('tools.php',...)
- 設定用: add_submenu_page('options-general.php',...)
- page_title
- サブメニューが有効化された際にHTMLページタイトルに表示されるテキスト
- menu_title
- サブメニューの管理画面上での名前。
- capability
- ユーザーがこのメニュー表示する際に必要な権限。
- menu_slug
- 既存の WordPress メニューの場合、メニューページコンテンツ表示を処理する PHP ファイル。カスタムトップレベルメニューのサブメニューの場合、このサブメニューページの一意の識別子
- プラグインが専用のトップレベルメニューを作成する場合、先頭のサブメニューは通常、トップレベルメニューと同じタイトルへのリンクを持つため、リンクが重複します。重複したリンクタイトルを回避するには、最初に parent_slug パラメータと menu_slug パラメータに同じ値を指定して add_submenu_page を呼び出します。
- function
- メニューページのコンテンツを表示する関数
- 技術的には add_menu_page 関数同様、functionパラメータはオプションですが、指定されていない場合、WordPress は基本的にインクルードされた PHP ファイルが、関数の呼び出しなしで管理画面を生成するものと仮定します。ほとんどのプラグインの作者はメインのプラグインファイル内の関数で、ページ生成コードを実装します。
- function パラメータを指定する場合は menu_slug パラメータに任意の文字列を使用できます。?page=my-super-plugin/admin-options.php の代わりに ?page=my_super_plugin_page のようなページを使用できます。
- function パラメータとしてクラスのメンバーを使用する方法については「トップレベルメニュー」節を参照してください。
例
以下はトップレベルメニューページとサブメニューページを挿入する簡単な例です。ここでサブメニューのタイトルはトップレベルページと異なります。この例では、'my_magic_function'が最初のサブメニューページを表示する関数です。
<?php
add_menu_page('Page title', 'Top-level menu title', 'manage_options', 'my-top-level-handle', 'my_magic_function');
add_submenu_page( 'my-top-level-handle', 'Page title', 'Sub-menu title', 'manage_options', 'my-submenu-handle', 'my_magic_function');
?>
次の例は カスタム投稿タイプメニューブロックの下にオプションページを追加します。こちら も参照してください。
<?php add_submenu_page('edit.php?post_type=wiki', 'Options', 'Options', 'manage_options', 'wiki-options', array(&$this, 'options_page') ); ?>
ラッパー関数の使用
ほとんどのサブレベルメニューは「設定」、「ツール」、「外観」メニューの下に属するため、これらのトップレベルメニューに簡単にサブレベルメニュー項目を追加できるよう、WordPress はラッパー関数を提供します。注意: 管理画面で表示される名前は時間とともに変化したため、関数名と一致しないものがあります。
<?php add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $function); ?>
<?php add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $function); ?>
<?php add_media_page( $page_title, $menu_title, $capability, $menu_slug, $function); ?>
<?php add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $function); ?>
<?php add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $function); ?>
<?php add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function); ?>
<?php add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $function); ?>
<?php add_users_page( $page_title, $menu_title, $capability, $menu_slug, $function); ?>
<?php add_management_page( $page_title, $menu_title, $capability, $menu_slug, $function); ?>
<?php add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function); ?>
「設定ページの作成」も参照してください。
ページの挿入
以下はさまざまな場所に新しいメニューを挿入する WordPress プラグインの例です。
<?php
/*
Plugin Name: Menu Test
Plugin URI: http://codex.wordpress.org/Adding_Administration_Menus
Description: Menu Test
Author: Codex authors
Author URI: http://example.com
*/
// 管理メニューに追加するフック
add_action('admin_menu', 'mt_add_pages');
// 上のフックに対する action 関数
function mt_add_pages() {
// 「設定」下に新しいサブメニューを追加
add_options_page(__('Test Settings','menu-test'), __('Test Settings','menu-test'), 'manage_options', 'testsettings', 'mt_settings_page');
// 「ツール」下に新しいサブメニューを追加
add_management_page( __('Test Tools','menu-test'), __('Test Tools','menu-test'), 'manage_options', 'testtools', 'mt_tools_page');
// 新しいトップレベルメニューを追加 (あれだけ言ったのに...)
add_menu_page(__('Test Toplevel','menu-test'), __('Test Toplevel','menu-test'), 'manage_options', 'mt-top-level-handle', 'mt_toplevel_page' );
// カスタムトップレベルメニューにサブメニューを追加
add_submenu_page('mt-top-level-handle', __('Test Sublevel','menu-test'), __('Test Sublevel','menu-test'), 'manage_options', 'sub-page', 'mt_sublevel_page');
// カスタムトップレベルメニューに2番目のサブメニューを追加
add_submenu_page('mt-top-level-handle', __('Test Sublevel 2','menu-test'), __('Test Sublevel 2','menu-test'), 'manage_options', 'sub-page2', 'mt_sublevel_page2');
}
// mt_settings_page() は Test Settings サブメニューのページコンテンツを表示
function mt_settings_page() {
echo "<h2>" . __( 'Test Settings', 'menu-test' ) . "</h2>";
}
// mt_tools_page() は Test Tools サブメニューのページコンテンツを表示
function mt_tools_page() {
echo "<h2>" . __( 'Test Tools', 'menu-test' ) . "</h2>";
}
// mt_toplevel_page() はカスタムの Test Toplevel メニューのページコンテンツを表示
function mt_toplevel_page() {
echo "<h2>" . __( 'Test Toplevel', 'menu-test' ) . "</h2>";
}
// mt_sublevel_page() はカスタムの Test Toplevel メニューの
// 最初のサブメニューのページコンテンツを表示
function mt_sublevel_page() {
echo "<h2>" . __( 'Test Sublevel', 'menu-test' ) . "</h2>";
}
// mt_sublevel_page() はカスタムの Test Toplevel メニューの
// 2番目のサブメニューのページコンテンツを表示
function mt_sublevel_page2() {
echo "<h2>" . __( 'Test Sublevel2', 'menu-test' ) . "</h2>";
}
?>
メニューページのサンプル
注意: 設定ページの作成に関する情報については「Settings API」を参照してください。
上の例には実際のページコンテンツへのプレースホルダーとして mt_options_page のようないくつかのダミー関数が含まれています。これを実際のメニューページとして実装する必要があります。ここでプラグインにはオプション「mt_favorite_color」があり、サイト管理者は「設定」ページを使用して好きな色を入力できるものとします。関数 mt_options_page は画面にデータ入力用フォームを配置し、入力データを処理します。以下はこの関数の例です。
// mt_settings_page() は Test Settings サブメニューのページコンテンツを表示
function mt_settings_page() {
// ユーザーが必要な権限を持つか確認する必要がある
if (!current_user_can('manage_options'))
{
wp_die( __('You do not have sufficient permissions to access this page.') );
}
// フィールドとオプション名の変数
$opt_name = 'mt_favorite_color';
$hidden_field_name = 'mt_submit_hidden';
$data_field_name = 'mt_favorite_color';
// データベースから既存のオプション値を取得
$opt_val = get_option( $opt_name );
// ユーザーが何か情報を POST したかどうかを確認
// POST していれば、隠しフィールドに 'Y' が設定されている
if( isset($_POST[ $hidden_field_name ]) && $_POST[ $hidden_field_name ] == 'Y' ) {
// POST されたデータを取得
$opt_val = $_POST[ $data_field_name ];
// POST された値をデータベースに保存
update_option( $opt_name, $opt_val );
// 画面に「設定は保存されました」メッセージを表示
?>
<div class="updated"><p><strong><?php _e('settings saved.', 'menu-test' ); ?></strong></p></div>
<?php
}
// ここで設定編集画面を表示
echo '<div class="wrap">';
// ヘッダー
echo "<h2>" . __( 'Menu Test Plugin Settings', 'menu-test' ) . "</h2>";
// 設定用フォーム
?>
<form name="form1" method="post" action="">
<input type="hidden" name="<?php echo $hidden_field_name; ?>" value="Y">
<p><?php _e("Favorite Color:", 'menu-test' ); ?>
<input type="text" name="<?php echo $data_field_name; ?>" value="<?php echo $opt_val; ?>" size="20">
</p><hr />
<p class="submit">
<input type="submit" name="Submit" class="button-primary" value="<?php esc_attr_e('Save Changes') ?>" />
</p>
</form>
</div>
<?php
}
注意点:
- add_menu_page や add_submenu_page などの WordPress 関数には権限を指定し、トップレベルメニューやサブレベルメニューの表示の可否を決定できます。
- ページの出力処理用にフックされる関数も同様に必要なユーザー権限を確認する必要があります。
- ユーザーログインの検証に対してはWordPress 管理関数が責任を持ちます。このため作成する関数内で注意する必要はありません。
- 上の例に挙げた関数は多言語化されています。詳細については プラグインの多言語化を参照してください。
- 関数はすべての入力データを処理してから、画面にデータ入力フォームを表示するため、フォームにはデータベースから取得した値ではなく、新しい値が表示されます。
- 関数名 update_option からデータベースに何もない状態での動作に不安を感じるかもしれませんが、安心してください。update_option 関数は値が存在しなければ、自動的にデータベースへ値を追加します。
- この管理メニュー追加プログラムは、ユーザーが管理画面のページに移動するたびに解析されます。したがってプラグインの開発中、当初オプションページを持たなかったものにあとで追加する場合も、単純に上の手順を使用して追加し、アップロードし直し、満足の行くまで調整するだけで済みます。言い換えればメニューは「永久に追加」されたり、プラグインの有効化の際にデータベースに保存されるわけではありません。メニューは動的に解析されるため、メニュー項目は自由に追加、削除でき、変更も即座に反映されます。
Page Hook Suffix
add_menu_page()、add_submenu_page() およびその特別版である add_options_page() など、新しい管理メニューを追加するすべての関数は特別な値「Page Hook Suffix」を返します。この値はあとで特定のページに対してのみ呼び出されるアクションを登録するフックとして使用できます。
このようなアクションフックの1つがload-{page_hook} です。このとき {page_hook} は関数 add_*_page() から返される値です。このフックは特定のページがロードされる際に呼ばれます。 次の例では、すべての管理画面のページで注意「プラグインが未構成」を表示しますが、Page Hook Suffix を使用してプラグイン自身のオプションページでは表示しません。
<?php
add_action('admin_menu', 'my_plugin_menu');
// ここでプラグインが構成されているかどうかを確認し(例: オプションが設定
// されているかなど)、構成されていなければ、新しいフックを追加
// この例では常にフックを追加
add_action( 'admin_notices', 'my_plugin_admin_notices' );
function my_plugin_menu() {
// 新しい管理メニュー、ページを追加し、戻り値の hook suffix を保存
$hook_suffix = add_options_page('My Plugin Options', 'My Plugin', 'manage_options', 'my-unique-identifier', 'my_plugin_options');
// hook suffix を使用してフックを構成し、プラグインオプションページが
// ロードされた際に実行されるアクションを登録
add_action( 'load-' . $hook_suffix , 'my_load_function' );
}
function my_load_function() {
// 現在の管理ページはこのプラグインのオプションページのため、
// 注意を表示しない (該当のアクションを削除)
remove_action( 'admin_notices', 'my_plugin_admin_notices' );
}
function my_plugin_admin_notices() {
echo "<div id='notice' class='updated fade'><p>My Plugin はまだ構成されていません。すぐに構成してください。</p></div>\n";
}
function my_plugin_options() {
if (!current_user_can('manage_options')) {
wp_die( __('You do not have sufficient permissions to access this page.') );
}
echo '<div class="wrap">';
echo '<p>オプション用のフォームをここに表示する。</p>';
echo '</div>';
}
?>
関連情報
- Admin Menu Editor プラグイン - 管理項目の追加、削除、非表示、並べ替えが可能
最新英語版： WordPress Codex » Adding Administration Menus （最新版との差分）
