当サイト、Codex 日本語版は今後積極的な更新は行わない予定です。後継となる新ユーザーマニュアルは、https://ja.wordpress.org/support/ にあります。
万が一、当サイトで重大な問題を発見した際などは、フォーラムWordSlack #docs チャンネルでお知らせください。</p>

「管理メニューの追加」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(ページの挿入)
(最新英語版を反映 en:Adding Administration Menus 22:02, 7 February 2016‎ Atachibana版)
8行目: 8行目:
  
 
この記事では、プラグインがWordPressにカスタム管理画面を追加する方法について説明します。すでに[[プラグインの作成]]とアクション・フィルターという[[プラグイン API]]の基本的な部分は理解している読者を想定しています。
 
この記事では、プラグインがWordPressにカスタム管理画面を追加する方法について説明します。すでに[[プラグインの作成]]とアクション・フィルターという[[プラグイン API]]の基本的な部分は理解している読者を想定しています。
 +
 +
Usually, plugin and theme authors need to provide access to a settings (options) screen so users can customize how the plugin or theme is used. The best way to present the user with such a screen is to create an administration menu item that allows the user to access that settings screen from all the [[Administration Screens]]. This article explains how plugin authors can add administration menus and screens. Note: the following information assumes a knowledge of the basics of [[Writing a Plugin]] and using the [[Plugin API]] of Actions and Filters.
  
 
== 関数リファレンス ==
 
== 関数リファレンス ==
55行目: 57行目:
 
#メニューを作成するコードを含んだ関数を作る
 
#メニューを作成するコードを含んだ関数を作る
 
#"admin_menu"フックに上で作った関数を登録する
 
#"admin_menu"フックに上で作った関数を登録する
 +
# Register the above function using the [[Plugin_API/Action_Reference/admin_menu|admin_menu]] action hook. (If you are adding an admin menu for the [[Create A Network|Network]], use [[Plugin_API/Action_Reference/network_admin_menu|network_admin_menu]] instead).
 
#メニューがクリックされたときに表示されるページのHTML出力を作る
 
#メニューがクリックされたときに表示されるページのHTML出力を作る
 
コードはプラグインの主要なPHPファイルに含まれるか、別のPHPからインクルードされなくてはいけません。
 
  
 
二番目のステップは、新米プラグイン開発者には見過ごされがちです。次に述べるメニュー作成コードを単に呼び出すだけではいけません;あなたはそれを'''関数の中'''に入れ、それから関数を登録するのです。
 
二番目のステップは、新米プラグイン開発者には見過ごされがちです。次に述べるメニュー作成コードを単に呼び出すだけではいけません;あなたはそれを'''関数の中'''に入れ、それから関数を登録するのです。
  
 
上記の三ステップを簡単な例にしてみましょう:
 
上記の三ステップを簡単な例にしてみましょう:
 +
