Monthly Archives: March 2014

Adding Main Menu and Submenu Items to WordPress Admin

This tutorial expands on a previous tutorial I wrote about Adding a Custom WordPress Admin Page and Menu Item. In this tutorial however, I will show you how to add both a main manu item and a submenu item because there is a trick to it that is very difficult to figure out just from reading the WordPress codex. That's why I figured I'd write this quick tutorial to help others.

Here's an image of a client of mine's WordPress admin where I added both a top level menu to the WordPress admin and a submenu item under it or beside it on hover:

menu example

The image above has the area we are working on with a red border added around it to make it easy to see for this tutorial.

Adding Your Action

First, you have to add an action to your functions.php file. I did this wrong the first time because I tried to add one action for the main menu item and another for the sub menu item. It turns out that is incorrect. You need to add both your main menu item and sub menu item in a single action. Your action and call back function should something look like:

add_action( 'admin_menu', 'addAdminMenu' );

function addAdminMenu(){
add_menu_page('GEE Admin Settings', 'GEE Admin', 'manage_options', 'gee_admin_settings_page', 'admin_pg_function', '', 3);
add_submenu_page('gee_admin_settings_page','User Role Editor', 'Edit User Roles','manage_options', 'user_role_editor_slug', 'edit_user_roles_function');
}

addAdminMenu Function Explained

In the above function we call both the add_menu_page and add_submenu_page functions. First lets look at the seven parameters for the add_menu_page function:

  1. 'Gee Admin Settings' - This is what shows up in the page tab of the browser. It is the title attribute for the admin page you are creating.
  2. 'GEE Admin' - This is what shows up in the left nav of the wp-admin page as the main menu item's text. You can see this in the image provided above outlined in red.
  3. 'manage_options' - This is the capability required for users to be able to access this menu item. Use manage_options here unless you know what you are doing and have reason to use another capability here. The manage_options capability is usually set aside for admin users so other roles will not have access to your admin menu items.
  4. 'gee_admin_settings_page' - This is your menu item's slug used to identify the menu item and should be unique. You will need this later to use with your submenu item.
  5. 'admin_pg_function' - This is the call back function. The call back function is the function that creates your actual admin page linked to the main menu item. It's the page that opens when you click on the main menu item.
  6. '' - You'll notice I left the sixth parameter blank by simply using two single quotes. This is because I am using the default menu icon which is the image of a gear. To use a custom icon for your menu item, include the image path and name here. This parameter is optional, but I had to include the single quotes to mark it's place due to the fact that I also included the optional seventh parameter.
  7. 3 - finally, the seventh parameter here is optional and determines the menu order. Using "3" here causes the menu item to appear directly under the "Dashboard" menu item. make the number higher to make it appear further down in the navigation bar.

Now let's look at the add_submenu_page function's parameters:

  1. 'gee_admin_settings_page' - this has to be the exact same as your main menu item's menu slug so notice how the same text is used in the add_menu_page function above it inside the AddAdminMenu function above.
  2. 'User Role Editor' - This is what shows up in the browser tab when the submenu item page is open. It is the title element for the submenu item's page.
  3. 'Edit User Roles' - This is the text for the submenu item that shows up in the left navigation bar directly under the main menu item's text.
  4. 'manage_options'  - Just like in the previous function, this is the capability the user role must have to access these menu items.
  5. 'user_role_editor_slug' - This is the menu slug for this sub menu item.
  6. 'edit_user_roles_function' - This is the call back function that creates the page linked to from the submenu item. We will discuss these functons and give examples next.

The call back functions

Now we will discuss the call back functions called within the AddAdminMenu function's inner functions of add_menu_page and add_submenu_page. The functions in this case were named admin_pg_function and edit_user_roles_function, but could be named anything, just make sure they are unique function names and that they are called inside of the add_menu_page and add_submenu_page functions respectively. Here are both function for creating the admin menu pages for the AddAdminMenu function:

function admin_pg_function(){
if(!current_user_can('manage_options')){
wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
}
/*add any form processing code here in PHP:*/
?>
<div style="width:750px;">
<h1><span style="position:relative;top:-7px">GoldEagleXpress.com Custom Admin Settings</span></h1>

<?php
/*add the rest of your page content above here if it's HTML and below here if it's PHP!*/
}/*end admin_pg_function function.*/
/*end cody by Ian L. to add custom menu item to wp-admin...*/

function edit_user_roles_function(){
if(!current_user_can('manage_options')){
wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
}
/*add any form processing code here in PHP:*/
?>
<div style="width:750px;">
<h1><span style="position:relative;top:-7px">GoldEagleXpress.com Custom User Role Settings</span></h1>

<?php
/*add the rest of your page content above here if it's HTML and below here if it's PHP!*/
}//end edit_user_roles_function function.
//############### end add main menu item to wp-admin ############

Summary

You will see if you cut and paste the code above, that it will simply create two menu items added to your navigation bar in your WordPress admin and two basically blank pages that you can go to by clicking on the new menu items. You will of course need to add some content in the last two functions here to add content to your admin pages. Good luck and happy coding!

WordPress Custom Recent Posts Widget

Here I will show you a technique I used recently to install a custom recent post widget in the footer or sidebar of your blog.

Using Short Codes:

In this tutorial, I will use the display-posts shortcode that looks like:
[display-posts include_date="true" date_format="F j, Y"]

My particular problem was that I needed a custom date format in my recent posts widget, so I used both the include_date and the date_format arguments with the display_posts shortcode.

