WordPress.org

Ready to get started?Download WordPress

Codex

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

Contents

Вступление

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

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

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

Первым шагом в создании собственного административного меню это определить к какому системному меню WordPress оно относится. Большинство плагинов добавляют свои меню в существующий верхний уровень меню WordPress. Вот руководство, что принадлежит к каждому меню верхнего уровня:

Settings / Настройки
Отобажение настроек плагина которые доступны только администратору (также смотрите Создание Страниц Настроек).
Manage
Отображение управления ссылками, записями, категориями, изображениями, etc.
Plugins / Плагины
Установка/удаление, включение/выключение и редактирование плагинов.
Presentation / Внешний Вид
Управление темами/стилями файлов, боковой панелью, etc.
Write / Записи
Создание контента (записей и страниц).
Users / Пользователи
Управление пользователями.

Если ваш плагин вводит совершенно новое понятие или функцию для WordPress, и нуждается в большем колличестве экранов, чтобы это сделать, для вашего плагина возможен вариант создания нового меню верхнего уровня. Это следует рассматривать только если вам действительно нужно несколько связанных экранов, чтобы сделать в WordPress к чему он изначально не предназначен. Примеры могут включать управление галерей изображений, администрирование баз данных, или управление конференцией.

С плагином Custom Admin Menu, пользователи также имеют возможность сами решать, должен ли ваш плагин занять меню верхнего уровня или нет -- вы можете дать понять пользователям, что они имеют такую ​​возможность, особенно если вы решили создать меню верхнего уровня.

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.