Codeable info

Adding to the WordPress Toolbar

Posted on by in WordPress Tutorials

add wp toolbarLog in to almost any WordPress site, and what do you see at the top of every page? The toolbar. Formerly known as the “Admin Bar,” the Toolbar gives any user a central location for quick access to their profile, and can provide higher-level users links to various areas of the administrative interface as well as displaying various statistics and links about ongoing events. This ease of navigation around a website built with WordPress makes the Toolbar an important tool for any developer that wants to allow users to quickly access various resources. To accomplish this, you will need some experience with PHP and hooking into WordPress functions.

How the Toolbar is Useful

The Toolbar is useful for more than just signing out or going to the dashboard. It gives developers the opportunity to provide shortcuts on the front-end of a website. Some well-known plugins, such as Jetpack, W3 Total Cache, and WordPress SEO, take advantage of the Toolbar to display information or provide navigation shortcuts to some important functions of either the plugin or the current page being viewed.

Let us look at the three plugins mentioned in the previous paragraph to see just how they take advantage of the opportunity presented by the Toolbar’s presence on every page. Jetpack, by default, will place a chart in the front-end that displays the amount of views a website has received over the previous forty-eight hours. Doing so gives a user with permission to view stats the ability to quickly see if there are any recent trends around the amount views, and allows an administrator to take action if he or she notices an abnormal trend within the hourly rate of views. W3 Total Cache places a link to its configuration area, a link to immediately flush any and all cached content, and some informational links. If an administrator notices a problem that may be caused by a fault with the caching system, he or she can clear the cache and see if that resolves the problem, aiding in the diagnostic process by eliminating extra clicks. WordPress SEO has many links in its Toolbar menu. WordPress SEO has links to quickly conduct searches about keywords, analyze several search engine-oriented aspects about the page currently being viewed, and edit plugin settings.

Those are three examples of how the Toolbar can be useful to plugin developers, but the Toolbar can be a very important tool to any WordPress administrator as well. It has many features that some may overlook, and some of the most important features to look at are the available upgrade button, the review comments button, and the “New” menu. The available upgrade button will only appear if your website has an available plugin, theme, or core update. The review comments button is always there for those with sufficient permissions, and will display a number inside of the speech bubble whenever comment moderation is required. If there is no number, then no action is necessary. The “New” menu has links to create a new post, page, link, or user, or to upload a new media file. The upgrade and comment buttons provide instant information as to if any maintenance is necessary, while the “New” menu reduces the amount of clicks needed between any page and content creation.

Another incredibly useful feature of the Toolbar is the “Edit” link which appears when you are viewing any page, post, or attachment. If your theme does not have an edit link built-in, this link in the Toolbar will take you directly to the edit page for that content. Again, reducing the amount of time required to modify any content and correct any errors.

Adding a Simple Node

Adding a simple menu or link to the Toolbar requires the use of only one function.

$wp_admin_bar->add_node( $args )

adds a new “node,” or element, to the Toolbar. An example of this function creating a new simple node is shown below.

add_action( 'admin_bar_menu', 'my_toolbar_node', 999 );
function my_toolbar_node( $wp_admin_bar ) {
	global $wp_admin_bar;
	$args = array(
		'id' => 'my_settings_page',
		'title' => 'My Settings Page',
		'href' => menu_page_url('my_settings_slug'),
		'meta' => array(
			'class' => 'my-toolbar-link',
			'title' => 'My Settings Link Title'
		)
	);
	$wp_admin_bar->add_node($args);
}

The function $wp_admin_bar->add_node() works by making sure that you have provided an ID for this new node, then checks to see if this node already exists. If it finds that a node with the ID your provide already exists, this function will overwrite that node with the arguments explicitly provided by your script. Once the housework is completed, this function will add the new node to a property that will be later used to render the Toolbar during a page load. The way that this function is written allows you to overwrite a node that already exists. If you do not want to overwrite said node, then you can call $wp_admin_bar->get_node() inside of an “if” statement, passing the ID of the node in question as the only argument. A brief example is demonstrated below.

add_action( 'admin_bar_menu', 'my_toolbar_node', 999 );
function my_toolbar_node( $wp_admin_bar ) {
	global $wp_admin_bar;
	$updates_node = $wp_admin_bar->get_node('my_settings_page');
    	if(!$updates_node) {
		$args = array(
			'id' => 'my_settings_page',
			'title' => 'My Node'
		);
		$wp_admin_bar->add_node($args);
	}
}

