bp_core_register_nav_screen_function( array|string $args = '' )

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

Description

Parameters

$args

(array|string) (Optional) Array describing the new nav item.

  • 'name'
    (string) Display name for the nav item.
  • 'slug'
    (string) Unique URL slug for the nav item.
  • 'item_css_id'
    (bool|string) Optional. 'id' attribute for the nav item. Default: the value of $slug.
  • 'show_for_displayed_user'
    (bool) Optional. Whether the nav item should be visible when viewing a member profile other than your own. Default: true.
  • 'site_admin_only'
    (bool) Optional. Whether the nav item should be visible only to site admins (those with the 'bp_moderate' cap). Default: false.
  • 'position'
    (int) Optional. Numerical index specifying where the item should appear in the nav array. Default: 99.
  • 'screen_function'
    (callable) The callback function that will run when the nav item is clicked.
  • 'default_subnav_slug'
    (bool|string) Optional. The slug of the default subnav item to select when the nav item is clicked.

Default value: ''

Return

(false|null) Returns false on failure.

Source

File: bp-core/bp-core-buddybar.php

function bp_core_register_nav_screen_function( $args = '' ) {
	$bp = buddypress();

	$defaults = array(
		'name'                    => false, // Display name for the nav item.
		'slug'                    => false, // URL slug for the nav item.
		'item_css_id'             => false, // The CSS ID to apply to the HTML of the nav item.
		'show_for_displayed_user' => true,  // When viewing another user does this nav item show up?
		'site_admin_only'         => false, // Can only site admins see this nav item?
		'position'                => 99,    // Index of where this nav item should be positioned.
		'screen_function'         => false, // The name of the function to run when clicked.
		'default_subnav_slug'     => false  // The slug of the default subnav item to select when clicked.
	);

	$r = wp_parse_args( $args, $defaults );

	// If we don't have the required info we need, don't register this screen function.
	if ( empty( $r['slug'] ) ) {
		return false;
	}

	/**
	 * If this is for site admins only and the user is not one,
	 * don't register this screen function.
	 */
	if ( ! empty( $r['site_admin_only'] ) && ! bp_current_user_can( 'bp_moderate' ) ) {
		return false;
	}

	/**
	 * If this nav item is hidden for the displayed user, and
	 * the logged in user is not the displayed user
	 * looking at their own profile, don't don't register this screen function.
	 */
	if ( empty( $r['show_for_displayed_user'] ) && ! bp_user_has_access() ) {
		return false;
	}

	/**
	 * If the nav item is visible, we are not viewing a user, and this is a root
	 * component, don't attach the default subnav function so we can display a
	 * directory or something else.
	 */
	if ( ( -1 != $r['position'] ) && bp_is_root_component( $r['slug'] ) && ! bp_displayed_user_id() ) {
		return;
	}

	// Look for current component.
	if ( bp_is_current_component( $r['slug'] ) || bp_is_current_item( $r['slug'] ) ) {

		// The requested URL has explicitly included the default subnav
		// (eg: http://example.com/members/membername/activity/just-me/)
		// The canonical version will not contain this subnav slug.
		if ( ! empty( $r['default_subnav_slug'] ) && bp_is_current_action( $r['default_subnav_slug'] ) && ! bp_action_variable( 0 ) ) {
			unset( $bp->canonical_stack['action'] );
		} elseif ( ! bp_current_action() ) {

			// Add our screen hook if screen function is callable.
			if ( is_callable( $r['screen_function'] ) ) {
				add_action( 'bp_screens', $r['screen_function'], 3 );
			}

			if ( ! empty( $r['default_subnav_slug'] ) ) {

				/**
				 * Filters the default component subnav item.
				 *
				 * @since BuddyPress 1.5.0
				 *
				 * @param string $value The slug of the default subnav item
				 *                      to select when clicked.
				 * @param array  $r     Parsed arguments for the nav item.
				 */
				$bp->current_action = apply_filters( 'bp_default_component_subnav', $r['default_subnav_slug'], $r );
			}
		}
	}

	/**
	 * Fires after the screen function for an item in the BuddyPress main
	 * navigation is registered.
	 *
	 * @since BuddyPress 2.4.0
	 *
	 * @param array $r        Parsed arguments for the nav item.
	 * @param array $args     Originally passed in arguments for the nav item.
	 * @param array $defaults Default arguments for a nav item.
	 */
	do_action( 'bp_core_register_nav_screen_function', $r, $args, $defaults );
}

Changelog

Changelog
Version Description
BuddyPress 2.4.0 Introduced.

Questions?

We're always happy to help with code or other questions you might have! Search our developer docs, contact support, or connect with our sales team.