WP_Admin_Bar::add_node( array $args )

Adds a node to the menu.

Parameters

$argsarrayrequired
Arguments for adding a node.
  • id string
    ID of the item.
  • title string
    Title of the node.
  • parent string
    Optional. ID of the parent node.
  • href string
    Optional. Link for the item.
  • group bool
    Optional. Whether or not the node is a group. Default false.
  • meta array
    Meta data including the following keys: 'html', 'class', 'rel', 'lang', 'dir', 'onclick', 'target', 'title', 'tabindex', 'menu_title'. Default empty.

More Information

Source

public function add_node( $args ) {
	// Shim for old method signature: add_node( $parent_id, $menu_obj, $args ).
	if ( func_num_args() >= 3 && is_string( $args ) ) {
		$args = array_merge( array( 'parent' => $args ), func_get_arg( 2 ) );
	}

	if ( is_object( $args ) ) {
		$args = get_object_vars( $args );
	}

	// Ensure we have a valid title.
	if ( empty( $args['id'] ) ) {
		if ( empty( $args['title'] ) ) {
			return;
		}

		_doing_it_wrong( __METHOD__, __( 'The menu ID should not be empty.' ), '3.3.0' );
		// Deprecated: Generate an ID from the title.
		$args['id'] = esc_attr( sanitize_title( trim( $args['title'] ) ) );
	}

	$defaults = array(
		'id'     => false,
		'title'  => false,
		'parent' => false,
		'href'   => false,
		'group'  => false,
		'meta'   => array(),
	);

	// If the node already exists, keep any data that isn't provided.
	$maybe_defaults = $this->get_node( $args['id'] );
	if ( $maybe_defaults ) {
		$defaults = get_object_vars( $maybe_defaults );
	}

	// Do the same for 'meta' items.
	if ( ! empty( $defaults['meta'] ) && ! empty( $args['meta'] ) ) {
		$args['meta'] = wp_parse_args( $args['meta'], $defaults['meta'] );
	}

	$args = wp_parse_args( $args, $defaults );

	$back_compat_parents = array(
		'my-account-with-avatar' => array( 'my-account', '3.3' ),
		'my-blogs'               => array( 'my-sites', '3.3' ),
	);

	if ( isset( $back_compat_parents[ $args['parent'] ] ) ) {
		list( $new_parent, $version ) = $back_compat_parents[ $args['parent'] ];
		_deprecated_argument( __METHOD__, $version, sprintf( 'Use <code>%s</code> as the parent for the <code>%s</code> admin bar node instead of <code>%s</code>.', $new_parent, $args['id'], $args['parent'] ) );
		$args['parent'] = $new_parent;
	}

	$this->_set_node( $args );
}

Changelog

VersionDescription
6.5.0Added the ability to pass 'menu_title' for an ARIA menu name.
4.5.0Added the ability to pass 'lang' and 'dir' meta data.
3.1.0Introduced.

