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
[sourcecode language=”php”]add_options_page(Page Title, Menu Title, user level / capability, file, function name, icon url);[/sourcecode]
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
[sourcecode language=”php”]add_management_page(Page Title, Menu Title, user level / capability, file, function name, icon url);[/sourcecode]
and for adding a page to the Theme management section we use
[sourcecode language=”php”]add_theme_page(Page Title, Menu Title, user level / capability, file, function name, icon url);[/sourcecode]
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
[sourcecode language=”php”]add_submenu_page(Parent File, Page Title, Menu Title, user level / capability, file, function name, icon url);[/sourcecode]
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
[sourcecode language=”php”]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);[/sourcecode]
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
[sourcecode language=”php”]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’);[/sourcecode]
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.
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.