WordPress.org

Ready to get started?Download WordPress

Codex

Class Reference/WP Admin Bar/add node

Contents

Description

This function is a method of the $wp_admin_bar global object (see: WP_Admin_Bar), and can be used to add a new item to the Toolbar. You can also use it to change the properties of an item that is already in the Toolbar.

The Toolbar replaces the Admin Bar since WordPress Version 3.3.

Toolbar items are also called "nodes". Nodes can be parents for other nodes, which creates dropdown menus. Group nodes together with add_group() to create distinct sections in a Toolbar menu.

note: This function is a method of the WP_Admin_Bar class and $wp_admin_bar global object, which may not exist except during the 'admin_bar_menu' or 'wp_before_admin_bar_render' hooks.

Usage

<?php $wp_admin_bar->add_node$args ); ?>

Parameters

$args
(array) (required) An array of arguments.
Default: None

Arguments

id
(string) (required) The ID of the node.
Default: false
title
(string) (optional) The text that will be visible in the Toolbar. Including html tags is allowed.
Default: false
parent
(string) (optional) The ID of the parent node.
Default: false
href
(string) (optional) The 'href' attribute for the link. If 'href' is not set the node will be a text node.
Default: false
group
(boolean) (optional) This will make the node a group (node) if set to 'true'. Group nodes are not visible in the Toolbar, but nodes added to it are. See add_group().
Default: false
meta
(array) (optional) An array of meta data for the node.
Default: array()
  • 'html' - The html used for the node.
  • 'class' - The class attribute for the list item containing the link or text node.
  • 'onclick' - The onclick attribute for the link. This will only be set if the 'href' argument is present.
  • 'target' - The target attribute for the link. This will only be set if the 'href' argument is present.
  • 'title' - The title attribute. Will be set to the link or to a div containing a text node.
  • 'tabindex' - The tabindex attribute. Will be set to the link or to a div containing a text node.

Examples

Add a Page to the Toolbar

This example will add a Page with a "my-toolbar-page" class to the Toolbar. It will be a top level item because the 'parent' argument is not set (it has no parent node). Put this in your theme's functions.php file.

add_action( 'admin_bar_menu', 'toolbar_link_to_mypage', 999 );

function toolbar_link_to_mypage( $wp_admin_bar ) {
	$args = array(
		'id'    => 'my_page',
		'title' => 'My Page',
		'href'  => 'http://mysite.com/my-page/',
		'meta'  => array( 'class' => 'my-toolbar-page' )
	);
	$wp_admin_bar->add_node( $args );
}

Make an Existing Child Node a Parent Node

This example will change the properties of an existing node by using the ID of that node. See Finding Toolbar Node ID's on how to find existing node ID's. The following code will make the child node with ID "new-post" (New > Post) a parent node.

add_action( 'admin_bar_menu', 'make_parent_node', 999 );

function make_parent_node( $wp_admin_bar ) {
	$args = array(
		'id'     => 'new-post',     // id of the existing child node (New > Post)
		'title'  => 'Add New Post', // alter the title of existing node
		'parent' => false,          // set parent to false to make it a top level (parent) node
	);
	$wp_admin_bar->add_node( $args );
}

Single function to add parent/child sub menu items

This is how to add a parent or sub menu item with one function. This is from Orbisius Child Theme Creator plugin.

add_action('wp_before_admin_bar_render', 'orbisius_child_theme_creator_admin_bar_render', 100);

/**
 * Adds admin bar items for easy access to the theme creator and editor
 */
function orbisius_child_theme_creator_admin_bar_render() {
    orbisius_child_theme_creator_add_admin_bar('Orbisius'); // Parent item
    orbisius_child_theme_creator_add_admin_bar('Orbisius Child Theme Creator', 'some_link_to_the_settings', 'Orbisius');
    orbisius_child_theme_creator_add_admin_bar('Orbisius Theme Editor', 'some_link_to_the_settings', 'Orbisius');
}

/**
 * Add's menu parent or submenu item.
 * @param string $name the label of the menu item
 * @param string $href the link to the item (settings page or ext site)
 * @param string $parent Parent label (if creating a submenu item)
 *
 * @return void
 * @author Slavi Marinov <http://orbisius.com>
 * */
function orbisius_child_theme_creator_add_admin_bar($name, $href = '', $parent = '', $custom_meta = array()) {
    global $wp_admin_bar;

    if (!is_super_admin()
            || !is_admin_bar_showing()
            || !is_object($wp_admin_bar)
            || !function_exists('is_admin_bar_showing')) {
        return;
    }

    // Generate ID based on the current filename and the name supplied.
    $id = str_replace('.php', '', basename(__FILE__)) . '-' . $name;
    $id = preg_replace('#[^\w-]#si', '-', $id);
    $id = strtolower($id);
    $id = trim($id, '-');

    $parent = trim($parent);

    // Generate the ID of the parent.
    if (!empty($parent)) {
        $parent = str_replace('.php', '', basename(__FILE__)) . '-' . $parent;
        $parent = preg_replace('#[^\w-]#si', '-', $parent);
        $parent = strtolower($parent);
        $parent = trim($parent, '-');
    }

    // links from the current host will open in the current window
    $site_url = site_url();

    $meta_default = array();
    $meta_ext = array( 'target' => '_blank' ); // external links open in new tab/window

    $meta = (strpos($href, $site_url) !== false) ? $meta_default : $meta_ext;
    $meta = array_merge($meta, $custom_meta);

    $wp_admin_bar->add_node(array(
        'parent' => $parent,
        'id' => $id,
        'title' => $name,
        'href' => $href,
        'meta' => $meta,
    ));
}

Change Log

Source File

add_node() is located in wp-includes/class-wp-admin-bar.php.

Related

Toolbar API

See also index of Function Reference and index of Template Tags.