関数リファレンス

メニューページ

add_menu_page()

add_object_page()

add_utility_page()

remove_menu_page()

サブメニューページ

add_submenu_page()

remove_submenu_page()

WordPress管理メニュー

add_dashboard_page()

add_posts_page()

add_media_page()

add_links_page()

add_pages_page()

add_comments_page()

add_theme_page()

add_plugins_page()

add_users_page()

add_management_page()

add_options_page()

すべてのプロットにはフックが必要

管理メニューを追加するには、次の3つのことを行う必要があります：

  • 1. メニュー構築コードを含む関数を作成します。
  • 2. 上記の関数を admin_menu アクションフックを使用して登録します – または、ネットワーク用のメニューを追加する場合は network_admin_menu を使用します。
  • 3. メニュー項目がクリックされたときに表示される画面のHTML出力を作成します。

ほとんどの開発者はこのリストの2番目のステップを見落とします。単にメニューコードを呼び出すことはできません。関数の中に入れる必要があります、そしてこの関数を登録します。

以下は、これらの3つのステップを説明する簡単な例です。これにより、設定のトップレベルメニューの下にサブレベルメニュー項目が追加されます。選択すると、そのメニュー項目は非常に基本的な画面を表示します。 

  1. <?php
  2. /** Step 2 (from text above). */
  3. add_action( 'admin_menu', 'my_menu' );
  5. /** Step 1. */
  6. function my_menu() {
  7.     add_options_page(
  8.         'My Options',
  9.         'My Menu',
  10.         'manage_options',
  11.         'my-unique-identifier',
  12.         'my_options'
  13.     );
  14. }
  16. /** Step 3. */
  17. function my_options() {
  18.     if ( ! current_user_can( 'manage_options' ) ) {
  19.         wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
  20.     }
  21.     echo 'Here is where I output the HTML for my screen.';
  22.     echo '</div><pre>';
  23. }

この例では、関数 my_menu() が add_options_page() 関数を介して設定管理メニューに新しい項目を追加します。

注: ステップ2の add_action() 呼び出しは、admin_menu フックの下で my_menu() 関数を 登録します。それがなければ、未定義の関数に対するPHPエラーが発生します。最後に、add_options_page() 呼び出しは、メニュー項目がクリックされたときに表示される実際のページを含む my_options() 関数を参照します。

これらのステップは、以下のセクションでより詳細に説明されています。メニューとページの作成を関数に囲むことを忘れず、admin_menu フック を使用して、適切なタイミングで全プロセスを開始します。

新しいメニューの位置を決定する

新しいメニューを作成する前に、そのメニューがトップレベルメニューであるべきか、サブレベルメニュー項目であるべきかを最初に決定します。トップレベルメニューは、管理メニューの新しいセクションとして表示され、サブレベルメニュー項目を含みます。これは、サブレベルメニュー項目が既存のトップレベルメニューのメンバーであることを意味します。

テーマが新しいトップレベルメニューの作成を必要とすることは稀です。テーマがWordPressにまったく新しい概念を導入し、それを実現するために多くの画面が必要な場合、そのテーマは新しいトップレベルメニューを必要とするかもしれません。トップレベルメニューの追加は、WordPressが元々設計されていないことを実現するために、関連する複数の画面が本当に必要な場合にのみ考慮すべきです。新しいトップレベルメニューの例には、ジョブ管理や会議管理が含まれるかもしれません。ネイティブの post type 登録により、WordPressはこの種の機能を管理するために自動的にトップレベルメニューを作成しますのでご注意ください。

トップレベルメニューの作成が必要ない場合は、新しいサブレベルメニュー項目をどのトップレベルメニューの下に配置するかを決定する必要があります。参考までに、いくつかのテーマは既存のWordPressトップレベルメニューの下にサブレベルメニュー項目を追加します。

