bp_core_create_subnav_link

Add a subnav link to the BuddyPress navigation.

Description

(bool|object) bp_core_create_subnav_link( (string) $args = '', (string) $component = 'members' ); 

Returns (bool|object)

Returns false on failure, new BP_Core_Nav_Item instance on success.

Parameters (2)

0. $args — Optional. (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. (string) => 'members'
The component the navigation is attached to. Defaults to members..

Usage

  1. if ( !function_exists( 'bp_core_create_subnav_link' ) ) { 
  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 = 'members'; 
  20.  
  21. // NOTICE! Understand what this does before running. 
  22. $result = bp_core_create_subnav_link($args, $component); 
  23.  

Defined (1)

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

/bp-core/bp-core-buddybar.php  
  1. function bp_core_create_subnav_link( $args = '', $component = 'members' ) { 
  2. $bp =buddypress); 
  3.  
  4. $r = wp_parse_args( $args, array( 
  5. 'name' => false, // Display name for the nav item. 
  6. 'slug' => false, // URL slug for the nav item. 
  7. 'parent_slug' => false, // URL slug of the parent nav item. 
  8. 'parent_url' => false, // URL of the parent item. 
  9. 'item_css_id' => false, // The CSS ID to apply to the HTML of the nav item. 
  10. 'user_has_access' => true, // Can the logged in user see this nav item? 
  11. 'no_access_url' => '',  
  12. 'site_admin_only' => false, // Can only site admins see this nav item? 
  13. 'position' => 90, // Index of where this nav item should be positioned. 
  14. 'screen_function' => false, // The name of the function to run when clicked. 
  15. 'link' => '', // The link for the subnav item; optional, not usually required. 
  16. 'show_in_admin_bar' => false, // Show the Manage link in the current group's "Edit" Admin Bar menu. 
  17. ) ); 
  18.  
  19. // If we don't have the required info we need, don't create this subnav item. 
  20. if ( empty( $r['name'] ) || empty( $r['slug'] ) || empty( $r['parent_slug'] ) || empty( $r['parent_url'] ) || empty( $r['screen_function'] ) ) 
  21. return false; 
  22.  
  23. // Link was not forced, so create one. 
  24. if ( empty( $r['link'] ) ) { 
  25. $r['link'] = trailingslashit( $r['parent_url'] . $r['slug'] ); 
  26.  
  27. $parent_nav = $bp->{$component}->nav->get_primary( array( 'slug' => $r['parent_slug'] ), false ); 
  28.  
  29. // If this sub item is the default for its parent, skip the slug. 
  30. if ( $parent_nav ) { 
  31. $parent_nav_item = reset( $parent_nav ); 
  32. if ( ! empty( $parent_nav_item->default_subnav_slug ) && $r['slug'] === $parent_nav_item->default_subnav_slug ) { 
  33. $r['link'] = trailingslashit( $r['parent_url'] ); 
  34.  
  35. // If this is for site admins only and the user is not one, don't create the subnav item. 
  36. if ( ! empty( $r['site_admin_only'] ) && ! bp_current_user_can( 'bp_moderate' ) ) { 
  37. return false; 
  38.  
  39. if ( empty( $r['item_css_id'] ) ) { 
  40. $r['item_css_id'] = $r['slug']; 
  41.  
  42. $subnav_item = array( 
  43. 'name' => $r['name'],  
  44. 'link' => $r['link'],  
  45. 'slug' => $r['slug'],  
  46. 'parent_slug' => $r['parent_slug'],  
  47. 'css_id' => $r['item_css_id'],  
  48. 'position' => $r['position'],  
  49. 'user_has_access' => $r['user_has_access'],  
  50. 'no_access_url' => $r['no_access_url'],  
  51. 'screen_function' => &$r['screen_function'],  
  52. 'show_in_admin_bar' => (bool) $r['show_in_admin_bar'],  
  53. ); 
  54.  
  55. buddypress)->{$component}->nav->add_nav( $subnav_item ); 
  56.  
  57. return $subnav_item;