Genesis Explained Admin Menu

As noted in the first article in this sub-series, Genesis Explained Admin, this article will be starting the menu.php file. Also noted there I mentioned that this file sets up the Genesis Menu in the WordPress dashboard, allowing other pages to be added to this menu. There are only two functions here, but I’m going to also explain how to add your own menu item to this menu.

genesis_add_admin_menu()

This function is part of an action hook on the “admin_menu” hook. That is a WordPress API hook that is responsible for creating the dashboard menu. genesis_add_admin_menu does exactly that. It adds the “Genesis” Menu item. You will notice that the function stops (return) if the theme does not support genesis-admin-menu. This allows the child theme to short cut this entire menu by removing theme support for genesis-admin-menu.

After a check to ensure the user can access teh menu and a setup of the menu seperator, the menu is added with the add_menu_page() function. This function loads the genesis_theme_settings_admin() function, which creates the Genesis Settings page. We’ll discuss that in greater detail in the next article.

Other thank short-cutting this menu, there isn’t much else you can do without removing the menu action with remove_action() and putting in your own menu. This might be desirable if you are trying to brand the theme for your clients, but I’d recommend leaving in Genesis as this menu may have to change to keep up with changes to how WordPress integrates with the menu API. For example, WordPress 3.2 changed this by adding the menu position points.

genesis_add_admin_submenus

This function loads the basic menus included with the theme. You will notice the two global pagehook variables at the top of the menu. These are set in the menu and allow you to tie into those values in your own functions. If you look, you will also see the current_theme_support checks and a test to make sure teh current user is allowed to access the menu before loading the menu items for the SEO Settings and Import/Export sub menu. This means you can short circuit this with remove_theme_support() to prevent the menu from showing. The README sub menu checks to see if the file exists in addition to checking for theme support.

All of these use the add_submenu_page() function to tie into the existing top level menu. The various functions linked to, such as “genesis_theme_settings_admin” will be covered in more detail in the coming articles.

Adding your own sub menu

Adding your own sub menu is pretty easy. I’m going to use my Genesis Simple Breadcrumbs plugin as an example since it is a very straight forward plugin, and adds a sub menu. If you open the plugin.php file and jump past all the activation checks you will find this at the bottom

add_action( 'genesis_init', 'gsb_init', 15 );
/** Loads required files when needed */
function gsb_init() {

    if ( is_admin ( ) )
        require_once(GSB_PLUGIN_DIR . '/admin.php');

    else
        require_once(GSB_PLUGIN_DIR . '/output.php');

}

This action serves two important purposes. First, it moves everything to after the Genesis functions have been setup. A change in Genesis 1.6 so that the Framework could be streamlined, only loading code when needed, makes this necessary. The other purpose is to also make the plugin nice and clean. Admin functions are loaded via the admin.php file only when in the admin side of the site. Front end operation are loaded in output.php only when on the front end of the site. This is much more efficient than loading all the functions all the time.

OK, now open the admin.php file. There are some defaults and a definition that are at the top of the file, but after that, you will see this action

add_action('admin_menu', 'gsb_settings_init', 15);
function gsb_settings_init() {
	global $_gsb_settings_pagehook;

	// Add "Simple Breadcrumbs" submenu
	$_gsb_settings_pagehook = add_submenu_page('genesis', __('Simple Breadcrumbs','GSB'), __('Simple Breadcrumbs','GSB'), 'manage_options', 'gsb', 'gsb_settings_admin');

	add_action('load-'.$_gsb_settings_pagehook, 'gsb_settings_scripts');
	add_action('load-'.$_gsb_settings_pagehook, 'gsb_settings_boxes');
}

Notice I tie into the admin menu, just like the Genesis action does. Then I set a global pagehook. This makes the return value from add_submenu_page available in other functions I will use to create my page. Line 6 creates the submenu with add_submenu_page().

The parent_slug is “genesis” and the page title is “Simple Breadcrumbs.” This is the Title that shows up on the page itself. Next is the menu title, which is also Simple Breadcrumbs and the capability is set as “manage_options” which is related to what the user is allowed to do. Finally we have the menu slug “gsb” and the function that will actually load the page content “gsb_settings_admin.” I will go into how these functions work in more detail in the next article.

The function ends with two actions. The first loads the scripts that will be used in the Simple Breadcrumbs page, and the second loads the settings boxes that will be used in the Simple Breadcrumbs page, but again, more on that later.

For now, you should be able to follow on the basics of how to add your own menu.

Remember, sign up for the email updates on the right sidebar, or subscribe to the feed so you get the latest updates. Also, watch for details on the Genesis Explained: a Developer’s Guide to Genesis, which will be coming soon.