サブレベルメニュー項目の正しい位置を決定するために、WordPressのトップレベルメニューのガイドを使用してください：

  • ダッシュボード – サイトの情報センターで、WordPressコア、プラグイン、テーマの更新オプションを含みます。
  • 投稿 – 投稿を書くためのツールを表示します（時間指向のコンテンツ）。
  • メディア – 画像、動画、音声をアップロードおよび管理します。
  • リンク – 他のブログや興味のあるサイトへの参照を管理します。
  • ページ – 静的コンテンツであるページを書くためのツールを表示します。
  • コメント – 投稿に対する読者の反応を制御および規制します。
  • 外観 – テーマ/スタイルファイル、サイドバーなどの操作のためのコントロールを表示します。
  • プラグイン – プラグイン管理に関するコントロールを表示し、プラグイン自体の設定オプションではありません。
  • ユーザー – ユーザー管理のためのコントロールを表示します。
  • ツール – ブログデータのエクスポート、インポート、バックアップを管理します。
  • 設定 – 管理者のみが表示すべきプラグインオプションを表示します。
  • ネットワーク管理 – ネットワーク上で設定されたプラグインオプションを表示します。 admin_menu の代わりに network_admin_menu を使用する必要があります（ネットワークの作成も参照）。

トップレベルメニュー

テーマが新しいトップレベルメニューを必要とすることが決定した場合、最初に行うべきことは add_menu_page() 関数を使用してそれを作成することです。注: トップレベルメニューが必要ない場合は、サブレベルメニューにスキップしてください。

パラメータ値：

  • page_title – メニューが選択されたときにページのタイトルタグに表示されるテキスト。
  • menu_title – メニューの画面上の名前テキスト。
  • capability – このメニューがユーザーに表示されるために必要な権限。設定APIを使用してフォームを処理する場合は、ここで manage_options を使用する必要があります。ユーザーレベルは非推奨であり、ここでは使用すべきではありません。
  • menu_slug – このメニューを参照するためのスラッグ名（このメニューに対して一意である必要があります）。バージョン3.0以前は、これをファイル（またはハンドル）パラメータと呼んでいました。関数パラメータが省略された場合、menu_slug はメニューページのコンテンツを表示するPHPファイルである必要があります。
  • function – メニューページのコンテンツを表示する関数。
  • icon_url – このメニューに使用されるアイコンのURL。このパラメータはオプションです。
  • position – メニューの順序でこのメニューが表示される位置。デフォルトでは、このパラメータが省略されると、メニューはメニュー構造の下部に表示されます。現在のメニュー位置を確認するには、メニューが読み込まれた後に print_r( $GLOBALS[ 'menu' ] ) を使用します。
  • サブレベルメニュー – トップレベルメニューが定義されたら、または既存のWordPressトップレベルメニューを使用することを選択したら、add_submenu_page() 関数を使用して1つ以上のサブレベルメニュー項目を定義する準備が整います。

サブレベルメニュー

新しいメニュー項目をサブメニュー項目にしたい場合は、代わりに add_submenu_page() 関数を使用して作成できます。

