编辑“WordPress:Adding Administration Menus”

== 介绍==

许多插件向用户提供选项或者设置，使得用户能够自定义插件的使用方式。作为插件作者，你可以使用多种方式设置这个功能。一种方式是使用户在插件的PHP文件中编辑信息，但多数用户觉得这样做不便利（至少是这样觉得的）。因此，更好的方法通常是创建管理界面，使得插件用户更方便地设置选项。

这篇文件介绍了怎样在插件中为WordPress添加自定义管理界面。前提是你已经熟悉[[WordPress:Writing a Plugin|编写插件]]和Actions 和Filters的[[WordPress:Plugin API|插件API]]的基本知识。

== 菜单和子菜单 ==

创建自定义管理界面，首先要了解界面属于WordPress管理菜单系统的哪个部分。大多数插件将界面添加到WordPress当前最高级别的菜单。下面有个指南，关于最高级别菜单中，有哪些内容：

;[[WordPress:Administration_Panels#Settings_-_Configuration_Settings|设置]]:显示只有管理员才能够看到的插件选项（也看看[[WordPress:Creating_Options_Pages|创建设置页面]]）。

;[[WordPress:Administration_Panels#Manage_-_Change_your_content|管理]]:显示链接，文章，类别，图像，等等的管理控制。

;[[WordPress:Administration_Panels#Plugins_-_Add_Functionality_to_your_Blog|插件]]:显示插件管理，而不是插件自身配置选项的控制。

;[[WordPress:Administration_Panels#Presentation_-_Change_the_Look_of_your_Blog|Presentation]]:显示操作主题/样式文件，边栏等等的控制功能。

;[[WordPress:Administration_Panels#Write_-_Make_some_content|写]]:显示编写内容（文章和网页）的工具。

;[[WordPress:Administration_Panels#Users_-_Your_Blogging_Family|用户]]:显示控制用户管理的功能。

如果你的插件介绍了全新的WordPress 理念或者功能，而且需要许多界面实现这个功能，另一个选项是为你的插件创建全新的最高级别的菜单。如果你真的需要多个相关的界面，使得WordPress执行最初设计的操作范围外的一些操作，你就需要考虑插件的这些功能。例子包括图像集管理，数据库管理，或者会议管理。

使用[http://barunsingh.com/software/custom-admin-menu/ 自定义管理菜单插件]，用户现在也能够决定是否使自己的插件复制最高级别的菜单内容—你可能想向用户阐明他们可以那样做，特别是如果你已经创建了自定义的最高级别的菜单内容。

== 管理菜单函数 ==

既然你已经决定在哪里添加菜单/子菜单，接着就是要向WordPress展示你的新页面。所有这些操作，都会在注册为<tt>'admin_menu'</tt> action的函数中发生（请看看这个部分的底部的例子）。

=== 最高级别菜单===

首先，如果你已经确定插件需要最高级别菜单，你要创建一个。你将会使用<tt>add_menu_page</tt>函数：

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

参数值:

;page_title:菜单激活的时候，文本会进入HTML网页标题。

;menu_title:菜单的界面名文本。

;access_level/capability:用来显示和使用这个菜单页面的最小的[[WordPress:User Levels|用户级别]] 或者[[WordPress:Roles_and_Capabilities|权限]]。

;文件：控制菜单页面内容的显示情况的PHP文件。
;函数:显示菜单页面内容的函数。

从技术上说，''function''参数是可选择的，但是如果没有应用这个参数，WordPress会认定包含了PHP文件，不需要调用函数，就会创建管理界面。大多数插件作者选择将创建网页的代码，放入主要的插件文件的函数中。

=== 子菜单 ===

你定义了最高级别的菜单，或者已经选择使用WordPress当前最高级别的菜单，你就要准备使用<tt>add_submenu_page</tt>函数，定义一个或者更多的子菜单页面。确定添加子菜单页面的顺序，与页面的显示顺序相同。

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

参数值：
;parent:WordPress核心管理文件的文件名，这个文件应用了最高级别的菜单，你希望将子菜单插入到这个菜单中，如果子菜单进入自定义最高级别的菜单，你可以插入插件（例子：index.php, post.php, edit.php, themes.php, plugins.php,等等）
;page_title:激活子菜单时，进入网页HTML网页标题的文本。
;menu_title:子菜单的界面名文本。
;access_level/权限:显示并且使用这个子菜单页面的最小的[[WordPress:User Levels|用户级别]] 或者[[WordPress:Roles_and_Capabilities|权限]]。
;file:对于当前存在的WordPress菜单，指的是控制菜单内容显示情况的PHP文件。自定义最高级别菜单的子菜单页面有'''唯一的'''标示符。

''插件创建自身最高级别菜单的时候，第一个子菜单的链接标题通常与最高级别菜单的链接标题是相同的，因此链接得到了复制。使用相同参数值的母和文件参数，调用add_submenu_page函数，可以避免复制链接标题。

;function:显示菜单页面的网页内容的函数。

一般来说，就如<tt>add_menu_page</tt>函数，''function''参数是可选的，但是如果没有提供这个函数，WordPress会推测不需要调用函数，包含PHP文件，就会产生管理界面。大多数插件作者选择将产生网页的代码放入主要的插件文件的函数中。

下面有个例子，解释了怎样插入顶级菜单页面和子菜单页面，子菜单页面的标题和顶级页面的标题有什么不同。在这个例子中，'my_magic_function'是显示第一个子菜单页面的函数名。

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

因为大多数子菜单页面在WordPress选项，管理，或者Presentation菜单中，WordPress提供了三个包装函数，向这些页面添加子菜单变得更加简单：

;关于选项顶级菜单（更多的内容，请看看[[WordPress:Creating Options Pages|创建选项页面]]）：

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

=== 插入页面 ===

下面是WordPress插件的例子，在不同的位置，插入新的菜单：
<pre>
<?php
/*
插件名: 菜单测试
插件 URI: http://wordpress.org
描述: 菜单测试
作者: 没有人
作者URI: http://example.com
*/

// 添加管理菜单Hook 
add_action('admin_menu', 'mt_add_pages');

// action function for above hook
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');

    // 添加新的顶级菜单(ill-advised):
    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() 为测试选项子菜单，显示页面内容
function mt_options_page() {
    echo "<h2>Test Options</h2>";
}

// mt_manage_page() 为测试管理子菜单，显示页面内容
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() d显示第二个子菜单的页面内容
// 自定义测试顶级菜单
function mt_sublevel_page2() {
    echo "<h2>Test Sublevel 2</h2>";
}

?>
</pre>

=== 样本菜单页面 ===

上述的例子包含了几个哑元函数，如<tt>mt_options_page</tt>，作为真正的网页内容的占位符。我们需要将这些函数转变为真正的菜单页面。同时，加入我们的插件有个称为mt_favorite_food的选项，而且我们希望站点作者在插件的选项页面上输入他/她最喜爱的食物。<tt>mt_options_page</tt>函数需要将数据entry 形式放到界面上，实现这个操作，同时处理输入的数据。下面有个函数，可以执行这个操作：

<pre>

// mt_options_page()显示测试选项子菜单的页面内容
function mt_options_page() {

// fields和选项名称的变数
    $opt_name = 'mt_favorite_food';
    $hidden_field_name = 'mt_submit_hidden';
    $data_field_name = 'mt_favorite_food';

//阅读数据库中当前选项的参数值
    $opt_val = get_option( $opt_name );

// 看看用户有没有向我们发送一些信息
    // 如果发送了，这个隐藏的栏，就会被设置为'Y'
    if( $_POST[ $hidden_field_name ] == 'Y' ) {
        // 阅读 posted value
        $opt_val = $_POST[ $data_field_name ];

        // 将posted value 保存到数据库
        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
 
}
</pre>

几点注意：

*WordPress管理函数能够确认用户，因此你的函数不需要确认。

*上述的函数例子已经国际化了—更多的信息，请看看[[WordPress:Writing_a_Plugin#Internationalizing_Your_Plugin|编写插件的国际化部分]]

*函数处理好了输入的数据后，才将数据库entry form放到界面上，因此形式会显示新的参数值（而不是数据库参数值）。

*第一次，你不需要担心选项的运行，因为如果选项不存在，WordPress<tt>update_option</tt>会自动将选项添加到数据库中。