Changeset 58982

Timestamp:

09/03/2024 08:43:09 PM (5 weeks ago)

Author:

joedolson

Message:

Docs: Add changing existing items recommendations to 'admin_bar_menu' action.

Improves the 'admin_bar_menu' docblock by adding recommendations for customizing / changing existing items.

It also improves the wp_admin_bar_render() function's docblock by removing the "most optimal point" sentence.

The [58748] changeset moved the user menu to a higher priority level (of 9991) to achieve:

so nodes added with higher priorities will still be shown visually before the user and recovery menu items, as they were prior to [58215].

When hooking into 'admin_bar_menu' with a priority level less than 9991 and attempting to get the 'my-account' node, null is returned. While the preferred approach is to hook into 'wp_before_admin_bar_render', the documentation of the 'admin_bar_menu' action was previously misleading.

Follow-up to [58748], [58759].

Reviewed by joedolson.
Merges [58978] to the 6.6 branch.

Props michaelwp85, narenin, sabernhardt, joedolson, costdev, jorbin, hellofromTonya, mukesh27, pbiron.
Fixes #61738.

Location:

branches/6.6

Files:

• . (modified) (1 prop)
• src/wp-includes/admin-bar.php (modified) (2 diffs)

branches/6.6/src/wp-includes/admin-bar.php

@@ -63 +63 @@
  *
  * It includes the {@see 'admin_bar_menu'} action which should be used to hook in and
- * add new menus to the admin bar. That way you can be sure that you are adding at most
- * optimal point, right before the admin bar is rendered. This also gives you access to
- * the `$post` global, among others.
+ * add new menus to the admin bar. This also gives you access to the `$post` global,
+ * among others.
  *
  * @since 3.1.0
@@ -87 +86 @@
      * Loads all necessary admin bar items.
      *
-     * This is the hook used to add, remove, or manipulate admin bar items.
+     * This hook can add, remove, or manipulate admin bar items. The priority
+     * determines the placement for new items, and changes to existing items
+     * would require a high priority. To remove or manipulate existing nodes
+     * without a specific priority, use `wp_before_admin_bar_render`.
      *
      * @since 3.1.0