Hooks: Search, Hashtags, Sidebar, and Admin

The action and filter seams for unified search, the hashtag system, the search index, the right-sidebar widgets (greeting, streak, this-week stats, leaderboard, gamification overlays), and the admin information architecture. This page is for developers building search drivers, hashtag analytics, gamification sidebars, or admin extensions that add or relocate settings tabs. Every hook below is fired or applied by BuddyNext Free, so it is available without Pro - and the Pro search seams (buddynext_search_query_args / buddynext_search_filter_options) are listed here because they are the points Pro plugs its advanced member filters into.

Overview / Contract

• Search has a layered extension model. You can replace the entire result set with an external driver (buddynext_search_results), shape the query args before the built-in SQL runs (buddynext_search_query_args), enrich each row after it returns (buddynext_search_item), or react to a completed search (buddynext_search_performed). Pick the lowest-impact seam that does the job.
• Do not drop rows in buddynext_search_item. That filter is mutate-only. Removing items there desyncs the total count and the cursor. To exclude results, constrain the query through buddynext_search_query_args.
• Sidebar gamification seams are null-default overrides. Every buddynext_user_weekly_*, buddynext_user_activity_*, and buddynext_user_active_dates filter passes null by default; BuddyNext runs its own inline SQL only when the filter returns null. A gamification plugin returns its canonical value to take over, and BuddyNext skips the query entirely.
• Admin tabs register against their origin section, then the hub places them. A registrar always passes its own domain section to register_tab(); the canonical TAB_PLACEMENT map (filtered by bn_admin_hub_tab_placement) decides the final section, sidebar position, and visibility. This keeps the information architecture in one place while every feature stays decoupled.

Search seams

Note: buddynext_search_query_args is where the member_label, tier_slug, space_id, and joined_after keys enter the query. BuddyNext Free reads any of those keys if present, but only BuddyNext Pro populates them (and populates buddynext_search_filter_options so the controls appear). The page degrades cleanly with Pro inactive: no provider, no control.

scope_space_id - search inside one space

scope_space_id is a Free key on the same filter. It restricts content results to a single space, narrowing the existing visibility rules rather than replacing them, and it is what powers the in-space search box on a space's Feed tab.

add_filter( 'buddynext_search_query_args', function ( array $args, string $query, int $viewer_id ): array {
    $args['scope_space_id'] = 42;   // content from space 42 only
    return $args;
}, 10, 3 );

Do not reach for space_id to do this. The two keys look interchangeable and are not:

space_id is one of Pro's five advanced keys, and AdvancedSearchFilters::apply_pro_args() strips it whenever the viewer fails the search.saved_advanced entitlement - which includes every anonymous visitor. Scoping a free feature to it would work on a Free-only site and then silently stop working the moment monetization was switched on, handing the member the whole community's results while the interface told them they had searched one space. Two concerns, two keys, deliberately.

scope_space_id is not applied to member searches (user and member types), because user rows carry no space_id of their own and the column test would match nothing.

Hashtag seams

The hashtag system also exposes the full buddynext_part_hashtag_* template-part family (hero, posts list, sidebar-about, sidebar-related, sidebar-top-contributors, empty-state), each with the standard _before / _after / _args / _classes four-hook contract. See Hooks: Template Parts for that convention.

Search index

Sidebar and gamification seams

The right sidebar is the main surface a gamification plugin augments. The greeting/streak card, the this-week stats card, and the profile hero all expose override filters that default to null or empty, so BuddyNext computes a fallback only when nothing hooks them.

Sidebar injection points

Streak override filters (greeting/streak card)

This-week stats override filters

Each metric on the this-week stats card defaults to null so a gamification plugin can supply its canonical figure; the inline COUNT runs only on a null return.

Tip: Returning a real value from any of these short-circuits BuddyNext's own query, so an integration that already tracks the metric removes that query from the page render. Return null to fall back to BuddyNext's computation.

Admin information-architecture seams