Customizing the date format:

Where you see date_format="F j, Y" is where you can change the format, in my case I wanted to use an abbreviated month instead of the full month, so I changed "F" to "M" and accomplished just that. Here is some additional usefull information regarding date format:

Day of Month
d Numeric, with leading zeros 01–31
j Numeric, without leading zeros 1–31
S The English suffix for the day of the month st, nd or th in the 1st, 2nd or 15th.
Weekday
l Full name (lowercase 'L') Sunday – Saturday
D Three letter name Mon – Sun
Month
m Numeric, with leading zeros 01–12
n Numeric, without leading zeros 1–12
F Textual full January – December
M Textual three letters Jan - Dec
Year
Y Numeric, 4 digits Eg., 1999, 2003
y Numeric, 2 digits Eg., 99, 03
Time
a Lowercase am, pm
A Uppercase AM, PM
g Hour, 12-hour, without leading zeros 1–12
h Hour, 12-hour, with leading zeros 01–12
G Hour, 24-hour, without leading zeros 0-23
H Hour, 24-hour, with leading zeros 00-23
i Minutes, with leading zeros 00-59
s Seconds, with leading zeros 00-59
T Timezone abbreviation Eg., EST, MDT ...
Full Date/Time
c ISO 8601 2004-02-12T15:19:21+00:00
r RFC 2822 Thu, 21 Dec 2000 16:01:07 +0200

Summary:

Use the above information to form your date string and you'll be all set. When you insert a comma in the date string as in the default example above, the comma is presented literally, meaning it shows up in the date on the webpage results.

A Nicer print_r that is Pretty

Okay, today's find of the day was a simple way to print arrays to the page for testing in a much more human readable format. Until today, I always just used:

print_r($arrayname);

Well it got frustrating when dumping huge arrays and trying to decipher the infrastructure of the arrays, so I googled and found out rather quickly, that you can append and prepend the print_r function call with pre tags such as in the following PHP example code:


echo <pre>
print_r($arrayname);
echo </pre>

And WOW! what a difference that makes. Try it Mikey, you'll love it!

custom link text

Adding a Custom WordPress Admin Page and Menu Item

Here is how you can build on to your WordPress back-end and make it your own. You may also want to read my more recent and more advanced tutorial on How to Add Main Menu and Sub Menu Items to WordPress Admin right here in this same blog.

Add the Action:

First open up your functions.php file for your current theme and add the following code to initialize your function you will right next:


add_action( 'admin_menu', 'addCustomMenuItem' );

Add Function Called in Action

Next you have to add the addCustomMenuItem function you called in your action because it doesn't exist yet. You may name this function whatever you like, but be sure to replace the name in the action call above as well if you rename yours. Here is my working addCustomMenuItem function for you to build on:


function addCustomMenuItem(){

add_menu_page('Custom Admin Page Title', 'Custom Menu Title', 'manage_options', 'custom_admin_page_slug', 'pg_building_function','',3);

}//end addCustomMenuItem function.

Code explained:
Notice the add_menu_page function above takes seven parameters:

  1. Custom Admin Page Title - required to add the title element to your admin page(what shows up in the tab in browsers and inside the title tag.) You can change this to fit your page of course.
  2. Custom Menu Title - required to add the menu item to the main left nav in WP admin, see this circled in the image above. Again, change this to fit your custom page link.
  3. manage_options - This is required to tell WordPress who is allowed to view the page. You probably want to leave this be unless you know what you are doing.
  4. custom_admin_page_slug - required page slug definition. Make it whatever you wish.
  5. pg_building_function - required to name the function that creates the actual admin page you'll be adding. That's correct, you will need to wrap your admin page HTML in a PHP function. I describe this function next, so no worries.
  6. The sixth parameter is optional and you'll notice I left it blank in the example code. Leaving it blank will make it use a default icon. If you want to specify a special icon to be shown with your admin menu item's link text, then do so here, otherwise leave it blank as I have and it will often show a gear icon.
  7. The seventh parameter is also optional, but very useful if you do not want your new menu item to appear at the bottom of the menu. I used three and that seems to cause it to appear directly under the "dashboard" link in the main nav. But whatever number you put will directly correspond with the menu item's position in the menu.

Add Page Building Function

The final element in building an admin page with a menu item is adding your page building function which we already named in the last function we wrote. Notice above where we named our function pg_building_function in the add_menu_page function. Again, if you don't use pg_building_function for your function name, be sure to change it in both the above code and the below code. Here is the function to build a page that you will add your own HTML to:


function pg_building_function(){
if(!current_user_can('manage_options')){
//wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
}//end if user is allowed.
//add any form processing code here in PHP:
?>
<div style="width:750px;">
<h1><span style="position:relative;top:-7px">Custom WP-Admin Menu</span></h1>

< ?php
//add the rest of your page content above here if it's HTML and below here if it's PHP!
}//end pg_building_function function.
//############### end add main menu item to wp-admin ############

Summary

You may notice that there is no closing PHP tag. That is because I generally add new functions to functions.php at the very bottom and most of the time, functions.php leaves out the last closing PHP tag. This is all you need to get going. Install this exactly like I have laid it out and it will work. Then you may customize it to your own needs. I recommend using this code exactly at first before making any changes just so you are sure to have a working admin menu item and page.

Also, for more advanced usage cases such as adding submenu items under the main menu item, see this new tutorial I wrote called Adding Main Menu and Submenu Items to WordPress Admin.