Modifying the WP Toolbar

WordPress’ API for the toolbar (or the admin bar, as it was formerly known) has changed a bit since version 3.3. Since there is no documentation in the Codex, I thought I’d make some notes here.

First, check out this basic tutorial on SitePoint to get an idea of the API. For more info, check out this post on the WP developer blog — it is the only “official” documentation I could find.

When making changes, watch out for these subtle differences and options:

• Instead of using the global $wp_admin_bar, your action hook should instead take an argument (e.g., $toolbar) that will contain a WP_Admin_Bar object.
• The various default nodes are created in action hooks called with priorities anywhere from 1 to 200. Therefore, if you want to modify the default nodes that WP creates, it’s best to call your action hook with a late priority (such as 999).
• If you’re modifying an existing node, you can just call add_node() with the same ID — it will automatically replace the existing node. If you delete the node and then re-add it, it will appear after all the other nodes in that hierarchy. (You can’t specify a position in the toolbar for a node.)
• The argument you pass to add_node() can be an associative array or an object with properties — either will work.

To read through the toolbar code, check out wp-includes/class-wp-admin-bar.php.