Codex tools: Log in / create account
Languages: English • 日本語 • Русский • (Add your language)
Contents |
Many plugins give their users options or settings, which allow the users a way to customize how the plugin is used. As a plugin author, you have several choices in how to set this up. One way is to have the user edit information in the plugin's PHP file, but this makes many users uncomfortable (to say the least). So, a better way is usually to create administration screens that let the plugin user set options in a more familiar manner.
This article explains how to add custom administration screens to WordPress in a plugin. It assumes you are already familiar with the basics of Writing a Plugin and the Plugin API of Actions and Filters.
To add an admin menu, you must do three things:
Code should be added in the main plugin php file or a separate php include.
The second step is often overlooked by new plugin developers. You cannot simply call the menu code described below; you must put it inside a function and then register the function.
A very simple example of the above three steps:
<?php
add_action('admin_menu', 'my_plugin_menu');
function my_plugin_menu() {
add_options_page('My Plugin Options', 'My Plugin', 8, 'your-unique-identifier', 'my_plugin_options');
}
function my_plugin_options() {
echo '<div class="wrap">';
echo '<p>Here is where the form would go if I actually had options.</p>';
echo '</div>';
}
?>
As you can see, we have a function, my_plugin_menu, which adds a new item to the Admin menu (via the add_options_page function, described in the next section--more complicated multiple menu items can be added, as seen below). Then, we invoke the Wordpress hook which "registers" this function. Without that, a PHP error for "undefined function" will be thrown when you attempt to activate the plugin. Lastly, we create a function which contains the actual page to be displayed (and PHP code to be processed) when someone clicks the menu item.
The actual processes for the last two of these three steps are described in the sections below. But do not forget that you must enclose them in functions, and invoke that admin_menu hook to get the whole process started!
Before creating custom administration screens you must figure out where in the WordPress administration menu system they belong. Most plugins add their screens as submenus underneath the existing WordPress top-level menus. Here is a guide to what belongs in which top-level menu:
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.
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).
If for some reason you have decided that your plugin really needs a brand-new top-level menu, the first thing you'll need to do is to create one. Otherwise, skip to Sub-Menus below.
To add a new top-level menu, you'll use the add_menu_page function:
add_menu_page(page_title, menu_title, access_level/capability, file, [function], [icon_url]);
Parameter values:
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.
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:
Commonly-used examples:
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 the first time with the parent and file parameters being given the same value.
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:
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]);
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>";
}
?>
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: