Diving deeper into the wordpress admin – The Admin Toolbar


Posted on August 8th, 2012

Note:

This post is abondoned. I have stopped working on wordpress projects and as such I no longer keep track of wordpress related things.


I really like the new admin toolbar that came with wordpress 3.3. It is a significant improvement over its predecessor “admin bar", which came with wordpress 3.0. I have met some (not many) developers who dislike this new addition. Regardless of your personal choice, as a developer, I think that you should make an effort to familiarize yourself with it; mainly because with new toolbar API your theme and plugin can do so much with it.

In this post we are going to see how our theme and plugin can interact with admin toolbar. We will hide it, show it, remove items from it, and add items (with dropdown, and icons) in it — all programmatically.

First let’s identify some of its characteristics:

  • It’s enabled by default in both front end and back end sides.
  • It can be disabled in front end side, but not in back end side. Admins can disable it by going in their profile settings page.
  • It has two positions to add menu items: left and right.
  • Main files that control the toolbar are: wp-includes/admin-bar.php, and wp-includes/class-wp-admin-bar.php

Now without any further delay, let’s dive in.

###Hide/Show the toolbar (programmatically) To hide or show it in front end you can use the function show_admin_bar().

To hide it place this code in your theme/plugin:

<?php show_admin_bar(false);

To show it place this code in your theme/plugin:

<?php show_admin_bar(true);

Note 1: As I mentioned above, it can only be disabled in front end side, so above code will have no effect on the back end side.

Note 2: It will override user’s settings (Profile Setting for toolbar frontend display). So if admin choose in her profile page to disable it and you place above code in your theme to enable it, it will be enabled.

###Remove menu items

To remove items from the toolbar we will hook into admin_bar_menu action.

<?php
function tt_remove_toolbar_menu_items() {
    global $wp_admin_bar;
    $wp_admin_bar->remove_node('wp-logo'); 
    $wp_admin_bar->remove_node('new-media'); 
    $wp_admin_bar->remove_node('new-link'); 
    $wp_admin_bar->remove_node('my-account'); 
}
add_action('admin_bar_menu','tt_remove_toolbar_menu_items', 500);

This is a snapshot of the toolbar before I placed above code, and this one was taken after.

As you can see I removed WordPress Logo, New > Media, New > Link, and My Account (‘Howdy! Admin’, with avatar in the right) menu items.

$wp_admin_bar->remove_node() function takes the menu item id as its only argument. How did I know their respective ids? I checked wp-includes/admin-bar.php file. There is a simpler way to find out the id of the menu item you want to remove. See the html source of the toolbar. In this snapshot you can see how one can get the ids (I am using firebug extension in firefox).

###Add Menu Items

We again plug into admin_bar_menu hook and add some menu items. Place the following code in your theme/plugin:

<?php
function tt_add_toolbar_menu_items() {
    global $wp_admin_bar;
    $wp_admin_bar->add_node(array(
        'id' => 'tt-options',
        'title' => 'Twenty Eleven Options',
        'href' => admin_url('themes.php?page=theme_options')
    ));
    $wp_admin_bar->add_node(array(
        'id' => 'tt-options-header',
        'parent' => 'tt-options',
        'title' => 'Header',
        'href' => admin_url('themes.php?page=custom-header')
    ));
    $wp_admin_bar->add_node(array(
        'id' => 'tt-options-background',
        'parent' => 'tt-options',
        'title' => 'Background',
        'href' => admin_url('themes.php?page=custom-background')
    ));

    $wp_admin_bar->add_group(array(
        'id' => 'tt-external-links', 
        'parent' => 'tt-options', 
        'meta' => array('class' => 'tt-external-links-c')
    ));
    $wp_admin_bar->add_node(array(
        'id' => 'tt-options-facebook',
        'parent' => 'tt-external-links',
        'title' => '<span class="ab-icon" style="background: transparent url(' . get_theme_root_uri() . '/twentyeleven/images/facebook_16.png) no-repeat top left;"></span><span class="ab-label">Facebook</span>',
        'href' => 'http://www.facebook.com'
    ));        
    $wp_admin_bar->add_node(array(
        'id' => 'tt-options-wordpress',
        'parent' => 'tt-external-links',
        'title' => '<span class="ab-icon" style="background: transparent url(' . get_theme_root_uri() . '/twentyeleven/images/wordpress.png) no-repeat top left;"></span><span class="ab-label">Wordpress</span>',
        'href' => 'http://www.wordpress.org'
    ));
}
add_action('admin_bar_menu','tt_add_toolbar_menu_items', 500);

