To add an administration menu

Posted on January 29th, 2011

To add an administration menu, you must do three things:

1.    Create a function that contains the menu-building code

2.    Register the above function using the “admin_menu” action hook

3.    Create the HTML output for the page (screen) displayed when the menu item is clicked

Here is a very simple example of the three steps just described. This plug-in will add a sub-level menu item under the Settings top-level menu, and when selected, that menu item will cause a very basic screen to display. Note: this code should be added to a main plug-in PHP file

<?php

add_action(‘admin_menu’, ‘my_plugin_menu’);

function my_plugin_menu()

{

add_options_page(‘My Plugin Options’, ‘My Plugin’, ‘manage_options’, ‘my-unique-identifier’, ‘my_plugin_options’);

}

function my_plugin_options() {

if (!current_user_can(‘manage_options’))  {

wp_die( __(‘You do not have sufficient permissions to access this page.’) );

}

echo ‘<div>’;

echo ‘<p>Here is where the form would go if I actually had options.</p>’;

echo ‘</div>’;

}

?>

In this example, the function,

my_plugin_menu(), adds a new item to the Administration menu via the add_options_page function. The add_action line–that invokes the hook which “registers” the function, my_plugin_menu(). Without that add_action, a PHP error for “undefined function” will be found when attempting to activate the plug-in. Finally, the add_options_page code refers to the my_plugin_options() function which contains the actual page to be displayed (and PHP code to be processed) when someone clicks the menu item.

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

If the creation of a top-level menu is not necessary, decide under what top-level menu to place your sub-level menu item.

Use this guide of the Word Press top-level menus to determine the correct location for your sub-level menu item:

Dashboard

Information central for your site and include the Updates option for updating Word Press core, plug-in, and themes.

Posts

Displays tools for writing posts (time oriented content).

Media

Uploading and managing your pictures, videos, and audio.

Links

Manage references to other blogs and sites of interest.

Pages

Displays tools for writing your static content called pages.

Comments

Control and regulation of reader to respond to posts.

Appearance

Displays controls for manipulation of theme/style files, sidebars, etc.

Plug-in

Displays the controls dealing with plug-in management, ‘not configuration’ options for a plug-in itself.

Users

Display the controls for user management.

Tools

Manage the export, import, and even backup of blog data.

Settings

Displays plug-in options that only administrators should view (also see Creating Settings Pages).

Admin Menu Functions

After deciding where to add the top-level or sub-level menu, the next step is to tell Word Press about the new pages. All of this will take place in a function registered to the ‘admin_menu’ action. A working example is presented at the end of this section.

How to make Top-Level Menus

If the plugin requires a brand-new top-level menu, the first thing that is needed to do is to create one with the add_menu_page function.

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

page_title – The text to be displayed in the title tags of the page when the menu is selected.

menu_title – The on-screen name text for the menu.

capability – The capability required for this menu to be displayed to the user. User levels are deprecated and should not be used here!

menu_slug- The slug name to refer to this menu by (should be unique for this menu).  If the function parameter is omitted, the menu_slug should be 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 Word Press will basically assume that including the PHP file will generate the administration screen, without calling a function.

The function must be referenced in one of two ways:

1.    if the function is a member of a class within the plugin it should be referenced as array( $this, ‘function_name’ )

2.    in all other cases, using the function name itself is sufficient

icon_url – The url to the icon to be used for this menu. This parameter is optional.

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.

Sub-Level Menus

Once the top-level menu is defined, if an existing Word Press top-level menu is chosen to use,  one or more sub-level menu items can be defined using the add_submenu_page function. Make sure to add the sub-level menu items in the order to be displayed.

Using add submenu_page

<?php add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function); ?>

Parameter values:

parent_slug – the slug name for the parent menu or the file name of a standard Word Press admin file that supplies the top-level menu in which you want to insert your submenu or your plug-in file if this submenu is going into a custom top-level menu.

Examples:

1.    For Dashboard: add_submenu_page(‘index.php’,…)

2.    For Posts: add_submenu_page(‘edit.php’,…)

3.    For Media: add_submenu_page(‘upload.php’,…)

4.    For Links: add_submenu_page(‘link-manager.php’,…)

5.    For Pages: add_submenu_page(‘edit.php?post_type=page’,…)

6.    For Comments: add_submenu_page(‘edit-comments.php’,…)

