[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/ -> class-wp-admin-bar.php (source)

   1  <?php
   2  /**
   3   * Toolbar API: WP_Admin_Bar class
   4   *
   5   * @package WordPress
   6   * @subpackage Toolbar
   7   * @since 3.1.0
   8   */
   9  
  10  /**
  11   * Core class used to implement the Toolbar API.
  12   *
  13   * @since 3.1.0
  14   */
  15  #[AllowDynamicProperties]
  16  class WP_Admin_Bar {
  17      private $nodes = array();
  18      private $bound = false;
  19      public $user;
  20  
  21      /**
  22       * Deprecated menu property.
  23       *
  24       * @since 3.1.0
  25       * @deprecated 3.3.0 Modify admin bar nodes with WP_Admin_Bar::get_node(),
  26       *                   WP_Admin_Bar::add_node(), and WP_Admin_Bar::remove_node().
  27       * @var array
  28       */
  29      public $menu = array();
  30  
  31      /**
  32       * Initializes the admin bar.
  33       *
  34       * @since 3.1.0
  35       */
  36  	public function initialize() {
  37          $this->user = new stdClass();
  38  
  39          if ( is_user_logged_in() ) {
  40              /* Populate settings we need for the menu based on the current user. */
  41              $this->user->blogs = get_blogs_of_user( get_current_user_id() );
  42              if ( is_multisite() ) {
  43                  $this->user->active_blog    = get_active_blog_for_user( get_current_user_id() );
  44                  $this->user->domain         = empty( $this->user->active_blog ) ? user_admin_url() : trailingslashit( get_home_url( $this->user->active_blog->blog_id ) );
  45                  $this->user->account_domain = $this->user->domain;
  46              } else {
  47                  $this->user->active_blog    = $this->user->blogs[ get_current_blog_id() ];
  48                  $this->user->domain         = trailingslashit( home_url() );
  49                  $this->user->account_domain = $this->user->domain;
  50              }
  51          }
  52  
  53          add_action( 'wp_head', 'wp_admin_bar_header' );
  54  
  55          add_action( 'admin_head', 'wp_admin_bar_header' );
  56  
  57          if ( current_theme_supports( 'admin-bar' ) ) {
  58              /**
  59               * To remove the default padding styles from WordPress for the Toolbar, use the following code:
  60               * add_theme_support( 'admin-bar', array( 'callback' => '__return_false' ) );
  61               */
  62              $admin_bar_args  = get_theme_support( 'admin-bar' );
  63              $header_callback = $admin_bar_args[0]['callback'];
  64          }
  65  
  66          if ( empty( $header_callback ) ) {
  67              $header_callback = '_admin_bar_bump_cb';
  68          }
  69  
  70          add_action( 'wp_head', $header_callback );
  71  
  72          wp_enqueue_script( 'admin-bar' );
  73          wp_enqueue_style( 'admin-bar' );
  74  
  75          /**
  76           * Fires after WP_Admin_Bar is initialized.
  77           *
  78           * @since 3.1.0
  79           */
  80          do_action( 'admin_bar_init' );
  81      }
  82  
  83      /**
  84       * Adds a node (menu item) to the admin bar menu.
  85       *
  86       * @since 3.3.0
  87       *
  88       * @param array $node The attributes that define the node.
  89       */
  90  	public function add_menu( $node ) {
  91          $this->add_node( $node );
  92      }
  93  
  94      /**
  95       * Removes a node from the admin bar.
  96       *
  97       * @since 3.1.0
  98       *
  99       * @param string $id The menu slug to remove.
 100       */
 101  	public function remove_menu( $id ) {
 102          $this->remove_node( $id );
 103      }
 104  
 105      /**
 106       * Adds a node to the menu.
 107       *
 108       * @since 3.1.0
 109       * @since 4.5.0 Added the ability to pass 'lang' and 'dir' meta data.
 110       * @since 6.5.0 Added the ability to pass 'menu_title' for an ARIA menu name.
 111       *
 112       * @param array $args {
 113       *     Arguments for adding a node.
 114       *
 115       *     @type string $id     ID of the item.
 116       *     @type string $title  Title of the node.
 117       *     @type string $parent Optional. ID of the parent node.
 118       *     @type string $href   Optional. Link for the item.
 119       *     @type bool   $group  Optional. Whether or not the node is a group. Default false.
 120       *     @type array  $meta   Meta data including the following keys: 'html', 'class', 'rel', 'lang', 'dir',
 121       *                          'onclick', 'target', 'title', 'tabindex', 'menu_title'. Default empty.
 122       * }
 123       */
 124  	public function add_node( $args ) {
 125          // Shim for old method signature: add_node( $parent_id, $menu_obj, $args ).
 126          if ( func_num_args() >= 3 && is_string( $args ) ) {
 127              $args = array_merge( array( 'parent' => $args ), func_get_arg( 2 ) );
 128          }
 129  
 130          if ( is_object( $args ) ) {
 131              $args = get_object_vars( $args );
 132          }
 133  
 134          // Ensure we have a valid title.
 135          if ( empty( $args['id'] ) ) {
 136              if ( empty( $args['title'] ) ) {
 137                  return;
 138              }
 139  
 140              _doing_it_wrong( __METHOD__, __( 'The menu ID should not be empty.' ), '3.3.0' );
 141              // Deprecated: Generate an ID from the title.
 142              $args['id'] = esc_attr( sanitize_title( trim( $args['title'] ) ) );
 143          }
 144  
 145          $defaults = array(
 146              'id'     => false,
 147              'title'  => false,
 148              'parent' => false,
 149              'href'   => false,
 150              'group'  => false,
 151              'meta'   => array(),
 152          );
 153  
 154          // If the node already exists, keep any data that isn't provided.
 155          $maybe_defaults = $this->get_node( $args['id'] );
 156          if ( $maybe_defaults ) {
 157              $defaults = get_object_vars( $maybe_defaults );
 158          }
 159  
 160          // Do the same for 'meta' items.
 161          if ( ! empty( $defaults['meta'] ) && ! empty( $args['meta'] ) ) {
 162              $args['meta'] = wp_parse_args( $args['meta'], $defaults['meta'] );
 163          }
 164  
 165          $args = wp_parse_args( $args, $defaults );
 166  
 167          $back_compat_parents = array(
 168              'my-account-with-avatar' => array( 'my-account', '3.3' ),
 169              'my-blogs'               => array( 'my-sites', '3.3' ),
 170          );
 171  
 172          if ( isset( $back_compat_parents[ $args['parent'] ] ) ) {
 173              list( $new_parent, $version ) = $back_compat_parents[ $args['parent'] ];
 174              _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'] ) );
 175              $args['parent'] = $new_parent;
 176          }
 177  
 178          $this->_set_node( $args );
 179      }
 180  
 181      /**
 182       * @since 3.3.0
 183       *
 184       * @param array $args
 185       */
 186  	final protected function _set_node( $args ) {
 187          $this->nodes[ $args['id'] ] = (object) $args;
 188      }
 189  
 190      /**
 191       * Gets a node.
 192       *
 193       * @since 3.3.0
 194       *
 195       * @param string $id
 196       * @return object|void Node.
 197       */
 198  	final public function get_node( $id ) {
 199          $node = $this->_get_node( $id );
 200          if ( $node ) {
 201              return clone $node;
 202          }
 203      }
 204  
 205      /**
 206       * @since 3.3.0
 207       *
 208       * @param string $id
 209       * @return object|void
 210       */
 211  	final protected function _get_node( $id ) {
 212          if ( $this->bound ) {
 213              return;
 214          }
 215  
 216          if ( empty( $id ) ) {
 217              $id = 'root';
 218          }
 219  
 220          if ( isset( $this->nodes[ $id ] ) ) {
 221              return $this->nodes[ $id ];
 222          }
 223      }
 224  
 225      /**
 226       * @since 3.3.0
 227       *
 228       * @return array|void
 229       */
 230  	final public function get_nodes() {
 231          $nodes = $this->_get_nodes();
 232          if ( ! $nodes ) {
 233              return;
 234          }
 235  
 236          foreach ( $nodes as &$node ) {
 237              $node = clone $node;
 238          }
 239          return $nodes;
 240      }
 241  
 242      /**
 243       * @since 3.3.0
 244       *
 245       * @return array|void
 246       */
 247  	final protected function _get_nodes() {
 248          if ( $this->bound ) {
 249              return;
 250          }
 251  
 252          return $this->nodes;
 253      }
 254  
 255      /**
 256       * Adds a group to a toolbar menu node.
 257       *
 258       * Groups can be used to organize toolbar items into distinct sections of a toolbar menu.
 259       *
 260       * @since 3.3.0
 261       *
 262       * @param array $args {
 263       *     Array of arguments for adding a group.
 264       *
 265       *     @type string $id     ID of the item.
 266       *     @type string $parent Optional. ID of the parent node. Default 'root'.
 267       *     @type array  $meta   Meta data for the group including the following keys:
 268       *                         'class', 'onclick', 'target', and 'title'.
 269       * }
 270       */
 271  	final public function add_group( $args ) {
 272          $args['group'] = true;
 273  
 274          $this->add_node( $args );
 275      }
 276  
 277      /**
 278       * Remove a node.
 279       *
 280       * @since 3.1.0
 281       *
 282       * @param string $id The ID of the item.
 283       */
 284  	public function remove_node( $id ) {
 285          $this->_unset_node( $id );
 286      }
 287  
 288      /**
 289       * @since 3.3.0
 290       *
 291       * @param string $id
 292       */
 293  	final protected function _unset_node( $id ) {
 294          unset( $this->nodes[ $id ] );
 295      }
 296  
 297      /**
 298       * @since 3.1.0
 299       */
 300  	public function render() {
 301          $root = $this->_bind();
 302          if ( $root ) {
 303              $this->_render( $root );
 304          }
 305      }
 306  
 307      /**
 308       * @since 3.3.0
 309       *
 310       * @return object|void
 311       */
 312  	final protected function _bind() {
 313          if ( $this->bound ) {
 314              return;
 315          }
 316  
 317          /*
 318           * Add the root node.
 319           * Clear it first, just in case. Don't mess with The Root.
 320           */
 321          $this->remove_node( 'root' );
 322          $this->add_node(
 323              array(
 324                  'id'    => 'root',
 325                  'group' => false,
 326              )
 327          );
 328  
 329          // Normalize nodes: define internal 'children' and 'type' properties.
 330          foreach ( $this->_get_nodes() as $node ) {
 331              $node->children = array();
 332              $node->type     = ( $node->group ) ? 'group' : 'item';
 333              unset( $node->group );
 334  
 335              // The Root wants your orphans. No lonely items allowed.
 336              if ( ! $node->parent ) {
 337                  $node->parent = 'root';
 338              }
 339          }
 340  
 341          foreach ( $this->_get_nodes() as $node ) {
 342              if ( 'root' === $node->id ) {
 343                  continue;
 344              }
 345  
 346              // Fetch the parent node. If it isn't registered, ignore the node.
 347              $parent = $this->_get_node( $node->parent );
 348              if ( ! $parent ) {
 349                  continue;
 350              }
 351  
 352              // Generate the group class (we distinguish between top level and other level groups).
 353              $group_class = ( 'root' === $node->parent ) ? 'ab-top-menu' : 'ab-submenu';
 354  
 355              if ( 'group' === $node->type ) {
 356                  if ( empty( $node->meta['class'] ) ) {
 357                      $node->meta['class'] = $group_class;
 358                  } else {
 359                      $node->meta['class'] .= ' ' . $group_class;
 360                  }
 361              }
 362  
 363              // Items in items aren't allowed. Wrap nested items in 'default' groups.
 364              if ( 'item' === $parent->type && 'item' === $node->type ) {
 365                  $default_id = $parent->id . '-default';
 366                  $default    = $this->_get_node( $default_id );
 367  
 368                  /*
 369                   * The default group is added here to allow groups that are
 370                   * added before standard menu items to render first.
 371                   */
 372                  if ( ! $default ) {
 373                      /*
 374                       * Use _set_node because add_node can be overloaded.
 375                       * Make sure to specify default settings for all properties.
 376                       */
 377                      $this->_set_node(
 378                          array(
 379                              'id'       => $default_id,
 380                              'parent'   => $parent->id,
 381                              'type'     => 'group',
 382                              'children' => array(),
 383                              'meta'     => array(
 384                                  'class' => $group_class,
 385                              ),
 386                              'title'    => false,
 387                              'href'     => false,
 388                          )
 389                      );
 390                      $default            = $this->_get_node( $default_id );
 391                      $parent->children[] = $default;
 392                  }
 393                  $parent = $default;
 394  
 395                  /*
 396                   * Groups in groups aren't allowed. Add a special 'container' node.
 397                   * The container will invisibly wrap both groups.
 398                   */
 399              } elseif ( 'group' === $parent->type && 'group' === $node->type ) {
 400                  $container_id = $parent->id . '-container';
 401                  $container    = $this->_get_node( $container_id );
 402  
 403                  // We need to create a container for this group, life is sad.
 404                  if ( ! $container ) {
 405                      /*
 406                       * Use _set_node because add_node can be overloaded.
 407                       * Make sure to specify default settings for all properties.
 408                       */
 409                      $this->_set_node(
 410                          array(
 411                              'id'       => $container_id,
 412                              'type'     => 'container',
 413                              'children' => array( $parent ),
 414                              'parent'   => false,
 415                              'title'    => false,
 416                              'href'     => false,
 417                              'meta'     => array(),
 418                          )
 419                      );
 420  
 421                      $container = $this->_get_node( $container_id );
 422  
 423                      // Link the container node if a grandparent node exists.
 424                      $grandparent = $this->_get_node( $parent->parent );
 425  
 426                      if ( $grandparent ) {
 427                          $container->parent = $grandparent->id;
 428  
 429                          $index = array_search( $parent, $grandparent->children, true );
 430                          if ( false === $index ) {
 431                              $grandparent->children[] = $container;
 432                          } else {
 433                              array_splice( $grandparent->children, $index, 1, array( $container ) );
 434                          }
 435                      }
 436  
 437                      $parent->parent = $container->id;
 438                  }
 439  
 440                  $parent = $container;
 441              }
 442  
 443              // Update the parent ID (it might have changed).
 444              $node->parent = $parent->id;
 445  
 446              // Add the node to the tree.
 447              $parent->children[] = $node;
 448          }
 449  
 450          $root        = $this->_get_node( 'root' );
 451          $this->bound = true;
 452          return $root;
 453      }
 454  
 455      /**
 456       * @since 3.3.0
 457       *
 458       * @param object $root
 459       */
 460  	final protected function _render( $root ) {
 461          /*
 462           * Add browser classes.
 463           * We have to do this here since admin bar shows on the front end.
 464           */
 465          $class = 'nojq nojs';
 466          if ( wp_is_mobile() ) {
 467              $class .= ' mobile';
 468          }
 469  
 470          ?>
 471          <div id="wpadminbar" class="<?php echo $class; ?>">
 472              <?php if ( ! is_admin() && ! did_action( 'wp_body_open' ) ) { ?>
 473                  <a class="screen-reader-shortcut" href="#wp-toolbar" tabindex="1"><?php _e( 'Skip to toolbar' ); ?></a>
 474              <?php } ?>
 475              <div class="quicklinks" id="wp-toolbar" role="navigation" aria-label="<?php esc_attr_e( 'Toolbar' ); ?>">
 476                  <?php
 477                  foreach ( $root->children as $group ) {
 478                      $this->_render_group( $group );
 479                  }
 480                  ?>
 481              </div>
 482          </div>
 483  
 484          <?php
 485      }
 486  
 487      /**
 488       * @since 3.3.0
 489       *
 490       * @param object $node
 491       */
 492  	final protected function _render_container( $node ) {
 493          if ( 'container' !== $node->type || empty( $node->children ) ) {
 494              return;
 495          }
 496  
 497          echo '<div id="' . esc_attr( 'wp-admin-bar-' . $node->id ) . '" class="ab-group-container">';
 498          foreach ( $node->children as $group ) {
 499              $this->_render_group( $group );
 500          }
 501          echo '</div>';
 502      }
 503  
 504      /**
 505       * @since 3.3.0
 506       * @since 6.5.0 Added `$menu_title` parameter to allow an ARIA menu name.
 507       *
 508       * @param object $node
 509       * @param string|bool $menu_title The accessible name of this ARIA menu or false if not provided.
 510       */
 511  	final protected function _render_group( $node, $menu_title = false ) {
 512          if ( 'container' === $node->type ) {
 513              $this->_render_container( $node );
 514              return;
 515          }
 516          if ( 'group' !== $node->type || empty( $node->children ) ) {
 517              return;
 518          }
 519  
 520          if ( ! empty( $node->meta['class'] ) ) {
 521              $class = ' class="' . esc_attr( trim( $node->meta['class'] ) ) . '"';
 522          } else {
 523              $class = '';
 524          }
 525  
 526          if ( empty( $menu_title ) ) {
 527              echo "<ul role='menu' id='" . esc_attr( 'wp-admin-bar-' . $node->id ) . "'$class>";
 528          } else {
 529              echo "<ul role='menu' aria-label='" . esc_attr( $menu_title ) . "' id='" . esc_attr( 'wp-admin-bar-' . $node->id ) . "'$class>";
 530          }
 531          foreach ( $node->children as $item ) {
 532              $this->_render_item( $item );
 533          }
 534          echo '</ul>';
 535      }
 536  
 537      /**
 538       * @since 3.3.0
 539       *
 540       * @param object $node
 541       */
 542  	final protected function _render_item( $node ) {
 543          if ( 'item' !== $node->type ) {
 544              return;
 545          }
 546  
 547          $is_parent             = ! empty( $node->children );
 548          $has_link              = ! empty( $node->href );
 549          $is_root_top_item      = 'root-default' === $node->parent;
 550          $is_top_secondary_item = 'top-secondary' === $node->parent;
 551  
 552          // Allow only numeric values, then casted to integers, and allow a tabindex value of `0` for a11y.
 553          $tabindex         = ( isset( $node->meta['tabindex'] ) && is_numeric( $node->meta['tabindex'] ) ) ? (int) $node->meta['tabindex'] : '';
 554          $aria_attributes  = ( '' !== $tabindex ) ? ' tabindex="' . $tabindex . '"' : '';
 555          $aria_attributes .= ' role="menuitem"';
 556  
 557          $menuclass = '';
 558          $arrow     = '';
 559  
 560          if ( $is_parent ) {
 561              $menuclass        = 'menupop ';
 562              $aria_attributes .= ' aria-expanded="false"';
 563          }
 564  
 565          if ( ! empty( $node->meta['class'] ) ) {
 566              $menuclass .= $node->meta['class'];
 567          }
 568  
 569          // Print the arrow icon for the menu children with children.
 570          if ( ! $is_root_top_item && ! $is_top_secondary_item && $is_parent ) {
 571              $arrow = '<span class="wp-admin-bar-arrow" aria-hidden="true"></span>';
 572          }
 573  
 574          if ( $menuclass ) {
 575              $menuclass = ' class="' . esc_attr( trim( $menuclass ) ) . '"';
 576          }
 577  
 578          echo "<li id='" . esc_attr( 'wp-admin-bar-' . $node->id ) . "'$menuclass>";
 579  
 580          if ( $has_link ) {
 581              $attributes = array( 'onclick', 'target', 'title', 'rel', 'lang', 'dir' );
 582              echo "<a class='ab-item'$aria_attributes href='" . esc_url( $node->href ) . "'";
 583          } else {
 584              $attributes = array( 'onclick', 'target', 'title', 'rel', 'lang', 'dir' );
 585              echo '<div class="ab-item ab-empty-item"' . $aria_attributes;
 586          }
 587  
 588          foreach ( $attributes as $attribute ) {
 589              if ( empty( $node->meta[ $attribute ] ) ) {
 590                  continue;
 591              }
 592  
 593              if ( 'onclick' === $attribute ) {
 594                  echo " $attribute='" . esc_js( $node->meta[ $attribute ] ) . "'";
 595              } else {
 596                  echo " $attribute='" . esc_attr( $node->meta[ $attribute ] ) . "'";
 597              }
 598          }
 599  
 600          echo ">{$arrow}{$node->title}";
 601  
 602          if ( $has_link ) {
 603              echo '</a>';
 604          } else {
 605              echo '</div>';
 606          }
 607  
 608          if ( $is_parent ) {
 609              echo '<div class="ab-sub-wrapper">';
 610              foreach ( $node->children as $group ) {
 611                  if ( empty( $node->meta['menu_title'] ) ) {
 612                      $this->_render_group( $group, false );
 613                  } else {
 614                      $this->_render_group( $group, $node->meta['menu_title'] );
 615                  }
 616              }
 617              echo '</div>';
 618          }
 619  
 620          if ( ! empty( $node->meta['html'] ) ) {
 621              echo $node->meta['html'];
 622          }
 623  
 624          echo '</li>';
 625      }
 626  
 627      /**
 628       * Renders toolbar items recursively.
 629       *
 630       * @since 3.1.0
 631       * @deprecated 3.3.0 Use WP_Admin_Bar::_render_item() or WP_Admin_bar::render() instead.
 632       * @see WP_Admin_Bar::_render_item()
 633       * @see WP_Admin_Bar::render()
 634       *
 635       * @param string $id    Unused.
 636       * @param object $node
 637       */
 638  	public function recursive_render( $id, $node ) {
 639          _deprecated_function( __METHOD__, '3.3.0', 'WP_Admin_bar::render(), WP_Admin_Bar::_render_item()' );
 640          $this->_render_item( $node );
 641      }
 642  
 643      /**
 644       * Adds menus to the admin bar.
 645       *
 646       * @since 3.1.0
 647       */
 648  	public function add_menus() {
 649          // User-related, aligned right.
 650          add_action( 'admin_bar_menu', 'wp_admin_bar_my_account_menu', 0 );
 651          add_action( 'admin_bar_menu', 'wp_admin_bar_search_menu', 4 );
 652          add_action( 'admin_bar_menu', 'wp_admin_bar_my_account_item', 7 );
 653          add_action( 'admin_bar_menu', 'wp_admin_bar_recovery_mode_menu', 8 );
 654  
 655          // Site-related.
 656          add_action( 'admin_bar_menu', 'wp_admin_bar_sidebar_toggle', 0 );
 657          add_action( 'admin_bar_menu', 'wp_admin_bar_wp_menu', 10 );
 658          add_action( 'admin_bar_menu', 'wp_admin_bar_my_sites_menu', 20 );
 659          add_action( 'admin_bar_menu', 'wp_admin_bar_site_menu', 30 );
 660          add_action( 'admin_bar_menu', 'wp_admin_bar_edit_site_menu', 40 );
 661          add_action( 'admin_bar_menu', 'wp_admin_bar_customize_menu', 40 );
 662          add_action( 'admin_bar_menu', 'wp_admin_bar_updates_menu', 50 );
 663  
 664          // Content-related.
 665          if ( ! is_network_admin() && ! is_user_admin() ) {
 666              add_action( 'admin_bar_menu', 'wp_admin_bar_comments_menu', 60 );
 667              add_action( 'admin_bar_menu', 'wp_admin_bar_new_content_menu', 70 );
 668          }
 669          add_action( 'admin_bar_menu', 'wp_admin_bar_edit_menu', 80 );
 670  
 671          add_action( 'admin_bar_menu', 'wp_admin_bar_add_secondary_groups', 200 );
 672  
 673          /**
 674           * Fires after menus are added to the menu bar.
 675           *
 676           * @since 3.1.0
 677           */
 678          do_action( 'add_admin_bar_menus' );
 679      }
 680  }


Generated : Tue Mar 19 08:20:01 2024 Cross-referenced by PHPXref