WordPress - Administration Menus

The WordPress administration page contains a number of menus in the left hand sidebar. This page describes how to add your own options to these.

Declare that menus will exist

The first thing is to indicate that there are menu options ... but don't actually define them unless the admin page is displayed.

add_action('admin_menu', array(&$this, 'add_pages'));  // Indicate that there are menu items

When the admin pages are displayed, then the following will define those options

function add_pages() {
  add_options_page(__('Library Events', 'lib_events'), __('Library Events', 'lib_events'), 
    'manage_options', __FILE__, array(&$this, 'option_page'));   // Add to lower Settings menu
}

Note that two underscores - __(string, dictionary_set) - translates the text into another language (assuming that an appropriate translation file is provided).

Create a new top-level menu

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

page_title	Text displayed as the page title
menu_title	Menu label
access_level/capability	The minimum user level to display and use the feature
file	The PHP file that displays the page
function	Optional - Called if present
icon_url	Optional - Uses the associated icon (image) in the menu

Create a new sub-menu

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

parent	Filename of the associated main menus
page_title	Text displayed as the page title Ignored on pages under a custom top level menu
menu_title	Menu label
access_level/capability	The minimum user level to display and use the feature
file/ID	The PHP file that displays the page If you create a custom top level menu, this MUST be a unique ID, otherwise, clicking any sub-menu all cause all items to execute
function	Optional - Called if present Required if you create a custom top level menu
icon_url	Optional - Uses the associated icon (image) in the menu

These aliases (and many more) can be used

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

as indicated in this table (only a few were in the help, the rest were found in the code)

Menu	WP Help	Filename	Shortcut
Posts	Manage	add_submenu_page('edit.php',...)	add_posts_page(...)
Media		add_submenu_page('upload.php',...)	add_media_page(...)
Links		add_submenu_page('link-manager.php',...)	add_links_page(...)
Pages		add_submenu_page('edit-pages.php',...)	add_pages_page(...)
Comments	Comments	add_submenu_page('edit-comments.php',...)	add_comments_page(...)
Appearance	Design	add_submenu_page('themes.php',...)	add_theme_page(...)
Plugins	Plugins	add_submenu_page('plugins.php',...)
Users	Users	add_submenu_page('users.php',...)	add_users_page(...)
Your Profile		add_submenu_page('profile.php',...)	add_users_page(...)
Tools		add_submenu_page('tools.php',...)	add_management_page(...)
Settings	Settings	add_submenu_page('options-general.php',...)	add_options_page(...)
Posts/Add New	Write	add_submenu_page('post-new.php',...)
Dashboard		add_submenu_page('index.php',...)	add_dashboard_page(...)

It is totally unacceptable that the menu titles in the WordPress help do not match the options in the default theme. On your system, you can determine which files are called just by placing the mouse over each menu option and reading the associated filenames in the status bar.

By default, the first sub-menu will have the same label as the top level selection. To change it, create the first sub-menu with the same ID and function as the top level - the menu_title string will be displayed.

Function names

There are 2 ways to define the function names

`'function_name'`	Use this for global functions
`array(&$this, 'class_member_name')`	Use this for class members

Filenames

`'xyz.php'`	This should work, but probably needs a path
`__FILE__`	I use this

Roles and Capabilities

There are 5 roles and 40 capabilities.

When creating a user, only one of the 5 roles can be set. Same when editing the user profile.

Yet, when browsing the database, some individual capabilities are defined. There is no indication how this is done.

The functions to add and remove capabilities exist in

wp-includes/capabilities.php

This is a code example

if(get_user_option('rich_editing') == 'true') {
  add_filter("mce_external_plugins", array(&$this, "mm_forms_tinymce_addplugin"), 11);
  add_filter('mce_buttons',          array(&$this, 'mm_forms_tinymce_registerbutton'), 11);
}

When your page is displayed

A (page_hook) is returned when using any of the functions that add plugin menu items to the admin menu: add_management_page(), add_options_page(), etc. As a result, there is an option to provide custom headers when one of those options is selected. See - Administrative Actions and Plugin API/Action Reference/admin head-(plugin page)

admin_head-(page_hook) or admin_head-(plugin_page): Runs in the HTML section of the admin panel of a plugin-generated page
admin_print_scripts-(page_hook) or admin_print_scripts-(plugin_page): Runs in the HTML section of the admin panel of a plugin-generated page - used to print JavaScript scripts
admin_print_styles--(page_hook) or admin_print_styles--(plugin_page): Runs in the HTML section of the admin panel of a plugin-generated page - used to print styles

(The difference is explained below.)

function myplugin_setup_options(){

  $plugin_page=add_options_page( ... );  // see details above

  add_action( 'admin_head-'. $plugin_page, 'myplugin_admin_header' );
}

function myplugin_admin_header(){
  echo '<p>Only executes when the myplugin options page is displayed.</p>';
}

This code is from admin-header.php, it shows the order the of the actions (thus, explaining the difference).

do_action('admin_enqueue_scripts', $hook_suffix);
do_action("admin_print_styles-$hook_suffix");
do_action('admin_print_styles');
do_action("admin_print_scripts-$hook_suffix");
do_action('admin_print_scripts');
do_action("admin_head-$hook_suffix");
do_action('admin_head');

Author: Robert Clemenzi