7.    For Appearance: add_submenu_page(‘themes.php’,…)

8.    For Plugins: add_submenu_page(‘plugins.php’,…)

9.    For Users: add_submenu_page(‘users.php’,…)

10.    For Tools: add_submenu_page(‘tools.php’,…)

11.    For Settings: add_submenu_page(‘options-general.php’,…)

page_title – Text that will go into the HTML page title for the page when the submenu is active.

menu_title – The text to be displayed in the title tags of the page when the menu is selected.

capability – The capability required for this menu to be displayed to the user. User levels are deprecated and should not be used here!

menu_slug – For existing Word Press 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.

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

Here is an example of a Word Press plug-in that inserts new menus into various places:

<?php

/*

Plugin Name: Menu Test

Plugin URI: http://codex.wordpress.org/Adding_Administration_Menus

Description: Menu Test

Author: Codex authors

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 Settings:

add_options_page(__(‘Test Settings’,'menu-test’), __(‘Test Settings’,'menu-test’), ‘manage_options’, ‘testsettings’, ‘mt_settings_page’);

// Add a new submenu under Tools:

add_management_page( __(‘Test Tools’,'menu-test’), __(‘Test Tools’,'menu-test’), ‘manage_options’, ‘testtools’, ‘mt_tools_page’);

// Add a new top-level menu (ill-advised):

add_menu_page(__(‘Test Toplevel’,'menu-test’), __(‘Test Toplevel’,'menu-test’), ‘manage_options’, ‘mt-top-level-handle’, ‘mt_toplevel_page’ );

// Add a submenu to the custom top-level menu:

add_submenu_page(‘mt-top-level-handle’, __(‘Test Sublevel’,'menu-test’), __(‘Test Sublevel’,'menu-test’), ‘manage_options’, ‘sub-page’, ‘mt_sublevel_page’);

// Add a second submenu to the custom top-level menu:

add_submenu_page(‘mt-top-level-handle’, __(‘Test Sublevel 2′,’menu-test’), __(‘Test Sublevel 2′,’menu-test’), ‘manage_options’, ‘sub-page2′, ‘mt_sublevel_page2′);

}

// mt_settings_page() displays the page content for the Test settings submenu

function mt_settings_page() {

echo “<h2>” . __( ‘Test Settings’, ‘menu-test’ ) . “</h2>”;

}

// mt_tools_page() displays the page content for the Test Tools submenu

function mt_tools_page() {

echo “<h2>” . __( ‘Test Tools’, ‘menu-test’ ) . “</h2>”;

}

// mt_toplevel_page() displays the page content for the custom Test Toplevel menu

function mt_toplevel_page() {

echo “<h2>” . __( ‘Test Toplevel’, ‘menu-test’ ) . “</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’, ‘menu-test’ ) . “</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 Sublevel2′, ‘menu-test’ ) . “</h2>”;

}

?>

Sample Menu Page

The example above contains several dummy functions, such as mt_settings_page, as placeholders for actual page content. We need to turn them into real menu pages. Assume that our plug-in has an option called mt_favorite_color, and if the site owner to type in his/her favorite color via a Settings 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_settings_page() displays the page content for the Test settings submenu

function mt_settings_page() {

//must check that the user has the required capability

if (!current_user_can(‘manage_options’))

{

wp_die( __(‘You do not have sufficient permissions to access this page.’) );

}

// variables for the field and option names

$opt_name = ‘mt_favorite_color’;

$hidden_field_name = ‘mt_submit_hidden’;

$data_field_name = ‘mt_favorite_color’;

// 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( isset($_POST[ $hidden_field_name ]) && $_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 settings updated message on the screen

?>

<div class=”updated”><p><strong><?php _e(‘settings saved.’, ‘menu-test’ ); ?></strong></p></div>

<?php

}

// Now display the settings editing screen

echo ‘<div class=”wrap”>’;

// header

echo “<h2>” . __( ‘Menu Test Plugin Settings’, ‘menu-test’ ) . “</h2>”;

// settings form

?>

<form method=”post” action=”">

<input value=”Y”>

<p>

<?php _e(“Favorite Color:”, ‘menu-test’ ); ?>

<input value=”<?php echo $opt_val; ?>” size=”20″>

</p><hr />

<p>

<input class=”button-primary” value=”<?php esc_attr_e(‘Save Changes’) ?>” />

</p>

</form>

</div>

<?php

}

?>