Add Your Own Settings Page or Admin Menu


Many WordPress plugins require users to enter settings or options for the plugin to operate properly, and the way plugin authors accomplish this is by either adding their own settings page to an existing menu or by adding their own new top-level admin menu to WordPress.

How to Add a Settings Page

A common practice for adding your own admin settings page is to use the add_menu() hook to call the add_options_page() function:

01 add_action('admin_menu', 'myplugin_admin_menu');
02
03 function myplugin_admin_menu() {
04     $page_title = 'My Plugin Settings';
05     $menu_title = 'My Plugin';
06     $capability = 'manage_options';
07     $menu_slug = 'myplugin-settings';
08     $function = 'myplugin_settings';
09     add_options_page($page_title, $menu_title, $capability, $menu_slug, $function);
10 }
11
12 function myplugin_settings() {
13     if (!current_user_can('manage_options')) {
14         wp_die('You do not have sufficient permissions to access this page.');
15     }
16
17     // Here is where you could start displaying the HTML needed for the settings
18     // page, or you could include a file that handles the HTML output for you.
19 }

By invoking the add_options_page() function, we see that the “My Plugin” option has been added to the built-in Settings menu in the WordPress admin panel:

The add_options_page() function is really just a wrapper function on top of the add_submenu_page() function, and there are other wrapper functions that do similar work for the other sections of the WordPress admin panel:

  • add_dashboard_page()
  • add_posts_page()
  • add_media_page()
  • add_links_page()
  • add_pages_page()
  • add_comments_page()
  • add_theme_page()
  • add_plugins_page()
  • add_users_page()
  • add_management_page()

How to Add a Custom Admin Menu

Those wrapper functions work great, but what if you wanted to create your own admin menu section for your plugin? For example, what if you wanted to create a “My Plugin” admin section with more than just the Settings page, such as a Help page? This is how you would do that:

01 add_action('admin_menu', 'myplugin_menu_pages');
02
03 function myplugin_menu_pages() {
04     // Add the top-level admin menu
05     $page_title = 'My Plugin Settings';
06     $menu_title = 'My Plugin';
07     $capability = 'manage_options';
08     $menu_slug = 'myplugin-settings';
09     $function = 'myplugin_settings';
10     add_menu_page($page_title, $menu_title, $capability, $menu_slug, $function);
11
12     // Add submenu page with same slug as parent to ensure no duplicates
13     $sub_menu_title = 'Settings';
14     add_submenu_page($menu_slug, $page_title, $sub_menu_title, $capability, $menu_slug, $function);
15
16     // Now add the submenu page for Help
17     $submenu_page_title = 'My Plugin Help';
18     $submenu_title = 'Help';
19     $submenu_slug = 'myplugin-help';
20     $submenu_function = 'myplugin_help';
21     add_submenu_page($menu_slug, $submenu_page_title, $submenu_title, $capability, $submenu_slug, $submenu_function);
22 }
23
24 function myplugin_settings() {
25     if (!current_user_can('manage_options')) {
26         wp_die('You do not have sufficient permissions to access this page.');
27     }
28
29     // Render the HTML for the Settings page or include a file that does
30 }
31
32 function myplugin_help() {
33     if (!current_user_can('manage_options')) {
34         wp_die('You do not have sufficient permissions to access this page.');
35     }
36
37     // Render the HTML for the Help page or include a file that does
38 }

Notice that this code doesn’t use any of the wrapper functions. Instead, it calls add_menu_page() (for the parent menu page) and add_submenu_page() (for the child pages) to create a separate “My Plugin” admin menu that contains the Settings and Help pages:

One advantage of adding your own custom menu is that it’s easier for users to find the settings for your plugin because they aren’t buried within one of the built-in WordPress admin menus. Keeping that in mind, if your plugin is simple enough to only require a single admin page, then using one of the wrapper functions might make the most sense. But if you need more than that, creating a custom admin menu is the way to go.

Advertisements

One thought on “Add Your Own Settings Page or Admin Menu

  1. I feel that is among the so much significant information for me. And i’m glad studying your article. However should observation on few general issues, The website taste is ideal, the articles is in point of fact excellent D. Just right activity, cheers cdbeeadafbgg

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s