Admin Bar API changes in 3.3

Howdy! The Adminadmin (and super admin) Bar APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. has changed quite a bit in WordPress 3.3.

First up, what may break your pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party. The added items are no longer stored in a publicly accessible (but ideally privately used) menu property. So, if you were doing something like $wp_admin_bar->menu->..., you won’t get anything back.

The reason for this is that the internal structure has changed. Nodes are no longer internally stored in a tree. Now, they’re stored in a flat list, and the tree is bound together just before render. This makes the internal API much more stable, and allows us to provide plugin developers some nifty new tools. Even coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. only handles nodes using the same APIs developers use (mostly).

If you were to open the file you will notice there are a number of new methods and signatures. Here are the ones developers will want to know:

  • Add a node: add_node( $args ) or add_menu( $args ) (these are equivalent)
  • Remove a node: remove_node( $id ) or remove_menu( $id ) (these are equivalent)
  • Fetch a node’s properties: get_node( $id ).
  • Add a group, which wraps nodes (more on that in a bit): add_group( $args ).

Terminology notes

Before I continue: I’m using “item,” “node,” and “menu” synomyously throughout this post. They all are referring to a single link in the admin bar. Nodes can be parents for other nodes, which creates dropdown menus. The API previously emphasized add_menu(), but this can be confusing, so add_node() is now being promoted a bit more. Both methods do the same thing.

Since the optional admin bar has been merged into the admin headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes., we’re now calling it the toolbar in the UIUI User interface.


An example of groups in the new toolbar.

Version 3.3 introduces the concept of groups. Groups share the same namespace (in terms of IDs) as nodes, and a node’s parent can be a group, rather than another node. Groups allow us to group nodes together into distinct sections of a menu. As an example, see the new W menu in the top left of the toolbar (screenshot at right). Here’s how it was constructed:
  • The W logo node is added. It has no parent.
  • The “About WordPress” node is added. To create a submenu, we set the parent to the W logo.
  • We add a group for external links. The group’s parent is also the W logo. It uses an additional CSSCSS Cascading Style Sheets. class to add the gray styling.
  • We then add the four external links, and set their parent to the external links group.

You can see these registrations in wp_admin_bar_wp_menu() and wp_admin_bar_add_secondary_groups().

Groups were added to provide us some styling flexibility and semantic divisions for a few different menus. (The right side of the top menu, “Howdy” and search, are their own group.) But the possibilities for plugins are pretty great. A plugin can bundle all of their nodes into a single group that then maintain visual separation from all other nodes in that menu. You can use the add_group() method to add groups.

Moving and modifying nodes

While this isn’t a change from WordPress 3.2, it’s worth pointing out that add_node() is able to take the ID of an existing node as an argument, and then replace the specified arguments. For example, if you want to make the Networknetwork (versus site, blog) Admin level a top-level item, try this:

add_action( 'admin_bar_menu', 'nacin_promote_network_admin_in_toolbar', 25 );
function nacin_promote_network_admin_in_toolbar( $wp_admin_bar ) {
    $wp_admin_bar->add_node( array(
        'id' => 'network-admin',
        'parent' => false,
    ) );

That was easy!

To make modifications easier, there’s now a get_node() to fetch a node’s properties, and even get_nodes() to fetch a flat list of all nodes, in case you want to loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. through them.

#3-3, #dev-notes