I am placing these code samples in twenty eleven theme and it will add the following menu structure:

Twenty Eleven Options (Points to twenty eleven options page) – Header (Points to Header Options Page) – Background (Points to Background Page) – Facebook (With facebook icon, points to Facebook home page) – WordPress (With wordpress icon, points to WordPress.org home page) Facebook and WordPress items are grouped together (as external links). Note that external links group is displayed a little differently. This is the snapshot of the toolbar after above code was added.

$wp_admin_bar->add_node() function takes one argument: an array containing all the information about the menu you are adding.

Here is the list of information that you can provide in that array:

  • id – string – The ID of the item.
  • title – string – The title of the item.
  • parent – string – The ID of the parent item. Optional. If not provided then menu will be added as top level menu in left hand side. If “top-secondary" is provided then menu will be added as top level menu in right hand side.
  • href – string – The link for the item. Optional.
  • group – boolean – If the node is a group. Optional. Default false.
  • meta – array – Meta data including the following keys:
    • html – string – If provided this html will be placed after the menu’s “a" tag.
    • class – string – Any required css class for the menu item
    • onclick – string – Any required javascript onclick handler
    • target – string – The target attribute of “a" tag
    • title – string – The title attribute of “a" tag
    • tabindex – string – The tabindex attribute of “a" tag

The only thing above which is not obvious is the “group" attribute. Group node is a parent node which can contain other menu items as children, but which itself won’t be displayed. It may only be used where you need to group several menu items together. For example: When you are adding your theme options menu in the toolbar, then it may make some sense to group menu items into two groups: functionality and skin. It is a nice way to show that these menu items are part of a group. All the menu items are grouped together and shown a little differently (you can see it in the snapshot provided above).

$wp_admin_bar->add_group($menuArgs) is a shortcut function for adding a group. It automatically updates the provided $menuArgs array and adds “group" => true.

Placing menu item in the right hand side of the toolbar

To place a menu in the right hand side of the toolbar (like My Account menu), set “parent" of the top-most menu to “top-secondary". If, for example, I update above code like this:

<?php
$wp_admin_bar->add_node(array(
        'id' => 'tt-options',
        'parent' => 'top-secondary', // this will place menu in the right hand side
        'title' => 'Twenty Eleven Options',
        'href' => admin_url('themes.php?page=theme_options')
    ));

Then the new menu will be on the right hand side. See the snapshot.

Icons in menu item

To insert an icon in your menu item, add this html in place of simple “title" attribute.

<span class="ab-icon" style="background: transparent url(Your–Icon-URL-Here) no-repeat top left;"></span>
<span class="ab-label">Your-Title-Here</span>

Preferred size for icon is 16×16 px. Css classes “ab-icon" and “ab-label" are pre-defined in wordpress core. You can just attach your icon and be done with it. See in the above code, how I used it in Facebook and WordPress menu items.

###Closing Thoughts Admin toolbar is different from the admin menus (see the snapshot) in its space availability. While admin menus area will stretch (as it is vertical) to accommodate as many menu items you place there, admin toolbar has limited space. What this means is we should not place non-essential items on the toolbar.

Plugin developers need to be more concerned about this than theme developers, for there can only be one theme installed at one time, but this is not the case with plugins. Admin can have many plugins installed and if the majority of them have added unnecessary menus in the toolbar, it will break (see the snapshot).

Instead of adding new top-level menu, consider adding your menu as a child to the existing core menus. For example: If my plugin is about book database, and I want to add a menu “New Book", I can add it to the “New" core menu, instead of creating a new top level menu. Some circumstances will require a top level menu, all we can hope to do is to judge responsibly if our plugin do need a top level menu.

In the comment section below, tell me what you think about the new toolbar. As a wordpress admin, do you like it? And if you are a theme/plugin developer then will you consider manipulating it?

Share

If you liked this article then please consider sharing it.

comments powered by Disqus