bp_core_register_subnav_screen_function

Register a screen function, whether or not a related subnav link exists.

Description

(bool|null) bp_core_register_subnav_screen_function( (string) $args = '', (string) $component = 'members' ); 

Returns (bool|null)

Returns false on failure.

Parameters (2)

0. $args — Optional. (string) => ''
Array describing the new subnav item.

Options

  • 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.

  • 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(

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

Defined (1)

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

/bp-core/bp-core-buddybar.php  
  1. function bp_core_register_subnav_screen_function( $args = '', $component = 'members' ) { 
  2. $bp = buddypress(); 
  3.  
  4. $r = wp_parse_args( $args, array( 
  5. 'slug' => false, // URL slug for the screen. 
  6. 'parent_slug' => false, // URL slug of the parent screen. 
  7. 'user_has_access' => true, // Can the user visit this screen? 
  8. 'no_access_url' => '',  
  9. 'site_admin_only' => false, // Can only site admins visit this screen? 
  10. 'screen_function' => false, // The name of the function to run when clicked. 
  11. ) ); 
  12.  
  13. /** 
  14. * Hook the screen function for the added subnav item. But this only needs to 
  15. * be done if this subnav item is the current view, and the user has access to the 
  16. * subnav item. We figure out whether we're currently viewing this subnav by 
  17. * checking the following two conditions: 
  18. * (1) Either: 
  19. * (a) the parent slug matches the current_component, or 
  20. * (b) the parent slug matches the current_item 
  21. * (2) And either: 
  22. * (a) the current_action matches $slug, or 
  23. * (b) there is no current_action (ie, this is the default subnav for the parent nav) 
  24. * and this subnav item is the default for the parent item (which we check by 
  25. * comparing this subnav item's screen function with the screen function of the 
  26. * parent nav item in the component's primary nav). This condition only arises 
  27. * when viewing a user, since groups should always have an action set. 
  28. */ 
  29.  
  30. // If we *don't* meet condition (1), return. 
  31. if ( ! bp_is_current_component( $r['parent_slug'] ) && ! bp_is_current_item( $r['parent_slug'] ) ) { 
  32. return; 
  33.  
  34. $parent_nav = $bp->{$component}->nav->get_primary( array( 'slug' => $r['parent_slug'] ), false ); 
  35.  
  36. // If we *do* meet condition (2), then the added subnav item is currently being requested. 
  37. if ( ( bp_current_action() && bp_is_current_action( $r['slug'] ) ) || ( bp_is_user() && ! bp_current_action() && ! empty( $parent_nav->screen_function ) && $r['screen_function'] == $parent_nav->screen_function ) ) { 
  38.  
  39. // If this is for site admins only and the user is not one, don't create the subnav item. 
  40. if ( ! empty( $r['site_admin_only'] ) && ! bp_current_user_can( 'bp_moderate' ) ) { 
  41. return false; 
  42.  
  43. $hooked = bp_core_maybe_hook_new_subnav_screen_function( $r, $component ); 
  44.  
  45. // If redirect args have been returned, perform the redirect now. 
  46. if ( ! empty( $hooked['status'] ) && 'failure' === $hooked['status'] && isset( $hooked['redirect_args'] ) ) { 
  47. bp_core_no_access( $hooked['redirect_args'] );