WordPress.org

Добавление административных меню

Languages: English • 日本語 • Русский • (Add your language)

Вступление

Многие плагины создают своим пользователям опции и настройки, которые позволяют настроить плагин. Как у автора плагина, у Вас есть несколько вариантов для реализации этой возможности. Одна из них - дать пользователю возможность редактировать код PHP, но это будет для большинства пользователей неудобно. Более привычный вариант - создать специальную страницу в административной части для управления определенными опциями плагина.

Эта статья объясняет как добавить собственное административного меню в WordPress. Это предполагает что вы уже знакомы с основами Написание плагина и Plugin API of Действий и фильтров.

Меню и Подменю

Первым шагом в создании собственного административного меню это определить где в WordPress administration menu system they belong. Большинство плагинов добавляют свои меню в существующий WordPress верхний уровень меню. Вот руководство Here is a guide to what belongs in which top-level menu:

Settings: Displays plugin options that only administrators should view (also see Creating Settings Pages).
Manage: Displays management controls for links, posts, categories, images, etc.
Plugins: Displays controls dealing with plugin management, not configuration options for a plugin itself.
Presentation: Displays controls for manipulation of theme/style files, sidebars, etc.
Write: Displays tools for writing content (posts and pages).
Users: Displays controls for user management.

If your plugin introduces an entirely new concept or feature to WordPress, and needs many screens to do it, another option is to create a new top-level menu for your plugin. This should only be considered if you really need multiple, related screens to make WordPress do something it was not originally designed to do. Examples might include management of image galleries, database administration, or conference management.

With the Custom Admin Menu plugin, users now also have the ability to decide for themselves if they want your plugin to occupy a top-level menu item or not -- you may want to make clear to users that they have that option, particularly if you've decided to create a top-level menu item.

Admin Menu Functions

Now that you have decided where to add your menu/submenu, the next step is to tell WordPress about your new pages. All of this will take place in a function you have registered as an 'admin_menu' action (see example at bottom of this section).

Top-Level menu

The first thing you'll need to do is to create a top-level menu, if you have decided that your plugin really needs one. You'll use the add_menu_page function:

add_menu_page(page_title, menu_title, access_level/capability, file, [function]);

Parameter values:

page_title: Text that will go into the HTML page title for the page when the menu is active.
menu_title: The on-screen name text for the menu.
access_level/capability: The minimum user level or the capability required to display and use this menu page.
file: The PHP file that handles the display of the menu page content.
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. Most plugin authors choose to put the page-generating code in a function within their main plugin file.

Sub-Menus

Once you have a top-level menu defined, or have chosen to use an existing WordPress top-level menu, you are ready to define one or more sub-menu pages using the add_submenu_page function. Make sure to add the submenu pages in the order you want them displayed.

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

Parameter values:

parent: The filename of the core 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. (Examples: index.php, post.php, edit.php, themes.php, plugins.php, etc.)
page_title: Text that will go into the HTML page title for the page when the submenu is active.
menu_title: The on-screen name text for the submenu.
access_level/capability: The minimum user level or the capability required to display and use this submenu page.
file: 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 it's 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 with the parent and file parameters being given the same value.

function: The function that displays the page content for the menu page.

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.

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:

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

Since most submenus go into WordPress's Options, Management, or Presentation menus, WordPress supplies three wrapper functions that make adding a submenu to those pages easier:

For the Options top-level menu (see Creating Options Pages for more on this)

add_options_page(page_title, menu_title, access_level/capability, file, [function]);

For Management

add_management_page(page_title, menu_title, access_level/capability, file, [function]);

For Presentation

add_theme_page( page_title, menu_title, access_level/capability, file, [function]);

Inserting the Pages

Here is an example of a WordPress plugin that inserts new menus into various places:

<?php
/*
Plugin Name: Menu Test
Plugin URI: http://wordpress.org
Description: Menu Test
Author: Nobody
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 Options:
    add_options_page('Test Options', 'Test Options', 8, 'testoptions', 'mt_options_page');

    // Add a new submenu under Manage:
    add_management_page('Test Manage', 'Test Manage', 8, 'testmanage', 'mt_manage_page');

    // Add a new top-level menu (ill-advised):
    add_menu_page('Test Toplevel', 'Test Toplevel', 8, __FILE__, 'mt_toplevel_page');

    // Add a submenu to the custom top-level menu:
    add_submenu_page(__FILE__, 'Test Sublevel', 'Test Sublevel', 8, 'sub-page', 'mt_sublevel_page');

    // Add a second submenu to the custom top-level menu:
    add_submenu_page(__FILE__, 'Test Sublevel 2', 'Test Sublevel 2', 8, 'sub-page2', 'mt_sublevel_page2');
}

// mt_options_page() displays the page content for the Test Options submenu
function mt_options_page() {
    echo "<h2>Test Options</h2>";
}

// mt_manage_page() displays the page content for the Test Manage submenu
function mt_manage_page() {
    echo "<h2>Test Manage</h2>";
}

// mt_toplevel_page() displays the page content for the custom Test Toplevel menu
function mt_toplevel_page() {
    echo "<h2>Test Toplevel</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</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 Sublevel 2</h2>";
}

?>

Sample Menu Page

The example above contains several dummy functions, such as mt_options_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_food, and that we want to allow the site owner to type in his/her favorite food on the plugin's Option 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() displays the page content for the Test Options submenu
function mt_options_page() {

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

    // 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( $_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 an options updated message on the screen

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

    }

    // Now display the options editing screen

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

    // header

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

    // options form
    
    ?>

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

A few notes:

The WordPress administration functions take care of validating the user, so you don't have to worry about it in your function.
The function example above has been internationalized -- see the Internationalization section of Writing a Plugin for more information
The function processes any entered data before putting the data entry form on the screen, so that the new values will be shown in the form (rather than the values from the database).
You don't have to worry about this working the first time, because the WordPress update_option function will automatically add an option to the database if it doesn't already exist.

WordPress.org

Codex