Here is a very simple example of the three steps just described.  This plugin will add a sub-level menu item under the Settings top-level menu, and when selected, that menu item will cause a very basic screen to display.  Note: this code should be added to a [[Writing a Plugin#Plugin_Files|main plugin PHP file]] or a separate PHP include file.
 +
 
<pre>
 
<pre>
 
<?php
 
<?php
85行目: 88行目:
  
 
ご覧のように、管理画面に新しいアイテムを追加する<tt>my_plugin_menu</tt>関数がありますよね(次節で述べる<tt>add_options_page</tt>関数を使えば、もっと複雑な複数のメニューアイテムを追加できます。もうちょっと読んでみましょう)。それでは、この関数を"登録"するためのWordPressフックを呼び出しましょう。''これを行わないと、プラグインを有効化しようとしたときに"undefined function"というPHPエラーが投げられます。''最後に、ユーザがクリックしたときに表示されるページ(と、処理されるPHPコード)を含む関数を作りましょう。
 
ご覧のように、管理画面に新しいアイテムを追加する<tt>my_plugin_menu</tt>関数がありますよね(次節で述べる<tt>add_options_page</tt>関数を使えば、もっと複雑な複数のメニューアイテムを追加できます。もうちょっと読んでみましょう)。それでは、この関数を"登録"するためのWordPressフックを呼び出しましょう。''これを行わないと、プラグインを有効化しようとしたときに"undefined function"というPHPエラーが投げられます。''最後に、ユーザがクリックしたときに表示されるページ(と、処理されるPHPコード)を含む関数を作りましょう。
 +
In this example, the function <tt>my_plugin_menu()</tt> adds a new item to the ''Settings'' administration menu via the <tt>[[Function_Reference/add_options_page|add_options_page()]]</tt> function.  Note: more complicated multiple menu items can be added, but that will be described later. Notice the <tt>[[Function_Reference/add_action|add_action()]]</tt> call in ''Step 2'' that ''registers'' the <tt>my_plugin_menu()</tt> function under the [[Plugin_API/Action_Reference/admin_menu|admin_menu]] hook. '''Without that <tt>add_action()</tt> call, a PHP error for ''undefined function'' will be thrown when attempting to activate the plugin.''' Finally, the <tt>add_options_page()</tt> call refers to the <tt>my_plugin_options()</tt> function which contains the actual page to be displayed (and PHP code to be processed) when someone clicks the menu item. 
  
 
終わりの二つのステップの具体的な処理内容は、これから説明します。コードを関数の中に入れ、すべての処理を開始するために<tt>admin_menu</tt>フックを呼び出す、ということだけは忘れないでください!
 
終わりの二つのステップの具体的な処理内容は、これから説明します。コードを関数の中に入れ、すべての処理を開始するために<tt>admin_menu</tt>フックを呼び出す、ということだけは忘れないでください!
 +
These processes are described in more detail in the sections below. Remember to enclose the creation of the menu and the page in functions, and use the ''admin_menu'' [[Plugin_API#Current_Hooks_For_Actions|hook]] to get the whole process started at the right time!
 +
  
== メニューとサブメニュー ==
+
== Determining Location for New Menus ==
  
 
カスタムの管理画面を作る前に、WordPressの管理メニューのどこにそれが属するのかを指定しなくてはいけません。ほとんどのプラグインはWordPressの既存トップレベルメニュー下にサブメニューとして登録されます。
 
カスタムの管理画面を作る前に、WordPressの管理メニューのどこにそれが属するのかを指定しなくてはいけません。ほとんどのプラグインはWordPressの既存トップレベルメニュー下にサブメニューとして登録されます。
101行目: 107行目:
  
 
以下はそれぞれのトップレベルメニューの属性です:
 
以下はそれぞれのトップレベルメニューの属性です:
 +
Use this guide of the WordPress top-level menus to determine the correct location for your sub-level menu item:
  
 
;[[Dashboard_SubPanel|ダッシュボード]] : WordPressのコア、プラグイン、およびテーマを更新するための更新オプションなどの情報が中心に集められています。
 
;[[Dashboard_SubPanel|ダッシュボード]] : WordPressのコア、プラグイン、およびテーマを更新するための更新オプションなどの情報が中心に集められています。
113行目: 120行目:
 
;[[管理パネル#Settings|設定]] : Displays plugin options that only administrators should view (also see [[Creating_Options_Pages|Creating Settings Pages]]).
 
;[[管理パネル#Settings|設定]] : Displays plugin options that only administrators should view (also see [[Creating_Options_Pages|Creating Settings Pages]]).
 
;ネットワーク管理者 : Displays plugin options that are set on the Network. Instead of "admin_menu", you should use "network_admin_menu" (see also [[Create A Network]])
 
;ネットワーク管理者 : Displays plugin options that are set on the Network. Instead of "admin_menu", you should use "network_admin_menu" (see also [[Create A Network]])
 
 
<!--旧版
 
;[[管理パネル#Settings|設定]]:プラグイン設定を表示し、管理者だけに見える([[Creating_Options_Pages|設定ページを作る]]も参考のこと)。
 
;[[管理パネル#Manage_-_Change_your_content|管理]]:リンク、投稿、カテゴリー、画像などの管理ページを表示する。〔訳注:トップレベルメニュー「管理」はバージョン2.7より廃止されました〕
 
;[[管理パネル#Plugins|プラグイン]]:プラグインの初期設定以外を行う管理画面を表示する。
 
;[[管理パネル#Appearance|外観]]:テーマやサイドバーなどを編集する管理画面を表示。
 
;[[管理パネル#Posts|投稿]]:コンテンツ(投稿やページ)を書くための管理画面を表示。
 
;[[管理パネル#Users|ユーザ]]:ユーザ管理画面を表示。
 
-->
 
  
 
== admin_menu 関数 ==
 
== admin_menu 関数 ==
  
 
どこにメニュー・サブメニューを追加するのかを決定したら、次はWordPressに対して新しいページのことを知らせましょう。これはすべて<tt>'admin_menu'</tt>アクションに登録した関数の中に入れてください(この節の最後にある例を参照のこと)
 
どこにメニュー・サブメニューを追加するのかを決定したら、次はWordPressに対して新しいページのことを知らせましょう。これはすべて<tt>'admin_menu'</tt>アクションに登録した関数の中に入れてください(この節の最後にある例を参照のこと)
 +
A working example is presented at the end of this section.
  
 
=== トップレベルメニュー ===
 
=== トップレベルメニュー ===
133行目: 131行目:
  
 
新しいトップレベルメニューを追加するには、<tt>add_menu_page</tt>関数を使います:
 
新しいトップレベルメニューを追加するには、<tt>add_menu_page</tt>関数を使います:
 +
If you have decided your plugin requires a brand-new top-level menu, the first thing you'll need to do is to create one with the <tt>[[Function_Reference/add_menu_page|add_menu_page]]</tt> function.  Note: skip to [[#Sub-Level_Menus|Sub-Menus]] if you don't need a top-level menu.
  
 
  <?php add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position ); ?>
 
  <?php add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position ); ?>
  
 
パラメータ:
 
パラメータ:
;page_title:メニューが有効になった時に表示されるHTMLのページタイトル用テキスト。
+
;page_title:メニューが有効になった時に表示されるHTMLのページタイトル用テキスト。;page_title : The text to be displayed in the title tags of the page when the menu is selected.
 +
 
 
;menu_title:管理画面のメニュー上での表示名。
 
;menu_title:管理画面のメニュー上での表示名。
 
;access_level/capability:このメニューページを閲覧・使用するために最低限必要な[[ユーザーレベル]]または[[ユーザーの種類と権限]] 。
 
;access_level/capability:このメニューページを閲覧・使用するために最低限必要な[[ユーザーレベル]]または[[ユーザーの種類と権限]] 。
;file:メニューページのコンテンツを表示するPHPファイル。
+
;capability : The [[Roles and Capabilities|capability]] required for this menu to be displayed to the user. When using the Settings API to handle your form, you should use 'manage_options' here as the user won't be able to save options without it. [[User Levels|User levels]] are deprecated and should not be used here!
 +
 
 +
;menu_slug: The slug name to refer to this menu by (should be unique for this menu). Prior to [[Version 3.0]] this was called the file (or handle) parameter.  If the function parameter is omitted, the menu_slug should be the PHP file that handles the display of the menu page content.
 +
 
 
;function: メニューページにコンテンツを表示する関数。
 
;function: メニューページにコンテンツを表示する関数。
  
 
技術的に言うと''function''パラメータはオプションですが、指定されていない場合、WordPressは基本的にインクルードされたPHPファイルが管理画面を出力するものと仮定し、関数を呼び出しません。ほとんどのプラグイン作者はページ生成コードを持つ関数をメインのプラグインファイル内に書いています。
 
技術的に言うと''function''パラメータはオプションですが、指定されていない場合、WordPressは基本的にインクルードされたPHPファイルが管理画面を出力するものと仮定し、関数を呼び出しません。ほとんどのプラグイン作者はページ生成コードを持つ関数をメインのプラグインファイル内に書いています。
 +
;function: The function that displays the page content for the menu page. Technically, the ''function'' parameter is optional, but if it is not supplied, then WordPress will basically assume that including the PHP file will generate the administration screen, without calling a function. The page-generating code can be written in a function within the main plugin file.  In the event that the ''function'' parameter is specified, it is possible to use any string for the ''file'' parameter. This allows usage of pages such as ''?page=my_super_plugin_page'' instead of ''?page=my-super-plugin/admin-options.php''.
 +
 +
:The function must be referenced in one of two ways:
 +
:# if the function is a member of a class within the plugin it should be referenced as <tt>array( $this, 'function_name' )</tt>
 +
:# in all other cases, using the function name itself is sufficient
  
 
;icon_url:これはWordPress 2.7においてのみ有効です。メニューにカスタムアイコンを追加します。
 
;icon_url:これはWordPress 2.7においてのみ有効です。メニューにカスタムアイコンを追加します。
 +
;icon_url: The url to the icon to be used for this menu.  This parameter is optional.
 +
 
;position: The position in the menu order this menu should appear.  By default, if this parameter is omitted, the menu will appear at the bottom of the menu structure. To see the current menu positions, use <tt>print_r($GLOBALS['menu'])</tt> after the menu has loaded.
 
;position: The position in the menu order this menu should appear.  By default, if this parameter is omitted, the menu will appear at the bottom of the menu structure. To see the current menu positions, use <tt>print_r($GLOBALS['menu'])</tt> after the menu has loaded.
  
=== サブメニュー ===
+
=== Sub-Level Menus ===
  
 
トップレベルメニューを決定するか、既存のWordPressトップレベルメニューを使うことを選んだら、<tt>add_submenu_page</tt>関数を使ってサブメニューを定義する準備ができました。表示したい順番に追加していくようにしてください。
 
トップレベルメニューを決定するか、既存のWordPressトップレベルメニューを使うことを選んだら、<tt>add_submenu_page</tt>関数を使ってサブメニューを定義する準備ができました。表示したい順番に追加していくようにしてください。
 +
Once your top-level menu is defined, or you have chosen to use an existing WordPress top-level menu, you are ready to define one or more sub-level menu items using the <tt>add_submenu_page</tt> function. Make sure to add the sub-level menu items in the order you want them displayed.
 +
 +
==== Using add_submenu_page ====
  
 
<pre>
 
<pre>
add_submenu_page(''parent'', ''page_title'', ''menu_title'', ''access_level/capability'', ''file'', ''[function]'');
+
<?php add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function); ?>
 
</pre>
 
</pre>
  
 
パラメータ:
 
パラメータ:
 
;parent:サブメニューを挿入したいトップレベルメニューを提供するWordPressのコアadminファイル名。プラグインがトップレベルメニューをなしている場合は、そのプラグインファイル。
 
;parent:サブメニューを挿入したいトップレベルメニューを提供するWordPressのコアadminファイル名。プラグインがトップレベルメニューをなしている場合は、そのプラグインファイル。
 +
Parameter values:
 +
;parent_slug : The slug name for the parent menu, or the file name of a standard WordPress admin file that supplies the top-level menu in which you want to insert your submenu, or your plugin file if this submenu is going into a custom top-level menu.
 +
 
よくある例:
 
よくある例:
 
#''投稿''用: add_submenu_page('post-new.php',...)
 
#''投稿''用: add_submenu_page('post-new.php',...)
166行目: 182行目:
 
#''プラグイン''用: add_submenu_page('plugins.php',...)
 
#''プラグイン''用: add_submenu_page('plugins.php',...)
 
#''ユーザ''用: add_submenu_page('users.php',...)
 
#''ユーザ''用: add_submenu_page('users.php',...)
 +
:Examples:
 +
:#For ''Dashboard'': add_submenu_page('index.php',...)
 +
:#For ''Posts'': add_submenu_page('edit.php',...)
 +
:#For ''Media'': add_submenu_page('upload.php',...)
 +
:#For ''Links'': add_submenu_page('link-manager.php',...)
 +
:#For ''Pages'': add_submenu_page('edit.php?post_type=page',...)
 +
:#For ''Comments'': add_submenu_page('edit-comments.php',...)
 +
:#For ''Custom Post Types'': add_submenu_page('edit.php?post_type=your_post_type',...)
 +
:#For ''Appearance'': add_submenu_page('themes.php',...)
 +
:#For ''Plugins'': add_submenu_page('plugins.php',...)
 +
:#For ''Users'': add_submenu_page('users.php',...)
 +
:#For ''Tools'': add_submenu_page('tools.php',...)
 +
:#For ''Settings'': add_submenu_page('options-general.php',...)
 +
 
;page_title:サブメニューがクリックされたときにHTMLページタイトルになるテキスト。
 
;page_title:サブメニューがクリックされたときにHTMLページタイトルになるテキスト。
 
;menu_title:サブメニューの管理画面上での名前。
 
;menu_title:サブメニューの管理画面上での名前。
 +
;menu_title : The text to be displayed in the title tags of the page when the menu is selected.
 +
 
;access_level/capability:このメニューページを閲覧・使用するために最低限必要な[[ユーザーレベル]]または[[ユーザーの種類と権限]] 。
 
;access_level/capability:このメニューページを閲覧・使用するために最低限必要な[[ユーザーレベル]]または[[ユーザーの種類と権限]] 。
 +
;capability : The [[Roles and Capabilities|capability]] required for this menu to be displayed to the user.  [[User Levels|User levels]] are deprecated and should not be used here!
 +
 
;file:既存のWordPressメニュー用には、メニューページのコンテンツを表示するPHPファイル。カスタムのトップレベルメニュー下においては、'''ユニーク'''なこのサブメニューページの識別子。
 
;file:既存のWordPressメニュー用には、メニューページのコンテンツを表示するPHPファイル。カスタムのトップレベルメニュー下においては、'''ユニーク'''なこのサブメニューページの識別子。
 
''プラグインがトップレベルメニューを持つ場合、最初のサブメニューはトップレベルメニューと同じ名前を持ち、従ってリンクは複製されます。リンクの複製を避けるには、はじめにadd_submenu_page関数を呼び出し、parentとfileパラメータを同じ名前にします。''
 
''プラグインがトップレベルメニューを持つ場合、最初のサブメニューはトップレベルメニューと同じ名前を持ち、従ってリンクは複製されます。リンクの複製を避けるには、はじめにadd_submenu_page関数を呼び出し、parentとfileパラメータを同じ名前にします。''
 +
;menu_slug : For existing WordPress menus, the PHP file that handles the display of the menu page content. For submenus of a custom top-level menu, a '''unique''' identifier for this sub-menu page.
 +
 +
:''In situations where a plugin is creating its own top-level menu, the first submenu will normally have the same link title as the top-level menu and hence the link will be duplicated. The duplicate link title can be avoided by calling the add_submenu_page function the first time with the parent_slug and menu_slug parameters being given the same value.
 +
''
 
;function: メニューページのコンテンツを出力する関数。
 
;function: メニューページのコンテンツを出力する関数。
  
 
<tt>add_menu_page</tt>関数と同じく、技術的に言うと''function''パラメータはオプションですが、指定されていない場合、WordPressは基本的にインクルードされたPHPファイルが管理画面を出力するものと仮定し、関数を呼び出しません。ほとんどのプラグイン作者はページ生成コードを持つ関数をメインのプラグインファイル内に書いています。
 
<tt>add_menu_page</tt>関数と同じく、技術的に言うと''function''パラメータはオプションですが、指定されていない場合、WordPressは基本的にインクルードされたPHPファイルが管理画面を出力するものと仮定し、関数を呼び出しません。ほとんどのプラグイン作者はページ生成コードを持つ関数をメインのプラグインファイル内に書いています。
 +
:Technically, as in the <tt>add_menu_page</tt> function, the ''function'' parameter is optional, but if it is not supplied, then WordPress will basically assume that including the PHP file will generate the administration screen, without calling a function. Most plugin authors choose to put the page-generating code in a function within their main plugin file.
 +
 +
:In the event that the ''function'' parameter is specified, It's possible to use any string for the ''file'' parameter. This allows usage of pages such as ''?page=my_super_plugin_page'' instead of ''?page=my-super-plugin/admin-options.php''.
 +
 +
: See the [http://codex.wordpress.org/Adding_Administration_Menus#Top-Level_Menus Top-Level Menus] for notes about how to reference class members as function parameters.
 +
 +
===== 例 =====
  
 
以下はトップレベルメニューページとサブメニューページを挿入する簡単な例です。サブメニューのタイトルはトップレベルページと異なるものになっています。この例では、'my_magic_function'が最初のサブメニューページを表示する関数になります:
 
以下はトップレベルメニューページとサブメニューページを挿入する簡単な例です。サブメニューのタイトルはトップレベルページと異なるものになっています。この例では、'my_magic_function'が最初のサブメニューページを表示する関数になります:
 +
 
<pre>
 
<pre>
add_menu_page('Page title', 'Top-level menu title', 8, __FILE__, 'my_magic_function');
+
<?php
add_submenu_page(__FILE__, 'Page title', 'Sub-menu title', 8, __FILE__, 'my_magic_function');
+
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');
 +
?>
 
</pre>
 
</pre>
  
195行目: 243行目:
 
  add_theme_page( ''page_title'', ''menu_title'', ''access_level/capability'', ''file'', ''[function]'');
 
  add_theme_page( ''page_title'', ''menu_title'', ''access_level/capability'', ''file'', ''[function]'');
 
</pre>
 
</pre>
 
===== 例 =====
 
 
Here's a quick example illustrating how to insert a top-level menu page and a sub-menu page, where the title on the sub-menu page is different from the top-level page. In this example, 'my_magic_function' is the name of the function that displays the first sub-menu page:
 
 
<?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');
 
?>
 
  
 
Here's an example of adding an option page under a '''custom post type''' menu block ([http://www.billrobbinsdesign.com/custom-post-type-admin-page/ see also here]):
 
Here's an example of adding an option page under a '''custom post type''' menu block ([http://www.billrobbinsdesign.com/custom-post-type-admin-page/ see also here]):
  
 
  <?php add_submenu_page('edit.php?post_type=wiki', 'Options', 'Options', 'manage_options', 'wiki-options', array(&$this, 'options_page') ); ?>
 
  <?php add_submenu_page('edit.php?post_type=wiki', 'Options', 'Options', 'manage_options', 'wiki-options', array(&$this, 'options_page') ); ?>
 
  
 
==== ラッパー関数を用いる ====
 
==== ラッパー関数を用いる ====
306行目: 344行目:
 
function mt_sublevel_page2() {
 
function mt_sublevel_page2() {
 
     echo "<h2>Test Sublevel 2</h2>";
 
     echo "<h2>Test Sublevel 2</h2>";
 +
}
 +
 +
?>
 +
</pre>
 +
 +
<pre>
 +
<?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
 +
*/
 +
 +
// Hook for adding admin menus
 +
add_action('admin_menu', 'mt_add_pages');
 +
 +
// action function for above hook
 +
function mt_add_pages() {
 +
    // Add a new submenu under Settings:
 +
    add_options_page(__('Test Settings','menu-test'), __('Test Settings','menu-test'), 'manage_options', 'testsettings', 'mt_settings_page');
 +
 +
    // Add a new submenu under Tools:
 +
    add_management_page( __('Test Tools','menu-test'), __('Test Tools','menu-test'), 'manage_options', 'testtools', 'mt_tools_page');
 +
 +
    // Add a new top-level menu (ill-advised):
 +
    add_menu_page(__('Test Toplevel','menu-test'), __('Test Toplevel','menu-test'), 'manage_options', 'mt-top-level-handle', 'mt_toplevel_page' );
 +
 +
    // Add a submenu to the custom top-level menu:
 +
    add_submenu_page('mt-top-level-handle', __('Test Sublevel','menu-test'), __('Test Sublevel','menu-test'), 'manage_options', 'sub-page', 'mt_sublevel_page');
 +
 +
    // Add a second submenu to the custom top-level menu:
 +
    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() displays the page content for the Test settings submenu
 +
function mt_settings_page() {
 +
    echo "<h2>" . __( 'Test Settings', 'menu-test' ) . "</h2>";
 +
}
 +
 +
// mt_tools_page() displays the page content for the Test Tools submenu
 +
function mt_tools_page() {
 +
    echo "<h2>" . __( 'Test Tools', 'menu-test' ) . "</h2>";
 +
}
 +
 +
// mt_toplevel_page() displays the page content for the custom Test Toplevel menu
 +
function mt_toplevel_page() {
 +
    echo "<h2>" . __( 'Test Toplevel', 'menu-test' ) . "</h2>";
 +
}
 +
 +
// mt_sublevel_page() displays the page content for the first submenu
 +
// of the custom Test Toplevel menu
 +
function mt_sublevel_page() {
 +
    echo "<h2>" . __( 'Test Sublevel', 'menu-test' ) . "</h2>";
 +
}
 +
 +
// mt_sublevel_page2() displays the page content for the second submenu
 +
// of the custom Test Toplevel menu
 +
function mt_sublevel_page2() {
 +
    echo "<h2>" . __( 'Test Sublevel2', 'menu-test' ) . "</h2>";
 
}
 
}
  
312行目: 411行目:
  
 
=== メニューページサンプル ===
 
=== メニューページサンプル ===
 +
 +
<strong>Note: See the [[Settings API]] for information on creating settings pages.</strong>
  
 
上記の例ではいくつかのダミー関数を含んでいます。<tt>mt_options_page</tt>のような、実際のページコンテンツのプレース・ホルダーです。これを本物のメニューページに変更しましょう。それでは、我々のプラグインはmt_favorite_foodというオプションを持っており、サイトオーナーがプラグインのオプションページに好きな食べ物を記入できるようにしたいと仮定しましょう。<tt>mt_options_page</tt>関数がこれを実現するためには、管理画面上にデータ入力フォームがあり、入力されたデータを処理しなくてはいけません。以下がこれを実現する関数の例です:
 
上記の例ではいくつかのダミー関数を含んでいます。<tt>mt_options_page</tt>のような、実際のページコンテンツのプレース・ホルダーです。これを本物のメニューページに変更しましょう。それでは、我々のプラグインはmt_favorite_foodというオプションを持っており、サイトオーナーがプラグインのオプションページに好きな食べ物を記入できるようにしたいと仮定しましょう。<tt>mt_options_page</tt>関数がこれを実現するためには、管理画面上にデータ入力フォームがあり、入力されたデータを処理しなくてはいけません。以下がこれを実現する関数の例です:
 +
The example above contains several dummy functions, such as <tt>mt_settings_page</tt>, as placeholders for actual page content. We need to turn them into real menu pages. So, let's assume that our plugin has an option called mt_favorite_color, and that we want to allow the site owner to type in his/her favorite color via a Settings page. The <tt>mt_options_page</tt> function will need to put a data entry form on the screen to enable this, and also process the entered data. Here is a function that does this:
  
 
<pre>
 
<pre>
375行目: 477行目:
 
}
 
}
 
</pre>
 
</pre>
 +
 +
<pre>
 +
 +
// mt_settings_page() displays the page content for the Test settings submenu
 +
function mt_settings_page() {
 +
 +
    //must check that the user has the required capability
 +
    if (!current_user_can('manage_options'))
 +
    {
 +
      wp_die( __('You do not have sufficient permissions to access this page.') );
 +
    }
 +
 +
    // variables for the field and option names
 +
    $opt_name = 'mt_favorite_color';
 +
    $hidden_field_name = 'mt_submit_hidden';
 +
    $data_field_name = 'mt_favorite_color';
 +
 +
    // Read in existing option value from database
 +
    $opt_val = get_option( $opt_name );
 +
 +
    // See if the user has posted us some information
 +
    // If they did, this hidden field will be set to 'Y'
 +
    if( isset($_POST[ $hidden_field_name ]) && $_POST[ $hidden_field_name ] == 'Y' ) {
 +
        // Read their posted value
 +
        $opt_val = $_POST[ $data_field_name ];
 +
 +
        // Save the posted value in the database
 +
        update_option( $opt_name, $opt_val );
 +
 +
        // Put a "settings saved" message on the screen
 +
 +
?>
 +
<div class="updated"><p><strong><?php _e('settings saved.', 'menu-test' ); ?></strong></p></div>
 +
<?php
 +
 +
    }
 +
 +
    // Now display the settings editing screen
 +
 +
    echo '<div class="wrap">';
 +
 +
    // header
 +
 +
    echo "<h2>" . __( 'Menu Test Plugin Settings', 'menu-test' ) . "</h2>";
 +
 +
    // settings form
 +
   
 +
    ?>
 +
 +
<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
 +
 +
}
 +
</pre>
 +
  
 
注意点:
 
注意点:
 
* WordPressの管理機能はユーザ認証に対する注意を十分に払っているので、その点を心配する必要はありません。
 
* WordPressの管理機能はユーザ認証に対する注意を十分に払っているので、その点を心配する必要はありません。
 +
* The WordPress functions such as <tt>add_menu_page</tt> and <tt>add_submenu_page</tt> take a capability which will be used to determine whether the top-level or sub-level menu is displayed.
 +
* The function which is hooked in to handle the output of the page must check that the user has the required capability as well.
 +
* The WordPress administration functions take care of validating the user login, so you don't have to worry about it in your function.
 +
 
* 上記の例に挙げた関数は多言語化されています。詳しくは [[プラグインの作成#プラグインの多言語化|プラグインの多言語化]]を参照のこと。
 
* 上記の例に挙げた関数は多言語化されています。詳しくは [[プラグインの作成#プラグインの多言語化|プラグインの多言語化]]を参照のこと。
 
* 関数は入力されたデータが画面の入力フォームに表示されるよりも前に処理するので、フォーム内の値は(データベースの中よりも)新しいものになります。
 
* 関数は入力されたデータが画面の入力フォームに表示されるよりも前に処理するので、フォーム内の値は(データベースの中よりも)新しいものになります。
427行目: 601行目:
  
 
==関連情報==
 
==関連情報==
*[http://comox.textdrive.com/pipermail/wp-hackers/2009-February/024632.html Top Level Menu discussion on wp-hackers]
+
* [http://wordpress.org/plugins/admin-menu-editor/ Admin Menu Editor Plugin] - allows adding, deleting, hiding, and re-ordering of administration items
 +
 
  
{{原文|Adding Administration Menus|67603}}<!-- 15:04, February 20, 2009 Ronnie268 版 -->
+
{{原文|Adding Administration Menus|155575}}<!-- 22:02, 7 February 2016‎ Atachibana版 -->
  
 
{{DEFAULTSORT:かんりめにゆうのついか}}
 
{{DEFAULTSORT:かんりめにゆうのついか}}
437行目: 612行目:
  
 
[[en:Adding Administration Menus]]
 
[[en:Adding Administration Menus]]
 +
[[ja:管理メニューの追加]]
 
[[ru:Добавление административных меню]]
 
[[ru:Добавление административных меню]]
 +
[[zh-cn:Adding Administration Menus]]

2016年2月7日 (日) 22:05時点における版

このページ「管理メニューの追加」は情報が古くなっている可能性があります。最新版英語)も合わせてご覧ください。翻訳にご協力くださる方はぜひご相談ください

このページ「管理メニューの追加」は一部未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

(注: ユーザーレベルは 3.0 以降非推奨。原文は更新されている。--Mizuno 2011年7月23日 (土) 03:29 (UTC))

はじめに

多くのプラグインはユーザに設定項目を提供することで、プラグインの使用法をカスタマイズできるようにしています。プラグイン作者として、あなたにはいくつかのセットアップ方法があります。一つはプラグインのPHPファイルをユーザに編集させることです。しかし、これは多くのユーザにとって、不愉快です(控えめに言って、ですよ)。したがって、通常考えられるもっと良い方法というのは、ユーザがやり慣れた方法で設定を編集できる管理画面を用意することです。

この記事では、プラグインがWordPressにカスタム管理画面を追加する方法について説明します。すでにプラグインの作成とアクション・フィルターというプラグイン APIの基本的な部分は理解している読者を想定しています。

Usually, plugin and theme authors need to provide access to a settings (options) screen so users can customize how the plugin or theme is used. The best way to present the user with such a screen is to create an administration menu item that allows the user to access that settings screen from all the Administration Screens. This article explains how plugin authors can add administration menus and screens. Note: the following information assumes a knowledge of the basics of Writing a Plugin and using the Plugin API of Actions and Filters.

関数リファレンス

全般的な関数

メニュー

サブメニュー

WordPress 管理メニュー

どんな文脈でもHookが必要

管理メニューを作るには、次の三つを行う必要があります:

  1. メニューを作成するコードを含んだ関数を作る
  2. "admin_menu"フックに上で作った関数を登録する
  3. Register the above function using the admin_menu action hook. (If you are adding an admin menu for the Network, use network_admin_menu instead).
  4. メニューがクリックされたときに表示されるページのHTML出力を作る

二番目のステップは、新米プラグイン開発者には見過ごされがちです。次に述べるメニュー作成コードを単に呼び出すだけではいけません;あなたはそれを関数の中に入れ、それから関数を登録するのです。

上記の三ステップを簡単な例にしてみましょう: Here is a very simple example of the three steps just described. This plugin will add a sub-level menu item under the Settings top-level menu, and when selected, that menu item will cause a very basic screen to display. Note: this code should be added to a main plugin PHP file or a separate PHP include file.

<?php
/** Step 2 (from text above). */
add_action( 'admin_menu', 'my_plugin_menu' );

/** Step 1. */
function my_plugin_menu() {
	add_options_page( 'My Plugin Options', 'My Plugin', 'manage_options', 'my-unique-identifier', 'my_plugin_options' );
}

/** Step 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>Here is where the form would go if I actually had options.</p>';
	echo '</div>';
}
?>

ご覧のように、管理画面に新しいアイテムを追加するmy_plugin_menu関数がありますよね(次節で述べるadd_options_page関数を使えば、もっと複雑な複数のメニューアイテムを追加できます。もうちょっと読んでみましょう)。それでは、この関数を"登録"するためのWordPressフックを呼び出しましょう。これを行わないと、プラグインを有効化しようとしたときに"undefined function"というPHPエラーが投げられます。最後に、ユーザがクリックしたときに表示されるページ(と、処理されるPHPコード)を含む関数を作りましょう。 In this example, the function my_plugin_menu() adds a new item to the Settings administration menu via the add_options_page() function. Note: more complicated multiple menu items can be added, but that will be described later. Notice the add_action() call in Step 2 that registers the my_plugin_menu() function under the admin_menu hook. Without that add_action() call, a PHP error for undefined function will be thrown when attempting to activate the plugin. Finally, the add_options_page() call refers to the my_plugin_options() function which contains the actual page to be displayed (and PHP code to be processed) when someone clicks the menu item.

終わりの二つのステップの具体的な処理内容は、これから説明します。コードを関数の中に入れ、すべての処理を開始するためにadmin_menuフックを呼び出す、ということだけは忘れないでください! These processes are described in more detail in the sections below. Remember to enclose the creation of the menu and the page in functions, and use the admin_menu hook to get the whole process started at the right time!


Determining Location for New Menus

カスタムの管理画面を作る前に、WordPressの管理メニューのどこにそれが属するのかを指定しなくてはいけません。ほとんどのプラグインはWordPressの既存トップレベルメニュー下にサブメニューとして登録されます。

Before creating a new menu, first decide if the menu should be a top-level menu, or a sub-level menu item. A top-level menu displays as new section in the administration menus and contains sub-level menu items. A sub-level menu means the menu item is a member of an existing menu.

It is rare that a plugin would require the creation of a top-level menu. If the plugin introduces an entirely new concept or feature to WordPress, and needs many screens to do it, then that plugin may warrant a new top-level menu. Adding a top-level menu should only be considered if you really need multiple, related screens to make WordPress do something it was not originally designed to accomplish. Examples of new top-level menus might include job management or conference management. Please note with the native post type registration, WordPress automatically creates top-level menus to manage those features.

If the creation of a top-level menu is not necessary, decide under what top-level menu to place your sub-level menu item. As a point of reference, most plugins add sub-level menu items underneath existing WordPress top-level menus. For example, the Backup plugin adds a sub-level menu option to the Tools top-level menu. Please note with the taxonomy registration, WordPress automatically creates sub-level menus under the applicable top-level menu to manage those features.

もしあなたの作ったプラグインがWordPressにとってまったく新しい機能を提供するならば、たくさんの管理画面が必要でしょう。あなたのプラグイン用に新しいトップレベルメニューを作るという道もあります。WordPressにまったく独自の新しいことを行わせるために複数の連携した管理画面が必要だというときだけ、この方法をとるようにしてください。たとえば、画像ギャラリーの管理、データベース管理、コメント管理などです。

以下はそれぞれのトップレベルメニューの属性です: Use this guide of the WordPress top-level menus to determine the correct location for your sub-level menu item:

ダッシュボード 
WordPressのコア、プラグイン、およびテーマを更新するための更新オプションなどの情報が中心に集められています。
投稿 
投稿を書くための管理画面を表示。(time oriented content).
メディア 
画像、動画、オーディオのアップロードと管理画面を表示する。
固定ページ 
静的コンテンツと呼ばれるページを書くためののツールを表示します。
コメント 
Controlling and regulation reader to responses to posts.
外観
テーマやサイドバーなどを編集する管理画面を表示する。
プラグイン
プラグインの初期設定以外を行う管理画面を表示する。
ユーザー
ユーザ管理画面を表示。
ツール 
エクスポート、インポート、ブログデータのバックアップの管理画面。
設定 
Displays plugin options that only administrators should view (also see Creating Settings Pages).
ネットワーク管理者 
Displays plugin options that are set on the Network. Instead of "admin_menu", you should use "network_admin_menu" (see also Create A Network)

admin_menu 関数

どこにメニュー・サブメニューを追加するのかを決定したら、次はWordPressに対して新しいページのことを知らせましょう。これはすべて'admin_menu'アクションに登録した関数の中に入れてください(この節の最後にある例を参照のこと) A working example is presented at the end of this section.

トップレベルメニュー

なんらかの理由により、あなたの作るプラグインには新しいトップレベルメニューが必要だということになったら、あなたがまずしなくてはならないのは、それを作ることです。それが嫌ならば、下のサブメニューまで進んでください。

新しいトップレベルメニューを追加するには、add_menu_page関数を使います: If you have decided your plugin requires a brand-new top-level menu, the first thing you'll need to do is to create one with the add_menu_page function. Note: skip to Sub-Menus if you don't need a top-level menu.

<?php add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position ); ?>

パラメータ:

page_title
メニューが有効になった時に表示されるHTMLのページタイトル用テキスト。;page_title : The text to be displayed in the title tags of the page when the menu is selected.
menu_title
管理画面のメニュー上での表示名。
access_level/capability
このメニューページを閲覧・使用するために最低限必要なユーザーレベルまたはユーザーの種類と権限
capability 
The capability required for this menu to be displayed to the user. When using the Settings API to handle your form, you should use 'manage_options' here as the user won't be able to save options without it. User levels are deprecated and should not be used here!
menu_slug
The slug name to refer to this menu by (should be unique for this menu). Prior to Version 3.0 this was called the file (or handle) parameter. If the function parameter is omitted, the menu_slug should be the PHP file that handles the display of the menu page content.
function
メニューページにコンテンツを表示する関数。

技術的に言うとfunctionパラメータはオプションですが、指定されていない場合、WordPressは基本的にインクルードされたPHPファイルが管理画面を出力するものと仮定し、関数を呼び出しません。ほとんどのプラグイン作者はページ生成コードを持つ関数をメインのプラグインファイル内に書いています。

function
The function that displays the page content for the menu page. Technically, the function parameter is optional, but if it is not supplied, then WordPress will basically assume that including the PHP file will generate the administration screen, without calling a function. The page-generating code can be written in a function within the main plugin file. In the event that the function parameter is specified, it is possible to use any string for the file parameter. This allows usage of pages such as ?page=my_super_plugin_page instead of ?page=my-super-plugin/admin-options.php.
The function must be referenced in one of two ways:
  1. if the function is a member of a class within the plugin it should be referenced as array( $this, 'function_name' )
  2. in all other cases, using the function name itself is sufficient
icon_url
これはWordPress 2.7においてのみ有効です。メニューにカスタムアイコンを追加します。
icon_url
The url to the icon to be used for this menu. This parameter is optional.
position
The position in the menu order this menu should appear. By default, if this parameter is omitted, the menu will appear at the bottom of the menu structure. To see the current menu positions, use print_r($GLOBALS['menu']) after the menu has loaded.

Sub-Level Menus

トップレベルメニューを決定するか、既存のWordPressトップレベルメニューを使うことを選んだら、add_submenu_page関数を使ってサブメニューを定義する準備ができました。表示したい順番に追加していくようにしてください。 Once your top-level menu is defined, or you have chosen to use an existing WordPress top-level menu, you are ready to define one or more sub-level menu items using the add_submenu_page function. Make sure to add the sub-level menu items in the order you want them displayed.

Using add_submenu_page

<?php add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function); ?>

パラメータ:

parent
サブメニューを挿入したいトップレベルメニューを提供するWordPressのコアadminファイル名。プラグインがトップレベルメニューをなしている場合は、そのプラグインファイル。

Parameter values:

parent_slug 
The slug name for the parent menu, or the file name of a standard WordPress admin file that supplies the top-level menu in which you want to insert your submenu, or your plugin file if this submenu is going into a custom top-level menu.

よくある例:

  1. 投稿用: add_submenu_page('post-new.php',...)
  2. 管理用: add_submenu_page('edit.php',...)
  3. 外観用: add_submenu_page('themes.php',...)
  4. コメント用: add_submenu_page('edit-comments.php',...)
  5. 設定用: add_submenu_page('options-general.php',...)
  6. プラグイン用: add_submenu_page('plugins.php',...)
  7. ユーザ用: add_submenu_page('users.php',...)
Examples:
  1. For Dashboard: add_submenu_page('index.php',...)
  2. For Posts: add_submenu_page('edit.php',...)
  3. For Media: add_submenu_page('upload.php',...)
  4. For Links: add_submenu_page('link-manager.php',...)
  5. For Pages: add_submenu_page('edit.php?post_type=page',...)
  6. For Comments: add_submenu_page('edit-comments.php',...)
  7. For Custom Post Types: add_submenu_page('edit.php?post_type=your_post_type',...)
  8. For Appearance: add_submenu_page('themes.php',...)
  9. For Plugins: add_submenu_page('plugins.php',...)
  10. For Users: add_submenu_page('users.php',...)
  11. For Tools: add_submenu_page('tools.php',...)
  12. For Settings: add_submenu_page('options-general.php',...)
page_title
サブメニューがクリックされたときにHTMLページタイトルになるテキスト。
menu_title
サブメニューの管理画面上での名前。
menu_title 
The text to be displayed in the title tags of the page when the menu is selected.
access_level/capability
このメニューページを閲覧・使用するために最低限必要なユーザーレベルまたはユーザーの種類と権限
capability 
The capability required for this menu to be displayed to the user. User levels are deprecated and should not be used here!
file
既存のWordPressメニュー用には、メニューページのコンテンツを表示するPHPファイル。カスタムのトップレベルメニュー下においては、ユニークなこのサブメニューページの識別子。

プラグインがトップレベルメニューを持つ場合、最初のサブメニューはトップレベルメニューと同じ名前を持ち、従ってリンクは複製されます。リンクの複製を避けるには、はじめにadd_submenu_page関数を呼び出し、parentとfileパラメータを同じ名前にします。

menu_slug 
For existing WordPress menus, the PHP file that handles the display of the menu page content. For submenus of a custom top-level menu, a unique identifier for this sub-menu page.
In situations where a plugin is creating its own top-level menu, the first submenu will normally have the same link title as the top-level menu and hence the link will be duplicated. The duplicate link title can be avoided by calling the add_submenu_page function the first time with the parent_slug and menu_slug parameters being given the same value.

function
メニューページのコンテンツを出力する関数。

add_menu_page関数と同じく、技術的に言うとfunctionパラメータはオプションですが、指定されていない場合、WordPressは基本的にインクルードされたPHPファイルが管理画面を出力するものと仮定し、関数を呼び出しません。ほとんどのプラグイン作者はページ生成コードを持つ関数をメインのプラグインファイル内に書いています。

Technically, as in the add_menu_page function, the function parameter is optional, but if it is not supplied, then WordPress will basically assume that including the PHP file will generate the administration screen, without calling a function. Most plugin authors choose to put the page-generating code in a function within their main plugin file.
In the event that the function parameter is specified, It's possible to use any string for the file parameter. This allows usage of pages such as ?page=my_super_plugin_page instead of ?page=my-super-plugin/admin-options.php.
See the Top-Level Menus for notes about how to reference class members as function parameters.

以下はトップレベルメニューページとサブメニューページを挿入する簡単な例です。サブメニューのタイトルはトップレベルページと異なるものになっています。この例では、'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');
?>

ほとんどのサブメニューはWordPressの設定、管理、外観メニューに加わるため、WordPressはこのメニューに簡単に追加するためのラッパー関数を三つ用意しています:

トップレベルメニュー「設定」用 (Creating Options Pagesを参照のこと)
 add_options_page(''page_title'', ''menu_title'', ''access_level/capability'', ''file'', ''[function]'');
 
トップレベルメニュー「管理」用
 add_management_page(''page_title'', ''menu_title'', ''access_level/capability'', ''file'', ''[function]'');
トップレベルメニュー「外観」用
 add_theme_page( ''page_title'', ''menu_title'', ''access_level/capability'', ''file'', ''[function]'');

Here's an example of adding an option page under a custom post type menu block (see also here):

<?php add_submenu_page('edit.php?post_type=wiki', 'Options', 'Options', 'manage_options', 'wiki-options', array(&$this, 'options_page') ); ?>

ラッパー関数を用いる

Since most sub-level menus belong under the Settings, Tools, or Appearance menus, WordPress supplies wrapper functions that make adding a sub-level menu items to those top-level menus easier. Note that the function names may not match the names seen in the admin UI as they have changed over time:

ダッシュボード

<?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); ?>

あわせて Creating Options Pages もご覧ください。

ページの挿入

以下は色々な場所に新しいメニューを挿入するWordPressプラグインの例です:

<?php
/*
Plugin Name: Menu Test
Plugin URI: http://wordpress.org
Description: Menu Test
Author: Nobody
Author URI: http://example.com
*/

// 管理メニューに追加するフック
add_action('admin_menu', 'mt_add_pages');

// 上のフックに対するaction関数
function mt_add_pages() {
    // 設定メニュー下にサブメニューを追加:
    add_options_page('Test Options', 'Test Options', 8, 'testoptions', 'mt_options_page');

    // 管理メニュー下にサブメニューを追加
    add_management_page('Test Manage', 'Test Manage', 8, 'testmanage', 'mt_manage_page');

    // 新しいトップレベルメニューを追加(分からず屋):
    add_menu_page('Test Toplevel', 'Test Toplevel', 8, __FILE__, 'mt_toplevel_page');

    // カスタムのトップレベルメニューにサブメニューを追加:
    add_submenu_page(__FILE__, 'Test Sublevel', 'Test Sublevel', 8, 'sub-page', 'mt_sublevel_page');

    // カスタムのトップレベルメニューに二つ目のサブメニューを追加:
    add_submenu_page(__FILE__, 'Test Sublevel 2', 'Test Sublevel 2', 8, 'sub-page2', 'mt_sublevel_page2');
}

// mt_options_page() はTest Optionsサブメニューのページコンテンツを表示
function mt_options_page() {
    echo "<h2>Test Options</h2>";
}

// mt_manage_page()はTest Manageサブメニューにページコンテんツを表示
function mt_manage_page() {
    echo "<h2>Test Manage</h2>";
}

// mt_toplevel_page()は カスタムのトップレベルメニューのコンテンツを表示
function mt_toplevel_page() {
    echo "<h2>Test Toplevel</h2>";
}

// mt_sublevel_page() はカスタムのトップレベルメニューの
// 最初のサブメニューのコンテンツを表示
function mt_sublevel_page() {
    echo "<h2>Test Sublevel</h2>";
}

// mt_sublevel_page2() はカスタムのトップレベルメニューの
// 二番目のサブメニューを表示
function mt_sublevel_page2() {
    echo "<h2>Test Sublevel 2</h2>";
}

?>
<?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
*/

// Hook for adding admin menus
add_action('admin_menu', 'mt_add_pages');

// action function for above hook
function mt_add_pages() {
    // Add a new submenu under Settings:
    add_options_page(__('Test Settings','menu-test'), __('Test Settings','menu-test'), 'manage_options', 'testsettings', 'mt_settings_page');

    // Add a new submenu under Tools:
    add_management_page( __('Test Tools','menu-test'), __('Test Tools','menu-test'), 'manage_options', 'testtools', 'mt_tools_page');

    // Add a new top-level menu (ill-advised):
    add_menu_page(__('Test Toplevel','menu-test'), __('Test Toplevel','menu-test'), 'manage_options', 'mt-top-level-handle', 'mt_toplevel_page' );

    // Add a submenu to the custom top-level menu:
    add_submenu_page('mt-top-level-handle', __('Test Sublevel','menu-test'), __('Test Sublevel','menu-test'), 'manage_options', 'sub-page', 'mt_sublevel_page');

    // Add a second submenu to the custom top-level menu:
    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() displays the page content for the Test settings submenu
function mt_settings_page() {
    echo "<h2>" . __( 'Test Settings', 'menu-test' ) . "</h2>";
}

// mt_tools_page() displays the page content for the Test Tools submenu
function mt_tools_page() {
    echo "<h2>" . __( 'Test Tools', 'menu-test' ) . "</h2>";
}

// mt_toplevel_page() displays the page content for the custom Test Toplevel menu
function mt_toplevel_page() {
    echo "<h2>" . __( 'Test Toplevel', 'menu-test' ) . "</h2>";
}

// mt_sublevel_page() displays the page content for the first submenu
// of the custom Test Toplevel menu
function mt_sublevel_page() {
    echo "<h2>" . __( 'Test Sublevel', 'menu-test' ) . "</h2>";
}

// mt_sublevel_page2() displays the page content for the second submenu
// of the custom Test Toplevel menu
function mt_sublevel_page2() {
    echo "<h2>" . __( 'Test Sublevel2', 'menu-test' ) . "</h2>";
}

?>

メニューページサンプル

Note: See the Settings API for information on creating settings pages.

上記の例ではいくつかのダミー関数を含んでいます。mt_options_pageのような、実際のページコンテンツのプレース・ホルダーです。これを本物のメニューページに変更しましょう。それでは、我々のプラグインはmt_favorite_foodというオプションを持っており、サイトオーナーがプラグインのオプションページに好きな食べ物を記入できるようにしたいと仮定しましょう。mt_options_page関数がこれを実現するためには、管理画面上にデータ入力フォームがあり、入力されたデータを処理しなくてはいけません。以下がこれを実現する関数の例です: The example above contains several dummy functions, such as mt_settings_page, as placeholders for actual page content. We need to turn them into real menu pages. So, let's assume that our plugin has an option called mt_favorite_color, and that we want to allow the site owner to type in his/her favorite color via a Settings page. The mt_options_page function will need to put a data entry form on the screen to enable this, and also process the entered data. Here is a function that does this:


// mt_options_page()はTest Optionsサブメニューのコンテンツを表示する。
function mt_options_page() {

    // フィールドと設定項目名のための変数
    $opt_name = 'mt_favorite_food';
    $hidden_field_name = 'mt_submit_hidden';
    $data_field_name = 'mt_favorite_food';

    // データベースから既存の設定値を読み込む
    $opt_val = get_option( $opt_name );

    // ユーザが何かの情報を投稿したかどうかをチェックする
    // 投稿していれば、このhiddenフィールドの値は'Y'にセットされる
    if( $_POST[ $hidden_field_name ] == 'Y' ) {
        // 投稿された値を読む
        $opt_val = $_POST[ $data_field_name ];

        // データベースに値を設定する
        update_option( $opt_name, $opt_val );

        // 画面に更新されたことを伝えるメッセージを表示

?>
<div class="updated"><p><strong><?php _e('Options saved.', 'mt_trans_domain' ); ?></strong></p></div>
<?php

    }

    // 設定変更画面を表示する

    echo '<div class="wrap">';

    // ヘッダー

    echo "<h2>" . __( 'Menu Test Plugin Options', 'mt_trans_domain' ) . "</h2>";

    // 設定用フォーム
    
    ?>

<form name="form1" method="post" action="<?php echo str_replace( '%7E', '~', $_SERVER['REQUEST_URI']); ?>">
<input type="hidden" name="<?php echo $hidden_field_name; ?>" value="Y">

<p><?php _e("Favorite Color:", 'mt_trans_domain' ); ?> 
<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" value="<?php _e('Update Options', 'mt_trans_domain' ) ?>" />
</p>

</form>
</div>

<?php
 
}

// mt_settings_page() displays the page content for the Test settings submenu
function mt_settings_page() {

    //must check that the user has the required capability 
    if (!current_user_can('manage_options'))
    {
      wp_die( __('You do not have sufficient permissions to access this page.') );
    }

    // variables for the field and option names 
    $opt_name = 'mt_favorite_color';
    $hidden_field_name = 'mt_submit_hidden';
    $data_field_name = 'mt_favorite_color';

    // Read in existing option value from database
    $opt_val = get_option( $opt_name );

    // See if the user has posted us some information
    // If they did, this hidden field will be set to 'Y'
    if( isset($_POST[ $hidden_field_name ]) && $_POST[ $hidden_field_name ] == 'Y' ) {
        // Read their posted value
        $opt_val = $_POST[ $data_field_name ];

        // Save the posted value in the database
        update_option( $opt_name, $opt_val );

        // Put a "settings saved" message on the screen

?>
<div class="updated"><p><strong><?php _e('settings saved.', 'menu-test' ); ?></strong></p></div>
<?php

    }

    // Now display the settings editing screen

    echo '<div class="wrap">';

    // header

    echo "<h2>" . __( 'Menu Test Plugin Settings', 'menu-test' ) . "</h2>";

    // settings form
    
    ?>

<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
 
}


注意点:

  • WordPressの管理機能はユーザ認証に対する注意を十分に払っているので、その点を心配する必要はありません。
  • The WordPress functions such as add_menu_page and add_submenu_page take a capability which will be used to determine whether the top-level or sub-level menu is displayed.
  • The function which is hooked in to handle the output of the page must check that the user has the required capability as well.
  • The WordPress administration functions take care of validating the user login, so you don't have to worry about it in your function.
  • 上記の例に挙げた関数は多言語化されています。詳しくは プラグインの多言語化を参照のこと。
  • 関数は入力されたデータが画面の入力フォームに表示されるよりも前に処理するので、フォーム内の値は(データベースの中よりも)新しいものになります。
  • 最初はこの働きについて心配する必要はありません。というのは、WordPressのupdate_option関数は、その値が存在しなければ、自動的にデータベースへ追加するからです。
  • これらの管理メニュー追加の手順は管理画面でページに移動するたび発生します。もしも設定ページを持たず、後になって付け加えるようなことがあれば、上の指示に従ってページを追加し、アップロードし、しっくりくるまでチューニングしてください。言い換えれば、メニューは"恒常的に追加されてはいない"のであり、プラグインを有効にしたときにデータベースへ追加されたのでもありません。その都度忙しなく解析されているのであり、好きなときにメニューを付けたり外したりできます。アップロードしなおせば、すぐに変更が反映されます。


Page Hook Suffix

Every function that adds a new administration menu (add_menu_page(), add_submenu_page() and its specialized versions such as add_options_page()) returns a special value called Page Hook Suffix. It can be used later as a hook to which an action called only on that particular page can be registered.

One such action hook is load-{page_hook}, where {page_hook} is the value returned by one of these add_*_page() functions. This hook is called when the particular page is loaded. In the example below, it is used to display the "Plugin is not configured" notice on all admin pages except for plugin's options page:

<?php
add_action('admin_menu', 'my_plugin_menu');

// Here you can check if plugin is configured (e.g. check if some option is set). If not, add new hook. 
// In this example hook is always added.
add_action( 'admin_notices', 'my_plugin_admin_notices' );

function my_plugin_menu() {
	// Add the new admin menu and page and save the returned hook suffix
	$hook_suffix = add_options_page('My Plugin Options', 'My Plugin', 'manage_options', 'my-unique-identifier', 'my_plugin_options');
	// Use the hook suffix to compose the hook and register an action executed when plugin's options page is loaded
	add_action( 'load-' . $hook_suffix , 'my_load_function' );
}

function my_load_function() {
	// Current admin page is the options page for our plugin, so do not display the notice
	// (remove the action responsible for this)
	remove_action( 'admin_notices', 'my_plugin_admin_notices' );
}

function my_plugin_admin_notices() {
	echo "<div id='notice' class='updated fade'><p>My Plugin is not configured yet. Please do it now.</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>Here is where the form would go if I actually had options.</p>';
	echo '</div>';
}
?>

関連情報


最新英語版: WordPress Codex » Adding Administration Menus最新版との差分