User Contributed Notes

  1. Skip to note 7 content

    Inspect element to find the id

    To adjust a menu item one has to first find the correct id (node) of the link.
    Right click the menu link in your browser and select Inspect Element (name will vary from browser to browser) to open the panel to where one can see the html and css of the page you are on.
    Notice the id tag.
    I am looking at adjusting the sites drop down. So I will find the id: wp-admin-bar-site-name.
    To find the correct node one has to remove: wp-admin-bar-. What is left is the site-name.

    Nodes

    The various top level and submenu nodes in the admin toolbar are:
    wp-logo
    about
    wporg
    documentation
    support-forum
    feedback

    site-name
    dashboard
    themes
    customize
    widgets
    menus
    customize-background
    customize-header

    comments

    new-content
    new-post
    new-media
    new-page
    new-user

    edit

    user-actions (to the right – next to your avatar image)
    user-info
    edit-profile
    logout

    Removing a top level node removes the link and submenu if it has one.

    The Code

    If you’re using the code in the beginning of your functions.php file then include the opening php tag before the below code.

    The following code adds a media library link to the site name drop down menu.

    add_action( 'admin_bar_menu', 'add_link_to_admin_bar',999 );
    
    function add_link_to_admin_bar($admin_bar) {         
              $args = array(
                    'parent' => 'site-name',
                    'id'     => 'media-libray',
                    'title'  => 'Media Library',
                    'href'   => esc_url( admin_url( 'upload.php' ) ),
                    'meta'   => false
           		);
           		$admin_bar->add_node( $args );       
    }

    The following code adds a media library and a plugins link to the site name drop down menu.

    add_action( 'admin_bar_menu', 'add_links_to_admin_bar',999 );
    
    function add_links_to_admin_bar($admin_bar) {         
              $args = array(
                    'parent' => 'site-name',
                    'id'     => 'media-libray',
                    'title'  => 'Media Library',
                    'href'   => esc_url( admin_url( 'upload.php' ) ),
                    'meta'   => false
           		);
           	$admin_bar->add_node( $args );
           
            	$args = array(
            		'parent' => 'site-name',
            		'id'     => 'plugins',
            		'title'  => 'Plugins',
            		'href'   => esc_url( admin_url( 'plugins.php' ) ),
            		'meta'   => false
            	);
            $admin_bar->add_node( $args );
    }

    The following code adds top level link and media library and plugins submenu links to the Custom Made drop down.

    add_action( 'admin_bar_menu', 'add_top_link_to_admin_bar',999 );
    
    function add_top_link_to_admin_bar($admin_bar) {
             // add a parent item
             	$args = array(
             		'id'    => 'custom',
             		'title' => 'Custom Made',
             		'href'   => 'http://example.com/', // Showing how to add an external link
             	);
             	$admin_bar->add_node( $args );
             	
             // add a child item to our parent item	
             	$args = array(
             		'parent' => 'custom',
             		'id'     => 'media-libray',
             		'title'  => 'Media Library',
             		'href'   => esc_url( admin_url( 'upload.php' ) ),
             		'meta'   => false		
             	);
             	$admin_bar->add_node( $args );
             	
             // add a child item to our parent item	
             	$args = array(
             		'parent' => 'custom',
             		'id'     => 'plugins',
             		'title'  => 'Plugins',
             		'href'   => esc_url( admin_url( 'plugins.php' ) ),
             		'meta'   => false		
             	);
             	$admin_bar->add_node( $args );     	         		 
    }
  2. Skip to note 8 content

    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.

    /**
     * Adds a "My Page" link to the Toolbar.
     *
     * @param WP_Admin_Bar $wp_admin_bar Toolbar instance.
     */
    function toolbar_link_to_mypage( $wp_admin_bar ) {
    	$args = array(
    		'id'    => 'my_page',
    		'title' => __( 'My Page', 'textdomain' ),
    		'href'  => 'http://mysite.com/my-page/',
    		'meta'  => array(
    			'class' => 'my-toolbar-page'
    		)
    	);
    	$wp_admin_bar->add_node( $args );
    }
    add_action( 'admin_bar_menu', 'toolbar_link_to_mypage', 999 );
  3. Skip to note 9 content

    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.

    /**
     * Modifies the "Add New Post" Toolbar item to move it to the top-level.
     *
     * @param WP_Admin_Bar $wp_admin_bar Toolbar instance.
     */
    function make_parent_node( $wp_admin_bar ) {
    	$args = array(
    		'id'     => 'new-post',                         // id of the existing child node (New > Post)
    		'title'  => __( 'Add New Post', 'textdomain' ), // 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 );
    }
    add_action( 'admin_bar_menu', 'make_parent_node', 999 );
  4. Skip to note 10 content

    Sorting The Links on the Admin Menu Bar

    Use further array functions in PHP to sort the admin menu items with the following code.

    Problem: Since the basic code for admin bar links is to create a separate $args variable for each array, sorting the links could be a lot of work cutting and pasting code around when you need to sort the links.

    Solution: The following code does the following: 1. adds each $args into a separate element of the same $args by using PHP’s array_push() function 2. Each $args element is a multi-dimensional array that can be sorted 3. Use PHP’s sort function to sort them. 4. Traverse a for loop.

    /**
     * Adds sorted social media links to the Toolbar.
     *
     * @param WP_Admin_Bar $wp_admin_bar Toolbar instance.
     */
    function social_media_links( $wp_admin_bar ) {
    
    	$args = array(
    		'id'    => 'social_media',
    		'title' => 'Social Media',
    		'meta'  => array(
    			'class' => 'first-toolbar-group'
    		),
    	);
    	$wp_admin_bar->add_node( $args );	
    
    	$args = array();
    
    	array_push( $args,array(
    		'id'     => 'twitter',
    		'title'  => __( 'Twitter', 'textdomain' ),
    		'href'   => 'http://www.twitter.com',
    		'parent' => 'social_media',
    	) );
    	
    	array_push( $args,array(
    		'id'     => 'youtube',
    		'title'  => __( 'YouTube', 'textdomain' ),
    		'href'   => 'http://www.YouTube.com',
    		'parent' => 'social_media',
    		'meta'   => array(
    			'class' => 'first-toolbar-group'
    		),
    	) );
    
    	array_push( $args,array(
    		'id'     => 'fb',
    		'title'  => __( 'Facebook', 'textdomain' ),
    		'href'   => 'http://www.facebook.com',
    		'parent' => 'social_media',
    	) );
    	
    	sort( $args );
    
    	for ( $a=0; $a < sizeOf( $args ); $a++ ) {
    		$wp_admin_bar->add_node( $args[ $a ] );
    	}
    } 
  5. Skip to note 11 content

    Single function to add parent/child sub menu items

    This is how to add a parent or sub menu item with one function.

    add_action('wp_before_admin_bar_render', 'baw_admin_bar_render', 100);
    
    /**
     * Adds admin bar items for easy access to the theme creator and editor
     */
    function baw_admin_bar_render() {
        baw_admin_bar_render_item( 'BAW' ); // Parent item
        baw_admin_bar_render_item('BAW Sub1', 'some_link_to_the_settings', 'BAW');
        baw_admin_bar_render_item('BAW Sub2', 'some_link_to_the_settings', 'BAW');
    }
    
    /**
     * Adds menu parent or submenu item.
     *
     * @param string $name        The menu item label.
     * @param string $href        Optional. The link to the item (settings page or ext site). Default empty.
     * @param string $parent      Optional. Parent label (if creating a submenu item). Default empty.
     * @param array  $custom_meta Optional. Custom meta to include for the rendered item. Default empty array.
     *
     * @global WP_Admin_Bar $wp_admin_bar Toolbar instance.
     */
    function baw_admin_bar_render_item( $name, $href = '', $parent = '', $custom_meta = array() ) {
        global $wp_admin_bar;
    
    	if ( ! is_super_admin()
    		 || ! is_object( $wp_admin_bar ) 
    		 || ! function_exists( 'is_admin_bar_showing' ) 
    		 || ! is_admin_bar_showing()
    	 ) {
    		return;
    	}
    
        // Generate ID based on the current filename and the name supplied.
        $id = sanitize_key( basename( __FILE__, '.php' ) . '-' . $name );
    
        // Generate the ID of the parent.
        $parent = sanitize_key( basename( __FILE__, '.php' ) . '-' . $parent );
    
        // Links from the current host will open in the current window
    
        $meta = strpos( $href, site_url() ) !== false ? array() : array( 'target' => '_blank' ); // external links open in new tab/window
        $meta = array_merge( $meta, $custom_meta );
    
        $wp_admin_bar->add_node( array(
            'parent' => $parent,
            'id'     => $id,
            'title'  => $name,
            'href'   => $href,
            'meta'   => $meta,
        ) );
    }

You must log in before being able to contribute a note or feedback.