Plugin Administration Menus

When creating your own plugins you’ll often want to add one or more admin pages to allow users to configure options and add content, depending on what your plugin does. A couple of weeks ago I explained how to add an Options Page, this week I’ll run through how to add pages to other sections.

Creating a Submenu Page

The syntax of using these predefined functions is the same as using the options page function. To remind ourselves, this is

add_options_page(Page Title, Menu Title, user level / capability, file, function name, icon url);

For adding a management page, which will then appear under the Tools menu (for WordPress 2.6 and below this would appear on the management menu), we use

add_management_page(Page Title, Menu Title, user level / capability, file, function name, icon url);

and for adding a page to the Theme management section we use

add_theme_page(Page Title, Menu Title, user level / capability, file, function name, icon url);

If you want to add a menu page to another section then we use the standard add_submenu_page() function. This is almost the same as the predefined functions except we tell the function which admin page to make this a submenu of. The syntax for this function is

add_submenu_page(Parent File, Page Title, Menu Title, user level / capability, file, function name, icon url);

The parent file is just the PHP filename (including the .php extension) of the parent file, all of which are listed below:

• For the Dashboard menu use index.php
• For the Posts menu use edit.php
• For the Media menu use media.php
• For the Links menu use link-manager.php
• For the Pages menu use edit-pages.php
• For the Comments menu use edit-comments.php
• For the Plugins menu use plugins.php
• For the Users menu use users.php

Of course the Appearance, Tools and Settings menus can be targeted using the predefined functions above.

Creating a new Menu

If you start to develop larger plugin files then you may find that you need several pages for users to manage their content. Once you get to this point then you’ll want to create a whole new menu section. To do this we use the add_menu_page() function, and then add subpages to that. The syntax to create your own menu is

add_menu_page(Page Title, Menu Title, User Level / Capability, file, function name, icon);
add_submenu_page(Parent File, 'Page Title', 'Menu Title', User Level / Capability, file, function name);

Then you would repeat the submenu page function for each submenu page you need. For example, a recent plugin that I’ve created for converting a gallery section over to work in WordPress (without having to change 1000+ records to use the built in WP Gallery!), used the menu of

add_menu_page('Gallery Management', 'Gallery Management', 8, __FILE__, 'album_mgt_add');
add_submenu_page(__FILE__, 'Add a Gallery', 'Add a Gallery', 8, __FILE__, 'album_mgt_add');
add_submenu_page(__FILE__, 'Edit a Gallery', 'Edit a Gallery', 8, 'album_mgt_edit', 'album_mgt_edit');
add_submenu_page(__FILE__, 'Remove a Gallery', 'Remove a Gallery', 8, 'album_mgt_rem', 'album_mgt_rem');

In the add_menu_page() the fourth parameter is told to use the existing plugin file to find the album_mgt_add() function. Then in the first submenu page I’ve used similar parameters (except the additional first parameter is set to use the plugin file as the parent, so that the submenu page appears in the correct menu), so that if you click on the ‘Gallery Management’ main menu heading, or open it up and click on the Add a Gallery, both will go to the Add a Gallery page, similar to how the other admin menus work. For the Edit and Remove pages I’ve set the fifth and sixth parameters to use the function name as all the functions are in one file. If you were to split the plugin into several files (recommended for very large plugins) then you would set the fifth parameter to be the filename of where WordPress can find the function.

Controlling Access

I personally prefer to use the user level system to control who can see the menus, which means that I tend to set a level access of 8 for Administrators only, 7 for Editors and Administrators, 2 for authors and then 0 for any registered user. You can read more about the roles and capabilities available to you from the WordPress Codex.

Don’t forget, using a plugin that allows you to alter the default user roles and capabilities will also affect your plugin(s) so if you use this then be certain to check on your plugin access for the user types.

Written by Sarah from Stuff By Sarah
Posted on April 5th, 2009 and filed under WordPress Coding & Design
Do not forget to subscribe to our RSS feed for updates

1