- 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。（詳細）
「管理メニューの追加」の版間の差分
細 (ページ Adding Administration Menus を 管理メニューの追加 へ移動: Codex‐ノート:ページ名対応表#A での議論に従い日本語ページ名に改名。) |
細 (要更新、ソートキー追加、ロシア語リンク追加) |
||
| 1行目: | 1行目: | ||
| − | {{ | + | {{Old}} |
== はじめに == | == はじめに == | ||
| 267行目: | 267行目: | ||
{{原文|Adding Administration Menus|67603}}<!-- 15:04, February 20, 2009 Ronnie268 版 --> | {{原文|Adding Administration Menus|67603}}<!-- 15:04, February 20, 2009 Ronnie268 版 --> | ||
| + | {{DEFAULTSORT:かんりめにゆうのついか}} | ||
[[Category:プラグイン]] | [[Category:プラグイン]] | ||
[[Category:上級トピック]] | [[Category:上級トピック]] | ||
| 272行目: | 273行目: | ||
[[en:Adding Administration Menus]] | [[en:Adding Administration Menus]] | ||
| + | [[ru:Добавление административных меню]] | ||
2010年11月1日 (月) 13:29時点における版
このページ「管理メニューの追加」は 情報が古くなっている可能性があります。最新版（英語）も合わせてご覧ください。最新に更新してくださる協力者を求めています。
目次
はじめに
多くのプラグインはユーザに設定項目を提供することで、プラグインの使用法をカスタマイズできるようにしています。プラグイン作者として、あなたにはいくつかのセットアップ方法があります。一つはプラグインのPHPファイルをユーザに編集させることです。しかし、これは多くのユーザにとって、不愉快です(控えめに言って、ですよ)。したがって、通常考えられるもっと良い方法というのは、ユーザがやり慣れた方法で設定を編集できる管理画面を用意することです。
この記事では、プラグインがWordPressにカスタム管理画面を追加する方法について説明します。すでにプラグインの作成とアクション・フィルターというプラグイン APIの基本的な部分は理解している読者を想定しています。
どんな文脈でもHookが必要
管理メニューを作るには、次の三つを行う必要があります:
- メニューを作成するコードを含んだ関数を作る
- "admin_menu"フックに上で作った関数を登録する
- メニューがクリックされたときに表示されるページのHTML出力を作る
コードはプラグインの主要なPHPファイルに含まれるか、別のPHPからインクルードされなくてはいけません。
二番目のステップは、新米プラグイン開発者には見過ごされがちです。次に述べるメニュー作成コードを単に呼び出すだけではいけません;あなたはそれを関数の中に入れ、それから関数を登録するのです。
上記の三ステップを簡単な例にしてみましょう:
<?php
add_action('admin_menu', 'my_plugin_menu');
function my_plugin_menu() {
add_options_page('My Plugin Options', 'My Plugin', 8, __FILE__, 'my_plugin_options');
}
function my_plugin_options() {
echo '<div class="wrap">';
echo '<p>設定用のフォームが表示されるところ</p>';
echo '</div>';
}
?>
ご覧のように、管理画面に新しいアイテムを追加するmy_plugin_menu関数がありますよね(次節で述べるadd_options_page関数を使えば、もっと複雑な複数のメニューアイテムを追加できます。もうちょっと読んでみましょう)。それでは、この関数を"登録"するためのWordPressフックを呼び出しましょう。これを行わないと、プラグインを有効化しようとしたときに"undefined function"というPHPエラーが投げられます。最後に、ユーザがクリックしたときに表示されるページ(と、処理されるPHPコード)を含む関数を作りましょう。
終わりの二つのステップの具体的な処理内容は、これから説明します。コードを関数の中に入れ、すべての処理を開始するためにadmin_menuフックを呼び出す、ということだけは忘れないでください！
メニューとサブメニュー
カスタムの管理画面を作る前に、WordPressの管理メニューのどこにそれが属するのかを指定しなくてはいけません。ほとんどのプラグインはWordPressの既存トップレベルメニュー下にサブメニューとして登録されます。以下はそれぞれのトップレベルメニューの属性です:
- 設定
- プラグイン設定を表示し、管理者だけに見える(設定ページを作るも参考のこと)。
- 管理
- リンク、投稿、カテゴリー、画像などの管理ページを表示する。〔訳注：トップレベルメニュー「管理」はバージョン2.7より廃止されました〕
- プラグイン
- プラグインの初期設定以外を行う管理画面を表示する。
- 外観
- テーマやサイドバーなどを編集する管理画面を表示。
- 投稿
- コンテンツ(投稿やページ)を書くための管理画面を表示。
- ユーザ
- ユーザ管理画面を表示。
もしあなたの作ったプラグインがWordPressにとってまったく新しい機能を提供するならば、たくさんの管理画面が必要でしょう。あなたのプラグイン用に新しいトップレベルメニューを作るという道もあります。WordPressにまったく独自の新しいことを行わせるために複数の連携した管理画面が必要だというときだけ、この方法をとるようにしてください。たとえば、画像ギャラリーの管理、データベース管理、コメント管理などです。
Custom Admin Menu pluginを使うとき、ユーザはプラグインをトップレベルメニューに置くか否かを決められるようになります。トップレベルメニューを作ると決めたのならば、そういった選択肢もあるということをユーザに知らせた方がよいでしょう。
どこにメニュー・サブメニューを追加するのかを決定したら、次はWordPressに対して新しいページのことを知らせましょう。これはすべて'admin_menu'アクションに登録した関数の中に入れてください(この節の最後にある例を参照のこと)
トップレベルメニュー
なんらかの理由により、あなたの作るプラグインには新しいトップレベルメニューが必要だということになったら、あなたがまずしなくてはならないのは、それを作ることです。それが嫌ならば、下のサブメニューまで進んでください。
新しいトップレベルメニューを追加するには、add_menu_page関数を使います:
add_menu_page(''page_title'', ''menu_title'', ''access_level/capability'', ''file'', ''[function]'', ''[icon_url]'');
パラメータ:
- page_title
- メニューが有効になった時に表示されるHTMLのページタイトル用テキスト。
- menu_title
- 管理画面のメニュー上での表示名。
- access_level/capability
- このメニューページを閲覧・使用するために最低限必要なユーザーレベルまたはユーザーの種類と権限 。
- file
- メニューページのコンテンツを表示するPHPファイル。
- function
- メニューページにコンテンツを表示する関数。
技術的に言うとfunctionパラメータはオプションですが、指定されていない場合、WordPressは基本的にインクルードされたPHPファイルが管理画面を出力するものと仮定し、関数を呼び出しません。ほとんどのプラグイン作者はページ生成コードを持つ関数をメインのプラグインファイル内に書いています。
- icon_url
- これはWordPress 2.7においてのみ有効です。メニューにカスタムアイコンを追加します。
サブメニュー
トップレベルメニューを決定するか、既存のWordPressトップレベルメニューを使うことを選んだら、add_submenu_page関数を使ってサブメニューを定義する準備ができました。表示したい順番に追加していくようにしてください。
add_submenu_page(''parent'', ''page_title'', ''menu_title'', ''access_level/capability'', ''file'', ''[function]'');
パラメータ:
- parent
- サブメニューを挿入したいトップレベルメニューを提供するWordPressのコアadminファイル名。プラグインがトップレベルメニューをなしている場合は、そのプラグインファイル。
よくある例:
- 投稿用: add_submenu_page('post-new.php',...)
- 管理用: add_submenu_page('edit.php',...)
- 外観用: add_submenu_page('themes.php',...)
- コメント用: add_submenu_page('edit-comments.php',...)
- 設定用: add_submenu_page('options-general.php',...)
- プラグイン用: add_submenu_page('plugins.php',...)
- ユーザ用: add_submenu_page('users.php',...)
- page_title
- サブメニューがクリックされたときにHTMLページタイトルになるテキスト。
- menu_title
- サブメニューの管理画面上での名前。
- access_level/capability
- このメニューページを閲覧・使用するために最低限必要なユーザーレベルまたはユーザーの種類と権限 。
- file
- 既存のWordPressメニュー用には、メニューページのコンテンツを表示するPHPファイル。カスタムのトップレベルメニュー下においては、ユニークなこのサブメニューページの識別子。
プラグインがトップレベルメニューを持つ場合、最初のサブメニューはトップレベルメニューと同じ名前を持ち、従ってリンクは複製されます。リンクの複製を避けるには、はじめにadd_submenu_page関数を呼び出し、parentとfileパラメータを同じ名前にします。
- function
- メニューページのコンテンツを出力する関数。
add_menu_page関数と同じく、技術的に言うとfunctionパラメータはオプションですが、指定されていない場合、WordPressは基本的にインクルードされたPHPファイルが管理画面を出力するものと仮定し、関数を呼び出しません。ほとんどのプラグイン作者はページ生成コードを持つ関数をメインのプラグインファイル内に書いています。
以下はトップレベルメニューページとサブメニューページを挿入する簡単な例です。サブメニューのタイトルはトップレベルページと異なるものになっています。この例では、'my_magic_function'が最初のサブメニューページを表示する関数になります:
add_menu_page('Page title', 'Top-level menu title', 8, __FILE__, 'my_magic_function');
add_submenu_page(__FILE__, 'Page title', 'Sub-menu title', 8, __FILE__, '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]'');
ページの挿入
以下は色々な場所に新しいメニューを挿入する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>";
}
?>
メニューページサンプル
上記の例ではいくつかのダミー関数を含んでいます。mt_options_pageのような、実際のページコンテンツのプレース・ホルダーです。これを本物のメニューページに変更しましょう。それでは、我々のプラグインはmt_favorite_foodというオプションを持っており、サイトオーナーがプラグインのオプションページに好きな食べ物を記入できるようにしたいと仮定しましょう。mt_options_page関数がこれを実現するためには、管理画面上にデータ入力フォームがあり、入力されたデータを処理しなくてはいけません。以下がこれを実現する関数の例です:
// 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
}
注意点:
- WordPressの管理機能はユーザ認証に対する注意を十分に払っているので、その点を心配する必要はありません。
- 上記の例に挙げた関数は多言語化されています。詳しくは プラグインの多言語化を参照のこと。
- 関数は入力されたデータが画面の入力フォームに表示されるよりも前に処理するので、フォーム内の値は(データベースの中よりも)新しいものになります。
- 最初はこの働きについて心配する必要はありません。というのは、WordPressのupdate_option関数は、その値が存在しなければ、自動的にデータベースへ追加するからです。
- これらの管理メニュー追加の手順は管理画面でページに移動するたび発生します。もしも設定ページを持たず、後になって付け加えるようなことがあれば、上の指示に従ってページを追加し、アップロードし、しっくりくるまでチューニングしてください。言い換えれば、メニューは"恒常的に追加されてはいない"のであり、プラグインを有効にしたときにデータベースへ追加されたのでもありません。その都度忙しなく解析されているのであり、好きなときにメニューを付けたり外したりできます。アップロードしなおせば、すぐに変更が反映されます。
関連情報
最新英語版： WordPress Codex » Adding Administration Menus （最新版との差分）
