Add items ANYWHERE to the WP 3.3 Admin Bar

The title is pretty loud and clear, we are going to see how to add new items or links to the Admin Bar. Now it does say WP 3.3, but according to the core file, this method should work well backwards up to WP 3.1.0. I believe as you reached here, you meet the following prerequisites:

• WP Action Hooks: Just what, where and how about WP Action Hooks is enough

(Do I need to add ‘You should know WordPress and PHP’ as a prerequisite?)

Okay, time to add stuff to your WP Admin Bar. Like they say ‘An image speaks a thousand words’, I’ve put images which will help you better than my blabber! 😉

The action hook that does this job is:
[php]
admin_bar_menu
[/php]

The description for this action hook in the core file ‘admin-bar.php’ is as follows:

The action “admin_bar_menu” which should be used to hook in and add new menus to the admin bar. That way you can be sure that you are adding at most optimal point, right before the admin bar is rendered. This also gives you access to the $post global, among others.

The code is very simple. If you’ve used any action hook before, you’ll find this code very similar.

[php]
//Play around with the priority of add_action to see how the item’s position can be changed within the location groups

add_action(‘admin_bar_menu’, ‘add_items’, 100);
function add_items($admin_bar)
{

/* This print_r will show you the current contents of the admin menu bar, use it if you want to examine the $admin_bar array
* echo "<pre>";
* print_r($admin_bar);
* echo "</pre>";
*/

//The properties of the new item. Read More about the missing ‘parent’ parameter below
$args = array(
‘id’ => ‘my-item’,
‘title’ => ‘My Item’,
‘href’ => ‘#’
‘meta’ => array(
‘title’ => __(‘Click Me’),
),
);

//This is where the magic works.
$admin_bar->add_menu( $args);
}
[/php]

Simple, isn’t it? We’re hooking into the action hook ‘admin_bar_menu’ using our function ‘add_items’. The WP method which allows you to add the item is ‘add_menu’. I suggest you to play around with the action’s priority to see how it suits your need. Here’s what you can try:

The $args array is as follows:

1. id: The html ‘id’ attribute for the new item.
2. title: The label for this item.
3. href: If it’s a link, then where should it go?
4. meta: This array contains the html ‘title’ attribute for the new item. It can contain other html attributes such as ‘class’, ‘tabindex’ etc.

The location group of the new item is set using a parameter called ‘parent’ in the $args array. You can adjust the item’s position further within these location groups by changing the action’s priorities as above. I’ve not used ‘parent’ as I want my item to be a brand new tab in the admin bar.

‘parent’ can have the following values:

• wp-logo: Adds the item in menu popped out from WordPress logo on the extreme left.(above the separator, after About WordPress)
• wp-logo-external: Adds the item in the menu popped out from the WordPress logo on the extreme left. (in the group below the separator – WordPress.org, Documentation etc.)
• new-content: Will add the item in the drop down menu popping out from ‘+New’. (after Post, Media, Link etc.)

• top-secondary: Will add the item to the right hand side of the Admin Bar, on the immediate left of ‘Howdy Admin’.
• my-account: Item goes in the list that pops out from ‘Howdy Admin’, in a new separate group.
• user-actions: New item is added in the same list that pops out from ‘Howdy Admin’, exactly after ‘Log Out’ and ‘Edit My Profile’.

• site-name: In the menu that pops out from your site’s name, on the left hand. (after ‘Visit Site’)

The real trick behind the ‘parent’ parameter is, if you want the new item to be a brand new tab in the admin bar, do not use ‘parent’. But if you want it to be a child of an existing item, use this existing item’s html ‘id’ attribute as a ‘parent’ for your new item. (Please note that WP adds a ‘wp-admin-bar’ prefix to the id of the outer ‘li’ tags of it’s own admin bar items, hence use the inner ‘anchor or a’ tag’s id). Using this principle, you can create a hierarchy by adding more children to your newly added item, by using it’s ‘id’ as the parent of the child items.

So if you’re using the ‘parent’ parameter with one of the above values, the $args array should look as follows:
[php]
$args = array(
‘id’ => ‘my-item’,
‘title’ => ‘My Item’,
‘href’ => ‘#’,
‘parent’ => ‘new-content’,
‘meta’ => array(
‘title’ => __(‘Click Me’),
),
);
[/php]

I guess this gives you a better way to customize your WP Admin Bar! Feel free to bash me with doubts and suggestions! Peace and adieu 2011!