Subscribe Via RSS142 WordPress PK Admin Menu 0v2 A Top-level and Sub-level Menu (How-to Video)
142 WordPress PK Admin Menu 0v2 Demo Top-Level and Sub-Level Menus (Video)
Part of the "How to Write a WordPress Plugin" series
This Lesson – Overview
This lesson is part of the series covering the WordPress administration menus and options pages.
In a prior video I demonstrated the very basics of how to make an Administration Menu by producing a plugin which added a sub-menu and admin page to the existing WordPress Settings Menu.
In this lesson we will go a step further with admin menus and demonstrate how to create a custom top-level menu with two sub-menus and add sub-menus to the Settings and Tools top-level menus.
With this information you will have all the information you need to produce your own admin menus and options pages for your plugins.
In the next lesson I will demonstrate how to save your admin options to the database and expand upon the, Text to Hyperlink, example.
Contents
- 110 WordPress Plugin Naming and Declaration (How-to Video)
- 120 The Plugin Class (How-to Video)
- 130 WordPress Hooks, Actions and Filters (How-to Video)
- 131 Text to Hyperlink Filter Example (How-to Video)
- 140 WordPress Administration Menus/Panels/Pages (How-to Video)
- 141 WordPress PK Admin Menu 0v1 Demo – A Simple Sub Menu (How-to Video)
- 142 WordPress PK Admin Menu 0v2 A Top-level and Sub-level Menu (How-to Video)
- 143 Admin Menu 0v3 Text to Hyperlink (How-to Video)
- 150 Database
- 161 Javascript Inclusion with Plugins
- 162 CSS Inclusion with Plugins
- 170 Plugin Release and Promotion
Objectives
So, in this lesson we will create the following menu items, a new submenu for both the Settings and Tools top-level menus. A new Custom top-level menu containing two sub-level menus and an options page for each menu item.
- Settings menu:
- Add a new submenu, page and message.
- Tools menu:
- Add a new submenu, page and message.
- Custom menu:
- Add a custom top-level menu
- Add a submenu to the custom top-level menu, page and message.
- Add a second submenu to the custom top-level menu, page and message.
- Add a custom top-level menu
Example PK Admin Menu 0v2
Once again, we will follows the three steps discussed in previous lessons to create these WordPress administration menus.
Step 1
- Step 1 in the process is to create a function that contains the menu-building code, pk_add_pages() in this example. This contains five function calls whose purpose is to add the various menus we require to the dashboard menu structure.
- Function add_options_page() will add the sub-menu ‘PK Test Settings‘ to the Settings top-level menu and call the, pk_test_settings_page() to display the options page.
- Notice that internationalisation has not been included for demonstration purposes with lesson. We will be covering this topic in more detail in a later lesson. If you would like to read more on this top see the WordPress Codex.
// Add a new submenu under top-level Settings menu:
add_options_page('PK Test Settings', // page title
'PK Test Settings', // menu title
'manage_options', // capability
'testsettings', // menu slug
array($this, 'pk_test_settings_page')); // function call
- Function add_management_page() will add the sub-menu ‘PK Test Tools’ to the Tools top-level menu and call the pk_test_tools_page() to display the options page.
// Add a new submenu under top-level Tools menu:
add_management_page('PK Test Tools',
'PK Test Tools',
'manage_options',
'testtools',
array($this, 'pk_test_tools_page'));
- Function add_menu_page() specifically, creates a new top level menu section in the Dashboards admin menu sidebar.
- We will use this function to add the top-level menu ‘PK Test Toplevel‘ to the Dashboards admin menu structure and call the pk_test_toplevel_page() function to display the related options page.
- Unless you have a very good reason to add a top-level menu WordPress recommends placing your menus within the existing dashboard structure.
- Notice you could designate an icon and menu position with the menu structure but I would recommend simply accepting the default.
// Add a new top-level menu:
add_menu_page('PK Test Toplevel', // page title
'PK Test Toplevel', // menu title
'manage_options', //capability
'pk-top-level-handle', // menu slug
array($this, 'pk_test_toplevel_page' ) // function
// icon url (optional)
// position (optional)
);
- The two function calls to add_submenu_page() will add the sub-menus ‘Test Sublevel 1‘ and ‘Test Sublevel 2‘ to our custom top-level menu. Options pages ‘pk_sublevel_1_page‘ and ‘pk_sublevel_2_page‘ will be called when actioned.
// Add a submenu to the custom top-level menu:
add_submenu_page('pk-top-level-handle',
'Test Sublevel 1',
'Test Sublevel 1',
'manage_options',
'sub-page',
array($this, 'pk_sublevel_1_page'));
// Add a second submenu to the custom top-level menu:
add_submenu_page('pk-top-level-handle',
'Test Sublevel 2',
'Test Sublevel 2',
'manage_options', 'sub-page2',
array($this, 'pk_sublevel_2_page'));
Step 2
- In Step 2 we simply register the above function pk_add_pages() using the "admin_menu" action hook. Notice this is simply an add_action() interrupt function again.
// Step2: Register the menu building code function
add_action('admin_menu', array($this, 'pk_add_pages'));
Step 3
- In step 3 we create the HTML code for the pages to be displayed when the menu items are clicked. This step is actioned by the five functions, pk_test_setting_page(), pk_test_tools_page(), pk_test_toplevel_page(), pk_sublevel_1_page(), and pk_sublevel_2_page(). In this example we simply output the menu name in HTML on each options page.
- There is a point worth noting here,:
Each function should always check to see if the user has permission to view each of the options pages before doing anything else but for clarity I’ve included the necessary if() statement in the pk_test_setting_page() only.
// Step3: Create the HTML code for the page to be displayed
// pk_test_setting_page() displays page content for PK Test Settings submenu
function pk_test_setting_page() {
echo "<h2>" . 'PK Test Settings' . "</h2>";
}
// pk_test_tools_page() displays page content for PK Test Tools submenu
function pk_test_tools_page() {
echo "<h2>" . 'PK Test Tools' . "</h2>";
}
// pk_test_toplevel_page() displays page content for the custom Top-level menu
function pk_test_toplevel_page() {
echo "<h2>" . 'PK Test Toplevel' . "</h2>";
}
// pk_sublevel_1_page() displays the page content for the first submenu
// of the custom PK Test Toplevel menu
function pk_sublevel_1_page() {
echo "<h2>" . 'Test Sublevel 1' . "</h2>";
}
// pk_sublevel_2_page() displays the page content for the second submenu
// of the custom PK Test Toplevel menu
function pk_sublevel_2_page() {
echo "<h2>" . 'Test Sublevel 2' . "</h2>";
}
This code, when inserted into our plugin class template, will add the top-level menu and sub-level menu items as indicated.
When selected each menu item will display its custom options page which in this instance just contains the menu name.
Practical Eclipse Exercise (pk-admin-menu-0v2)
OK, lets see how to implement this code using our class template.
Create a New Plugin
To begin we need to use our plugin class template to create a new plugin which we’ll call pk-admin-menu-0v2 so copy the pk-plugin-class template we created previously to a new folder in the wp-content\plugins folder and rename the folder to pk-admin-menu-0v2 and the file to pk-admin-menu-0v2.php. Remember the plugin file name should be the same name as the folder with the PHP extension.
Then open the file ready for editing.
Enter a New Plugin Name and Description
The first thing we need to do with our new plugin is enter a new plugin name and description. so that WordPress with recognize the plugin.
Plugin Name: PK Admin Menu 0v2
Description: PK Admin Menu 0v2 Demonstration of Top and Sub-menus.
Enter New Class Name
Enter a more appropriate class name by renaming all occurrences of the pk_plugin_template_class to pk_admin_menu_0v2_class. There are six changes to be made.
Enter New Instance Name
Now that we have our plugin class we need an instance of that class. So change the template instance $pk_plugin_demo to a more appropriate name, $pk_admin_menu_0v2_demo.
Enter Hook (Step 2)
Next, we need to hook our menu building function into WordPress so enter the add_action() hook for the admin_menu call, just after the placeholder comment,
// TODO: Enter Plugin Actions and Filters here
// Step2: Register the menu building code function
add_action('admin_menu', array($this, 'pk_add_pages'));
Enter Menu Building Code Function (Step 1)
Now enter the menu building code action function, ‘pk_add_pages‘, just after the placeholder comment,
// TODO: Enter Action and Filter Methods here
// Step1: Menu-building code action function for above hook
function pk_add_pages() {
// Add a new submenu under top-level Settings menu:
add_options_page('PK Test Settings',
'PK Test Settings',
'manage_options',
'testsettings',
array($this, 'pk_test_setting_page'));
// Add a new submenu under top-level Tools menu:
add_management_page('PK Test Tools',
'PK Test Tools',
'manage_options',
'testtools',
array($this, 'pk_test_tools_page'));
// Add a new top-level menu:
add_menu_page('PK Test Toplevel',
'PK Test Toplevel',
'manage_options',
'pk-top-level-handle',
array($this, 'pk_test_toplevel_page' ));
// Add a submenu to the custom top-level menu:
add_submenu_page('pk-top-level-handle',
'Test Sublevel 1',
'Test Sublevel 1',
'manage_options',
'sub-page',
array($this, 'pk_sublevel_1_page'));
// Add a second submenu to the custom top-level menu:
add_submenu_page('pk-top-level-handle',
'Test Sublevel 2',
'Test Sublevel 2',
'manage_options', 'sub-page2',
array($this, 'pk_sublevel_2_page'));
}
Enter Html Page Options (Step 3)
Continue by entering the function which will actually display the HTML code containing our menu options.
// Step3: Create the HTML code for the page to be displayed
function pk_test_setting_page() {
echo "<h2>" . 'PK Test Settings' . "</h2>";
}
// pk_test_tools_page() displays the page content for the PK Test Tools submenu
function pk_test_tools_page() {
echo "<h2>" . 'PK Test Tools' . "</h2>";
}
// pk_test_toplevel_page() displays the page content for the custom PK Test Toplevel menu
function pk_test_toplevel_page() {
echo "<h2>" . 'PK Test Toplevel' . "</h2>";
}
// pk_sublevel_1_page() displays the page content for the first submenu
// of the custom PK Test Toplevel menu
function pk_sublevel_1_page() {
echo "<h2>" . 'Test Sublevel 1' . "</h2>";
}
// pk_sublevel_2_page() displays the page content for the second submenu
// of the custom PK Test Toplevel menu
function pk_sublevel_2_page() {
echo "<h2>" . 'Test Sublevel 2' . "</h2>";
}
Save the File
With the code entered, lets save the file, and see what happens in WordPress.
Login to WordPress
Login to WordPress as the administrator and navigate to Dashboard > Plugins > Installed Plugins and check the plugin has been recognised but is inactive.
Activate the plugin and check each of our menu items in the Tools, Settings and custom PK Test Toplevel, menus are working. Check each menu item activates its associated option page. This is of course where you would place your page of options, help information, etc.
With, everything working as planed, deactivate the plugin, and check that all our menu items have been removed.
Conclusion – Summary
Hopefully this tutorial gave you a good insight into how simple an administration menu can be.
In the next lesson we will take our Text to Hyperlink tutorial a stage further, add a more complex admin interface and save our data to the WordPress database.
Well, that’s all for this tutorial on Administration menus, see you in the next lesson.
Links Used in This Article
http://codex.WordPress.org/Function_Reference/add_menu_page
http://codex.WordPress.org/Function_Reference/add_options_page
http://codex.WordPress.org/Function_Reference/add_submenu_page
http://codex.WordPress.org/Plugin_API/Action_Reference/admin_menu
http://codex.WordPress.org/Roles_and_Capabilities#Capabilities
http://codex.WordPress.org/Translating_WordPress
Lesson Code (pk-admin-menu-0v2)
<?php
/*
Plugin Name: PK Admin Menu 0v2
Plugin URI: http://kingsolutions.org.uk/wordpress/wordpress/how-to-write-a-wp-plugin/
Description: PK Admin Menu 0v2 Demonstration of Top-level and Sub-level admin menus.
Version: 0.1
Author: Philip King
Author URI: http://kingsolutions.org.uk/wordpress/
Licence: Licence GPL2
*/
/* Copyright 2011 Philip King (contact: http://kingsolutions.org.uk/wordpress/)
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, version 2, as
published by the Free Software Foundation.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
/**
* The Plugin Class
*/
if (!class_exists("pk_admin_menu_0v2_class")) {
class pk_admin_menu_0v2_class {
// TODO: Variable declarations go here
// TODO: Constructor
function __construct() {
// TODO: Enter Plugin Actions and Filters here
// Step2: Register the menu building code function
add_action('admin_menu', array($this, 'pk_add_pages'));
} // End constructor
// Core functions go here
// TODO: Enter Action and Filter Methods here
// Step1: Menu-building code action function for above hook
function pk_add_pages() {
// Add a new submenu under top-level Settings menu:
add_options_page('PK Test Settings',
'PK Test Settings',
'manage_options',
'testsettings',
array($this, 'pk_test_settings_page'));
// Add a new submenu under top-level Tools menu:
add_management_page('PK Test Tools',
'PK Test Tools',
'manage_options',
'testtools',
array($this, 'pk_test_tools_page'));
// Add a new top-level menu:
add_menu_page('PK Test Toplevel',
'PK Test Toplevel',
'manage_options',
'pk-top-level-handle',
array($this, 'pk_test_toplevel_page' ));
// Add a submenu to the custom top-level menu:
add_submenu_page('pk-top-level-handle',
'Test Sublevel 1',
'Test Sublevel 1',
'manage_options',
'sub-page',
array($this, 'pk_sublevel_1_page'));
// Add a second submenu to the custom top-level menu:
add_submenu_page('pk-top-level-handle',
'Test Sublevel 2',
'Test Sublevel 2',
'manage_options', 'sub-page2',
array($this, 'pk_sublevel_2_page'));
}
// Step3: Create the HTML code for the page to be displayed
// pk_test_settings_page() displays page content for PK Test Settings submenu
function pk_test_settings_page() {
echo "<h2>" . 'PK Test Settings' . "</h2>";
}
// pk_test_tools_page() displays page content for PK Test Tools submenu
function pk_test_tools_page() {
echo "<h2>" . 'PK Test Tools' . "</h2>";
}
// pk_test_toplevel_page() displays page content for custom Top-level menu
function pk_test_toplevel_page() {
echo "<h2>" . 'PK Test Toplevel' . "</h2>";
}
// pk_sublevel_1_page() displays the page content for the first submenu
// of the custom PK Test Toplevel menu
function pk_sublevel_1_page() {
echo "<h2>" . 'Test Sublevel 1' . "</h2>";
}
// pk_sublevel_2_page() displays the page content for the second submenu
// of the custom PK Test Toplevel menu
function pk_sublevel_2_page() {
echo "<h2>" . 'Test Sublevel 2' . "</h2>";
}
// TODO: Enter Helper Methods here
} // End pk_admin_menu_0v2_class
} // End if (!class_exists("pk_admin_menu_0v2_class"))
/**
* Instantiate (create an instance of) the class
*/
if (class_exists("pk_admin_menu_0v2_class")) {
// TODO: Enter New Instance Name
$pk_admin_menu_0v2_demo = new pk_admin_menu_0v2_class();
} // End instantiate class
?>