The admin hub owns the BuddyNext top-level menu and arranges every settings tab into a fixed set of sections (Settings, Platform, Members, Spaces, Engagement, Notifications, Realtime and Push, Campaigns, Moderation, Moderation Tools, Monetization). A section appears in the sub-menu only once a tab is registered into it.

Note: bn_admin_hub_sections and bn_admin_hub_tab_placement use the internal bn_* prefix because they wire admin chrome. They are stable extension points, but treat the section/tab keys as the public contract rather than the surrounding admin classes. See Hooks Overview for the buddynext_* vs bn_* distinction.

Examples

Relocate an admin tab via bn_admin_hub_tab_placement

The placement map is keyed by a tab's origin section:slug. Each rule can set the final section, the sidebar position (lower sorts earlier), or hidden. This moves the webhooks tab out of Settings into Notifications, and hides the social-connections tab entirely:

add_filter(
	'bn_admin_hub_tab_placement',
	function ( $map ) {
		// Move the webhooks tab from Settings to the Notifications section.
		$map['settings:webhooks']['section']  = 'notifications';
		$map['settings:webhooks']['position'] = 40;

		// Hide a tab without touching the code that registers it.
		$map['settings:social']['hidden'] = true;

		return $map;
	}
);

To add a brand-new top-level section for your own tabs to live in, register it first via bn_admin_hub_sections (it stays hidden until a tab lands in it):

add_filter(
	'bn_admin_hub_sections',
	function ( $sections ) {
		$sections['marketplace'] = array(
			'slug'  => 'buddynext-marketplace',
			'label' => __( 'Marketplace', 'my-ext' ),
		);
		return $sections;
	}
);

Add a sidebar widget seam via buddynext_right_sidebar

buddynext_right_sidebar fires inside the right-sidebar column on every hub that opts in, passing the current hub slug so you can scope your widget to specific surfaces:

add_action(
	'buddynext_right_sidebar',
	function ( $hub ) {
		// Only show this widget on the home feed and the explore hub.
		if ( ! in_array( $hub, array( 'home', 'explore' ), true ) ) {
			return;
		}

		printf(
			'<section class="bn-sidebar-card my-streak-widget"><h3>%s</h3><p>%s</p></section>',
			esc_html__( 'Your reputation', 'my-ext' ),
			esc_html( my_gamification_reputation_line( get_current_user_id() ) )
		);
	}
);

Supply a gamification streak so BuddyNext skips its own query

add_filter(
	'buddynext_user_activity_streak',
	function ( $streak, $user_id ) {
		// Our plugin already tracks streaks - return ours and BuddyNext
		// skips its 30-day UNION query for this card.
		return (int) my_gamification_current_streak( $user_id );
	},
	10,
	2
);

Notes and gotchas

• Choose the right search seam. Use buddynext_search_query_args to constrain or extend the query, buddynext_search_results to replace the engine wholesale, and buddynext_search_item only to annotate rows. Never delete rows in buddynext_search_item - it breaks pagination totals.
• The Pro search filters are present but unpopulated in Free. buddynext_search_query_args and buddynext_search_filter_options are the exact points BuddyNext Pro injects advanced member filters; your own driver can use the same keys without Pro.
• Sidebar override filters trade a query for your value. Returning a real value from the buddynext_user_weekly_* / buddynext_user_activity_* filters removes the corresponding inline query from the page render. Return null to keep BuddyNext's fallback.
• Admin sections are hidden until populated. Registering a section via bn_admin_hub_sections does not show it; it appears only once a tab is placed into it. Hidden tabs ('hidden' => true) still keep their registration, so removing the filter restores them.
• Free vs Pro. Every hook here is Free. Pro contributes tabs into the same hub sections, populates the same search filters, and can override the same sidebar metrics - there is no separate Pro hub or Pro search pipeline. For the moderation, safeguard, and authentication seams, see Hooks: Moderation, Trust, and Authentication.