The arguments that

$wp_admin_bar->add_node()

will accept for each new node are: id, title, parent, href, group, and meta, with meta being another array with the additional arguments of html, class, onclick, target, title, and tabindex. The argument “ID” is a string that will identify the node within the property used to render the Toolbar. The “title” argument will be the text displayed in the Toolbar, unless overridden later by the “html” string of the “meta” array, which will be covered in the next section. The “parent” argument is to be passed only if you define two or more nodes and want one node in particular to be the parent of the others. You would accomplish this by passing the parent node’s ID as a string in this argument. The argument “href” is the link location of the node being created. If there is no “href” argument, then this node will not be a link, but only display what is passed in the “title” argument (or the “html” string). The “group” argument is for the ID of which node group you want this node to be a member of, which will also be discussed in the next section.

The “meta” argument of

$wp_admin_bar->add_node()

is an array of several other substrings. “Html” is for the HTML markup you wish to be displayed in place of any simple link or text. “Class” will be included with the list of classes for this node when rendered, allowing you or someone else to alter the appearance of this node. “Onclick” and “target” are dependent on the “html” argument, and are for their respective attributes for the link wrapping the content of the node. “Title” and “tabindex” are for their respective attributes of either the node’s link or the div surrounding the content displayed when the “href” argument is not passed.

Adding with More Complexity

Overwriting Existing Nodes

There may come a time when you need to edit a node that already exists. You might be building a child theme and want to edit a node that comes with the parent theme, or you might be building a plugin to edit or extend the functionality of another plugin and want to change a few details about the nodes that the base plugin adds. The

$wp_admin_bar->add_node()

function includes the ability to overwrite an existing node’s data when the same ID is used again. To accomplish this, use and modify the example code below, replacing the title argument with whatever arguments you wish to overwrite. Just be sure to use the same ID that the base node uses and to set the priority in add_action() to be lower (by using a larger number) than that used by your base plugin or theme. If you want to be sure that you will only overwrite an existing node and not create a new one (e.g. if the base plugin is not active), then use

$wp_admin_bar->get_node()

in an “if” statement to make sure the base node has already been added.

add_action( 'admin_bar_menu', 'my_toolbar_node', 999 );
function my_toolbar_node( $wp_admin_bar ) {
	global $wp_admin_bar;
	$args = array(
		'id' => 'original_node_id',
		'title' => 'Replacement Title'
	);
	$wp_admin_bar->add_node($args);
}

Creating Sub-menus

Making sub-menus out of nodes is nearly as easy as making regular nodes. All you have to do is set the parent argument of the nodes destined to be children. You can do this for multiple child nodes, and even go several layers deep by setting the grandchild’s parent as one of the child nodes. The code below demonstrates how to create a tree of nodes that goes two levels deep underneath the parent node.

add_action( 'admin_bar_menu', 'my_toolbar_nodes', 999 );
function my_toolbar_nodes( $wp_admin_bar ) {
	// add a parent/top-level node
	$args = array('id' => 'parent_node', 'title' => 'Parent Node'); 
	$wp_admin_bar->add_node($args);
 
	// add a child item to our parent node
	$args = array('id' => 'child_node_one', 'title' => 'First Child Node', 'parent' => 'parent_node'); 
	$wp_admin_bar->add_node($args);
 
	// add another child item to our parent node
	$args = array('id' => 'child_node_two', 'title' => 'Second Child Node', 'parent' => 'parent_node'); 
	$wp_admin_bar->add_node($args);
 
	// add a child to our second child node, making it a grandchild of our parent node
	$args = array('id' => 'child_of_child_two', 'title' => 'First Grandchild', 'parent' => 'child_node_two'); 
	$wp_admin_bar->add_node($args);
 
}

Summary

The WordPress Toolbar can be a great tool for enhancing the ability of users to manage and work with a website. It can reduce the number of clicks needed to get to any administration page, and provides a quick glance as to the amount of maintenance currently needed. If you want to create your own node for the Toolbar, only one function is needed to create a new node or to overwrite an existing node. Since the Toolbar makes it easy for developers to place new items for users to see and interact with, it would not be surprising to see it being used by more plugins and themes.

Resources
Link: Class Reference/WP Admin Bar in the WordPress Codex
Link: Toolbar – Administration Screens in the WordPress Codex

Comments Closed

Codeable info