bp_core_new_subnav_item

Add an item to secondary navigation of the specified component.

Description

(bool|null) bp_core_new_subnav_item( (array|string) $args, (null) $component = null ); 

Returns (bool|null)

Returns false on failure.

Parameters (2)

0. $args (array|string)
Array describing the new subnav item.

Options

  • name (string) => ''

    Display name for the subnav item.

  • slug (string) => ''

    Unique URL slug for the subnav item.

  • parent_slug (string) => ''

    Slug of the top-level nav item under which the new subnav item should be added.

  • parent_url (string) => ''

    URL of the parent nav item.

  • item_css_id (bool|string) => ''

    id attribute for the nav item. Default: the value of $slug..

  • user_has_access (bool) => null

    True if the logged-in user has access to the subnav item, otherwise false. Can be set dynamically when registering the subnav; eg, use bp_is_my_profile() to restrict access to profile owners only. Default: true.

  • site_admin_only (bool) => null

    Whether the nav item should be visible only to site admins (those with the bp_moderate cap). Default: false.

  • position (int) => 0

    Numerical index specifying where the item should appear in the subnav array. Default: 90.

  • screen_function (callable) => null

    The callback function that will run when the nav item is clicked.

  • link (string) => 'to a value generated from the $parent_url + $slug'

    The URL that the subnav item should point to.

array(

    /**
     * Display name for the subnav item.
     *
     * @type string
     * @default ''
     */
    'name' => '',

    /**
     * Unique URL slug for the subnav item.
     *
     * @type string
     * @default ''
     */
    'slug' => '',

    /**
     * Slug of the top-level nav item under which the new subnav item should be added.
     *
     * @type string
     * @default ''
     */
    'parent_slug' => '',

    /**
     * URL of the parent nav item.
     *
     * @type string
     * @default ''
     */
    'parent_url' => '',

    /**
     * Optional. 'id' attribute for the nav item. Default: the value of `$slug`.
     *
     * @type bool|string
     * @default ''
     * @optional
     */
    'item_css_id' => '',

    /**
     * Optional. True if the logged-in user has access to the subnav item, otherwise false. Can be set
     * dynamically when registering the subnav; eg, use `bp_is_my_profile()` to restrict access
     * to profile owners only. Default: true.
     *
     * @type bool
     * @default null
     * @optional
     */
    'user_has_access' => null,

    /**
     * Optional. Whether the nav item should be visible only to site admins (those with the
     * 'bp_moderate' cap). Default: false.
     *
     * @type bool
     * @default null
     * @optional
     */
    'site_admin_only' => null,

    /**
     * Optional. Numerical index specifying where the item should appear in the subnav array.
     * Default: 90.
     *
     * @type int
     * @optional
     */
    'position' => 0,

    /**
     * The callback function that will run when the nav item is clicked.
     *
     * @type callable
     * @default null
     */
    'screen_function' => null,

    /**
     * Optional. The URL that the subnav item should point to.
     *
     * @type string
     * @default 'to a value generated from the $parent_url + $slug'
     * @optional
     */
    'link' => 'to a value generated from the $parent_url + $slug'
);        

1. $component — Optional. (null) => null
The component the navigation is attached to. Defaults to members..

Usage

  1. if ( !function_exists( 'bp_core_new_subnav_item' ) ) { 
  2. require_once ABSPATH . PLUGINDIR . 'buddypress/bp-core/bp-core-buddybar.php'; 
  3.  
  4. // Array describing the new subnav item. 
  5. $args = array( 
  6. 'name' => '', 
  7. 'slug' => '', 
  8. 'parent_slug' => '', 
  9. 'parent_url' => '', 
  10. 'item_css_id' => '', 
  11. 'user_has_access' => null, 
  12. 'site_admin_only' => null, 
  13. 'position' => 0, 
  14. 'screen_function' => null, 
  15. 'link' => 'to a value generated from the $parent_url + $slug' 
  16. ); 
  17.  
  18. // The component the navigation is attached to. Defaults to 'members'. 
  19. $component = null; 
  20.  
  21. // NOTICE! Understand what this does before running. 
  22. $result = bp_core_new_subnav_item($args, $component); 
  23.  

Defined (1)

The function is defined in the following location(s).

/bp-core/bp-core-buddybar.php  
  1. function bp_core_new_subnav_item( $args, $component = null ) { 
  2. // Backward compatibility for plugins using `bp_core_new_subnav_item()` without `$component` 
  3. // to add group subnav items. 
  4. if ( null === $component && bp_is_active( 'groups' ) && bp_is_group() && isset( $args['parent_slug'] ) ) { 
  5. /** 
  6. * Assume that this item is intended to belong to the current group if: 
  7. * a) the 'parent_slug' is the same as the slug of the current group, or 
  8. * b) the 'parent_slug' starts with the slug of the current group, and the members nav doesn't have 
  9. * a primary item with that slug. 
  10. */ 
  11. $group_slug = bp_get_current_group_slug(); 
  12. if ( 
  13. $group_slug === $args['parent_slug'] || 
  14. ( 0 === strpos( $args['parent_slug'], $group_slug ) && !buddypress)->members->nav->get_primary( array( 'slug' => $args['parent_slug'] ), false ) ) 
  15. ) { 
  16. $component = 'groups'; 
  17.  
  18. if ( ! $component ) { 
  19. $component = 'members'; 
  20.  
  21. if ( ! bp_is_active( $component ) ) { 
  22. return; 
  23.  
  24. // First, register the subnav item in the nav. 
  25. $subnav_item = bp_core_create_subnav_link( $args, $component ); 
  26.  
  27. /** 
  28. * To mimic legacy behavior, if bp_core_create_subnav_link() returns false, we make an 
  29. * early exit and don't attempt to register the screen function. 
  30. */ 
  31. if ( false === $subnav_item ) { 
  32. return false; 
  33.  
  34. // Then, hook the screen function for the added subnav item. 
  35. $hooked = bp_core_register_subnav_screen_function( $subnav_item, $component ); 
  36. if ( false === $hooked ) { 
  37. return false;