bp_core_register_nav_screen_function

Register a screen function for an item in the main nav array.

Description

(bool|null) bp_core_register_nav_screen_function( (string) $args = '' ); 

Returns (bool|null)

Returns false on failure.

Parameters (1)

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

Options

  • name (string) => ''

    Display name for the nav item.

  • slug (string) => ''

    Unique URL slug for the nav item.

  • item_css_id (bool|string) => ''

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

  • show_for_displayed_user (bool) => null

    Whether the nav item should be visible when viewing a member profile other than your own. 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 nav array. Default: 99.

  • screen_function (callable) => null

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

array(

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

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

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

    /**
     * Optional. Whether the nav item should be visible when viewing a member profile other than your
     * own. Default: true.
     *
     * @type bool
     * @default null
     * @optional
     */
    'show_for_displayed_user' => 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 nav array. Default:
     * 99.
     *
     * @type int
     * @optional
     */
    'position' => 0,

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


Usage

  1. if ( !function_exists( 'bp_core_register_nav_screen_function' ) ) { 
  2. require_once ABSPATH . PLUGINDIR . 'buddypress/bp-core/bp-core-buddybar.php'; 
  3.  
  4. // Array describing the new nav item. 
  5. $args = array( 
  6. 'name' => '', 
  7. 'slug' => '', 
  8. 'item_css_id' => '', 
  9. 'show_for_displayed_user' => null, 
  10. 'site_admin_only' => null, 
  11. 'position' => 0, 
  12. 'screen_function' => null 
  13. ); 
  14.  
  15. // NOTICE! Understand what this does before running. 
  16. $result = bp_core_register_nav_screen_function($args); 
  17.  

Defined (1)

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

/bp-core/bp-core-buddybar.php  
  1. function bp_core_register_nav_screen_function( $args = '' ) { 
  2. $bp =buddypress); 
  3.  
  4. $defaults = array( 
  5. 'name' => false, // Display name for the nav item. 
  6. 'slug' => false, // URL slug for the nav item. 
  7. 'item_css_id' => false, // The CSS ID to apply to the HTML of the nav item. 
  8. 'show_for_displayed_user' => true, // When viewing another user does this nav item show up? 
  9. 'site_admin_only' => false, // Can only site admins see this nav item? 
  10. 'position' => 99, // Index of where this nav item should be positioned. 
  11. 'screen_function' => false, // The name of the function to run when clicked. 
  12. 'default_subnav_slug' => false // The slug of the default subnav item to select when clicked. 
  13. ); 
  14.  
  15. $r = wp_parse_args( $args, $defaults ); 
  16.  
  17. // If we don't have the required info we need, don't register this screen function. 
  18. if ( empty( $r['slug'] ) ) { 
  19. return false; 
  20.  
  21. /** 
  22. * If this is for site admins only and the user is not one,  
  23. * don't register this screen function. 
  24. */ 
  25. if ( ! empty( $r['site_admin_only'] ) && ! bp_current_user_can( 'bp_moderate' ) ) { 
  26. return false; 
  27.  
  28. /** 
  29. * If this nav item is hidden for the displayed user, and 
  30. * the logged in user is not the displayed user 
  31. * looking at their own profile, don't don't register this screen function. 
  32. */ 
  33. if ( empty( $r['show_for_displayed_user'] ) && ! bp_user_has_access() ) { 
  34. return false; 
  35.  
  36. /** 
  37. * If the nav item is visible, we are not viewing a user, and this is a root 
  38. * component, don't attach the default subnav function so we can display a 
  39. * directory or something else. 
  40. */ 
  41. if ( ( -1 != $r['position'] ) && bp_is_root_component( $r['slug'] ) && ! bp_displayed_user_id() ) { 
  42. return; 
  43.  
  44. // Look for current component. 
  45. if ( bp_is_current_component( $r['slug'] ) || bp_is_current_item( $r['slug'] ) ) { 
  46.  
  47. // The requested URL has explicitly included the default subnav 
  48. // (eg: http://example.com/members/membername/activity/just-me/) 
  49. // The canonical version will not contain this subnav slug. 
  50. if ( ! empty( $r['default_subnav_slug'] ) && bp_is_current_action( $r['default_subnav_slug'] ) && ! bp_action_variable( 0 ) ) { 
  51. unset( $bp->canonical_stack['action'] ); 
  52. } elseif ( ! bp_current_action() ) { 
  53.  
  54. // Add our screen hook if screen function is callable. 
  55. if ( is_callable( $r['screen_function'] ) ) { 
  56. add_action( 'bp_screens', $r['screen_function'], 3 ); 
  57.  
  58. if ( ! empty( $r['default_subnav_slug'] ) ) { 
  59.  
  60. /** 
  61. * Filters the default component subnav item. 
  62. * @since 1.5.0 
  63. * @param string $value The slug of the default subnav item 
  64. * to select when clicked. 
  65. * @param array $r Parsed arguments for the nav item. 
  66. */ 
  67. $bp->current_action = apply_filters( 'bp_default_component_subnav', $r['default_subnav_slug'], $r ); 
  68.  
  69. /** 
  70. * Fires after the screen function for an item in the BuddyPress main 
  71. * navigation is registered. 
  72. * @since 2.4.0 
  73. * @param array $r Parsed arguments for the nav item. 
  74. * @param array $args Originally passed in arguments for the nav item. 
  75. * @param array $defaults Default arguments for a nav item. 
  76. */