パラメータ値：

  • parent_slug – 親メニューのスラッグ名、またはサブメニューを挿入したいトップレベルメニューを提供する標準のWordPress管理ファイルのファイル名、またはこのサブメニューがカスタムトップレベルメニューに入る場合はプラグインファイル。例：
    • ダッシュボード – add_submenu_page('index.php', ...)
    • 投稿 – add_submenu_page('edit.php', ...)
    • メディア – add_submenu_page('upload.php', ...)
    • リンク – add_submenu_page('link-manager.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ファイル。カスタムトップレベルメニューのサブメニューの場合、このサブメニューページの一意の識別子。
  • function – メニューページのコンテンツを表示する関数。技術的には、add_menu_page 関数のように、関数パラメータはオプションですが、提供されない場合、WordPressは基本的にPHPファイルを含めることで管理画面を生成することを想定します。

ラッパー関数の使用

ほとんどのサブレベルメニューは設定、ツール、または外観メニューの下に属するため、WordPressはこれらのトップレベルメニューにサブレベルメニュー項目を追加するのを容易にするラッパー関数を提供します。関数名は、時間の経過とともに変更されているため、管理UIで見られる名前と一致しない場合があります。

ダッシュボード

  1. <?php
  2. add_dashboard_page(
  3.     $page_title,
  4.     $menu_title,
  5.     $capability,
  6.     $menu_slug,
  7.     $function
  8. );

投稿

  1. <?php
  2. add_posts_page(
  3.     $page_title,
  4.     $menu_title,
  5.     $capability,
  6.     $menu_slug,
  7.     $function
  8. );

メディア

  1. <?php
  2. add_media_page(
  3.     $page_title,
  4.     $menu_title,
  5.     $capability,
  6.     $menu_slug,
  7.     $function
  8. );

リンク

  1. <?php
  2. add_links_page(
  3.     $page_title,
  4.     $menu_title,
  5.     $capability,
  6.     $menu_slug,
  7.     $function
  8. );

ページ

  1. <?php
  2. add_pages_page(
  3.     $page_title,
  4.     $menu_title,
  5.     $capability,
  6.     $menu_slug,
  7.     $function
  8. );

コメント

  1. add_comments_page(
  2.     $page_title,
  3.     $menu_title,
  4.     $capability,
  5.     $menu_slug,
  6.     $function
  7. );

外観

  1. <?php
  2. add_theme_page(
  3.     $page_title,
  4.     $menu_title,
  5.     $capability,
  6.     $menu_slug,
  7.     $function
  8. );

プラグイン

  1. <?php
  2. add_plugins_page(
  3.     $page_title,
  4.     $menu_title,
  5.     $capability,
  6.     $menu_slug,
  7.     $function
  8. );

ユーザー

  1. <?php
  2. add_users_page(
  3.     $page_title,
  4.     $menu_title,
  5.     $capability,
  6.     $menu_slug,
  7.     $function
  8. );

ツール

  1. <?php
  2. add_management_page(
  3.     $page_title,
  4.     $menu_title,
  5.     $capability,
  6.     $menu_slug,
  7.     $function
  8. );

設定

  1. <?php
  2. add_options_page(
  3.     $page_title,
  4.     $menu_title,
  5.     $capability,
  6.     $menu_slug,
  7.     $function
  8. );

また、テーマオプションを参照して、Customizer APIを介してオプションを作成するための現在推奨される方法を確認してください。

例

ここでは、トップレベルメニューページとサブメニューページを挿入する方法を示す簡単な例を示します。サブメニューページのタイトルはトップレベルページとは異なります。この例では、register_my_theme_more_settings_menu は最初のサブメニューページを表示する関数の名前です： 

  1. <?php
  2. function register_my_theme_settings_menu() {
  3.     add_menu_page(
  4.         "My Theme's Settings",
  5.         'My Theme',
  6.         'manage_options',
  7.         'my-theme-settings-menu'
  8.     );
  9. }
  11. function register_my_theme_more_settings_menu() {
  12.     add_submenu_page(
  13.         'my-theme-settings-menu',
  14.         'More Settings for My Theme',
  15.         'More Settings',
  16.         'manage_options',
  17.         'my-theme-more-settings-menu'
  18.     );
  19. }
  21. add_action( 'admin_menu', 'register_my_theme_settings_menu' );
  22. add_action( 'admin_menu', 'register_my_theme_more_settings_menu' );

カスタム投稿タイプメニューブロックの下にオプションページを追加する例です（こちらも参照）：

コード

ページの挿入

さまざまな場所に複数のメニューを挿入する方法の例を示します： 

  1. <?php
  2. // Hook for adding admin menus
  3. add_action( 'admin_menu', 'mt_add_pages' );
  5. // Action function for hook above
  6. function mt_add_pages() {
  7.     // Add a new submenu under Settings:
  8.     add_options_page( __( 'Test Settings', 'menu-test' ), __( 'Test Settings', 'menu-test' ), 'manage_options', 'testsettings', 'mt_settings_page' );
  10.     // Add a new submenu under Tools:
  11.     add_management_page( __( 'Test Tools', 'menu-test' ), __( 'Test Tools', 'menu-test' ), 'manage_options', 'testtools', 'mt_tools_page' );
  13.     // Add a new top-level menu (ill-advised):
  14.     add_menu_page( __( 'Test Toplevel', 'menu-test' ), __( 'Test Top-level', 'menu-test' ), 'manage_options', 'mt-top-level-handle', 'mt_toplevel_page' );
  16.     // Add a submenu to the custom top-level menu:
  17.     add_submenu_page( 'mt-top-level-handle', __( 'Test Sub-Level', 'menu-test' ), __( 'Test Sub-Level', 'menu-test' ), 'manage_options', 'sub-page', 'mt_sublevel_page' );
  19.     // Add a second submenu to the custom top-level menu:
  20.     add_submenu_page( 'mt-top-level-handle', __( 'Test Sub-Level 2', 'menu-test' ), __( 'Test Sub-Level 2', 'menu-test' ), 'manage_options', 'sub-page2', 'mt_sublevel_page2' );
  21. }
  23. // mt_settings_page() displays the page content for the Test settings sub-menu.
  24. function mt_settings_page() {
  25.     echo '</pre><h2>' . __( 'Test Settings', 'menu-test' ) . '</h2><pre>';
  26. }
  28. // mt_tools_page() displays the page content for the Test Tools sub-menu.
  29. function mt_tools_page() {
  30.     echo '</pre><h2>' . __( 'Test Tools', 'menu-test' ) . '</h2><pre>';
  31. }
  33. // mt_toplevel_page() displays the page content for the custom Test Top-Level menu.
  34. function mt_toplevel_page() {
  35.     echo '</pre><h2>' . __( 'Test Top-Level', 'menu-test' ) . '</h2><pre>';
  36. }
  38. // mt_sublevel_page() displays the page content for the first sub-menu of the custom Test Toplevel menu.
  39. function mt_sublevel_page() {
  40.     echo '</pre><h2>' . __( 'Test Sub-Level', 'menu-test' ) . '</h2><pre>';
  41. }
  43. // mt_sublevel_page2() displays the page content for the second sub-menu of the custom Test Top-Level menu.
  44. function mt_sublevel_page2() {
  45.     echo '</pre><h2>' . __( 'Test Sub-Level 2', 'menu-test' ) . '</h2><pre>';
  46. }

サンプルメニューページ

注: 設定ページを作成するための情報は Settings API を参照してください。

前の例には、mt_settings_page() のようなダミー関数がいくつか含まれており、実際のページコンテンツのプレースホルダーとして機能します。サイト所有者が設定ページを介してお気に入りの色を入力できるようにする mt_favorite_color というオプションを作成したい場合はどうでしょうか？ mt_options_page() 関数は、画面にデータ入力フォームを出力し、入力されたデータを処理する必要があります。

これを行う関数は次のとおりです： 

  1. <?php
  2. // mt_settings_page() displays the page content for the Test settings sub-menu.
  3. function mt_settings_page() {
  4.     // Must check that the user has the required capability.
  5.     if ( ! current_user_can( 'manage_options' ) ) {
  6.         wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
  7.     }
  9.     // Variables for the field and option names
  10.     $opt_name          = 'mt_favorite_color';
  11.     $hidden_field_name = 'mt_submit_hidden';
  12.     $data_field_name   = 'mt_favorite_color';
  14.     // Read in existing option value from database
  15.     $opt_val = get_option( $opt_name );
  17.     // See if the user has posted us some information. If they did, this hidden field will be set to 'Y'.
  18.     if ( isset( $_POST[ $hidden_field_name ] ) && $_POST[ $hidden_field_name ] == 'Y' ) {
  19.         // Read their posted value.
  20.         $opt_val = $_POST[ $data_field_name ];
  22.         // Save the posted value in the database.
  23.         update_option( $opt_name, $opt_val );
  25.         // Put a "Settings updated" message on the screen
  26.         ?>
  27.         <div class="updated"></div><!-- .updated -->
  29.         <div class="wrap">
  30.             <?php echo '<h2>' . __( 'Menu Test Settings', 'menu-test' ) . '</h2>'; ?>
  31.             <form action="" method="post" name="form1"></form>
  32.             <?php _e( 'Favorite Color:', 'menu-test' ); ?>
  33.             <hr />
  34.         </div><!-- .wrap -->
  36.         <?php
  37.     }
  38. }

いくつかの注意事項:

  • add_menu_page() や add_submenu_page() のようなWordPress関数は、トップレベルまたはサブレベルメニューが表示されるかどうかを判断するために使用される権限を取ります。
  • ページの出力を処理するためにフックされた関数は、ユーザーが必要な権限を持っていることを確認する必要があります。
  • WordPressの管理関数はユーザーログインの検証を処理するため、関数内で心配する必要はありません。
  • 上記の関数例は国際化されており、詳細については WordPress開発者のためのI18n を参照してください。
  • 関数は、データ入力フォームを画面に表示する前に、入力されたデータを処理するため、新しい値がフォームに表示されます（データベースの値ではなく）。
  • これが最初に機能することを心配する必要はありません。WordPressの update_option 関数は、存在しない場合に自動的にデータベースにオプションを追加します。
  • これらの管理メニュー追加手順は、管理ページに移動するたびに解析されます。したがって、オプションページがないテーマを作成している場合でも、後で追加することができ、上記の手順を使用して再アップロードし、調整して満足するまで行うことができます。言い換えれば、メニューは「永続的に追加」されたり、テーマを有効にしたときにデータベースに入れられたりすることはありません。動的に解析されるため、メニュー項目を自由に追加または削除でき、再アップロードすると、変更がすぐに反映されます。

ページフックサフィックス

新しい管理メニューを追加するすべての関数 – add_menu_page()、add_submenu_page() およびその特殊バージョン（add_options_page() など）は、ページフックサフィックスと呼ばれる特別な値を返します。これは、特定のページでのみアクションを登録できるフックとして後で使用できます。

そのようなアクションフックの1つは load-{page_hook} で、{page_hook} はこれらの add_*_page() 関数の1つによって返される値です。このフックは、特定のページが読み込まれたときに呼び出されます。以下の例では、プラグインのオプションページを除くすべての管理ページに「テーマが構成されていません」という通知を表示するために使用されます： 

  1. <?php
  2. add_action( 'admin_menu', 'my_menu' );
  4. // Here you can check if plugin is configured (e.g. check if some option is set). If not, add new hook.
  5. // In this example hook is always added.
  6. add_action( 'admin_notices', 'my_admin_notices' );
  8. function my_menu() {
  9.     // Add the new admin menu and page and save the returned hook suffix
  10.     $hook_suffix = add_options_page( 'My Options', 'My Theme', 'manage_options', 'my-unique-identifier', 'my_options' );
  11.     // Use the hook suffix to compose the hook and register an action executed when plugin's options page is loaded
  12.     add_action( 'load-' . $hook_suffix, 'my_load_function' );
  13. }
  15. function my_load_function() {
  16.     // Current admin page is the options page for our plugin, so do not display the notice
  17.     // (remove the action responsible for this)
  18.     remove_action( 'admin_notices', 'my_admin_notices' );
  19. }
  21. function my_admin_notices() {
  22.     echo '<pre><div class="updated fade" id="notice">My Plugin is not configured yet. Please do it now.</div></pre>';
  23. }
  25. function my_options() {
  26.     if ( ! current_user_can( 'manage_options' ) ) {
  27.         wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
  28.     }
  30.     echo '</pre><div class="wrap">';
  31.     echo 'Here is where the form would go if I actually had options.';
  32.     echo '</div><pre>';
  33. }

リソース

トップレベルメニューに関するwp-hackersの議論管理メニューエディタープラグイン