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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(メニューとサブメニュー)
(ページの挿入)
268行目: 268行目:
 
     add_options_page('Test Options', 'Test Options', 8, 'testoptions', 'mt_options_page');
 
     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_management_page('Test Manage', 'Test Manage', 8, 'testmanage', 'mt_manage_page');
  

2015年12月11日 (金) 11:38時点における版

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

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

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

はじめに

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

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

関数リファレンス

全般的な関数

メニュー

サブメニュー

WordPress 管理メニュー

どんな文脈でもHookが必要

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

  1. メニューを作成するコードを含んだ関数を作る
  2. "admin_menu"フックに上で作った関数を登録する
  3. メニューがクリックされたときに表示されるページのHTML出力を作る

コードはプラグインの主要なPHPファイルに含まれるか、別のPHPからインクルードされなくてはいけません。

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

上記の三ステップを簡単な例にしてみましょう:

<?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コード)を含む関数を作りましょう。

終わりの二つのステップの具体的な処理内容は、これから説明します。コードを関数の中に入れ、すべての処理を開始するためにadmin_menuフックを呼び出す、ということだけは忘れないでください!

メニューとサブメニュー

カスタムの管理画面を作る前に、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にまったく独自の新しいことを行わせるために複数の連携した管理画面が必要だというときだけ、この方法をとるようにしてください。たとえば、画像ギャラリーの管理、データベース管理、コメント管理などです。

以下はそれぞれのトップレベルメニューの属性です:

ダッシュボード 
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'アクションに登録した関数の中に入れてください(この節の最後にある例を参照のこと)

トップレベルメニュー

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

新しいトップレベルメニューを追加するには、add_menu_page関数を使います:

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

パラメータ:

page_title
メニューが有効になった時に表示されるHTMLのページタイトル用テキスト。
menu_title
管理画面のメニュー上での表示名。
access_level/capability
このメニューページを閲覧・使用するために最低限必要なユーザーレベルまたはユーザーの種類と権限
file
メニューページのコンテンツを表示するPHPファイル。
function
メニューページにコンテンツを表示する関数。

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

icon_url
これはWordPress 2.7においてのみ有効です。メニューにカスタムアイコンを追加します。
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.

サブメニュー

トップレベルメニューを決定するか、既存のWordPressトップレベルメニューを使うことを選んだら、add_submenu_page関数を使ってサブメニューを定義する準備ができました。表示したい順番に追加していくようにしてください。

add_submenu_page(''parent'', ''page_title'', ''menu_title'', ''access_level/capability'', ''file'', ''[function]'');

パラメータ:

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

よくある例:

  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',...)
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]'');

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 (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>";
}

?>

メニューページサンプル

上記の例ではいくつかのダミー関数を含んでいます。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関数は、その値が存在しなければ、自動的にデータベースへ追加するからです。
  • これらの管理メニュー追加の手順は管理画面でページに移動するたび発生します。もしも設定ページを持たず、後になって付け加えるようなことがあれば、上の指示に従ってページを追加し、アップロードし、しっくりくるまでチューニングしてください。言い換えれば、メニューは"恒常的に追加されてはいない"のであり、プラグインを有効にしたときにデータベースへ追加されたのでもありません。その都度忙しなく解析されているのであり、好きなときにメニューを付けたり外したりできます。アップロードしなおせば、すぐに変更が反映されます。


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最新版との差分