Filter: wpd_alpha_insights_active_parent_menu_item

Control which parent menu item is highlighted as active in the Alpha Insights navigation.

Description

This filter determines which parent menu item appears as active/selected. Useful when you have custom pages or need to override the default active state detection logic.

Location

File: includes/classes/WPDAI_Admin_Menu.php

Method: WPDAI_Admin_Menu::get_active_parent_menu_item()

Line: ~592

Parameters

Parameter	Type	Description
$menu_item_key	string\|null	The currently detected active parent menu item slug

Return

Type: string|null

Description: The menu item slug that should be marked as active

Example Usage

Set Active Menu for Custom Page

add_filter( 'wpd_alpha_insights_active_parent_menu_item', 'custom_page_active_menu' );
function custom_page_active_menu( $menu_item_key )
{
    // If on custom analytics page, highlight Reports menu
    if ( isset( $_GET['page'] ) && $_GET['page'] === 'custom-analytics' )
    {
        return 'reports';
    }
    return $menu_item_key;
}

Route Multiple Pages to Same Parent

add_filter( 'wpd_alpha_insights_active_parent_menu_item', 'group_pages_under_parent' );
function group_pages_under_parent( $menu_item_key )
{
    if ( ! isset( $_GET['page'] ) )
    {
        return $menu_item_key;
    }
    $current_page = $_GET['page'];
    // Multiple pages should highlight "Marketing" parent
    $marketing_pages = array(
        'facebook-campaigns',
        'google-ads-campaigns',
        'email-marketing',
        'social-media'
    );
    if ( in_array( $current_page, $marketing_pages ) )
    {
        return 'marketing';
    }
    return $menu_item_key;
}

Conditional Active State by User Role

add_filter( 'wpd_alpha_insights_active_parent_menu_item', 'role_based_active_menu' );
function role_based_active_menu( $menu_item_key )
{
    // Wholesale users always see Reports as active
    $user = wp_get_current_user();
    if ( in_array( 'wholesale_customer', $user->roles ) )
    {
        // Unless they're specifically in settings
        if ( isset( $_GET['page'] ) && $_GET['page'] === 'settings' ) {
            return 'settings';
        }
        
        return 'wholesale-reports';
    }
    
    return $menu_item_key;
}

Override Based on Query Parameters

add_filter( 'wpd_alpha_insights_active_parent_menu_item', 'query_param_active_menu' );
function query_param_active_menu( $menu_item_key )
{
    // If viewing expense-related report, activate Expenses menu
    if ( isset( $_GET['report_type'] ) && $_GET['report_type'] === 'expenses' )
    {
        return 'expenses';
    }
    // If viewing product cost report, activate Cost of Goods menu
    if ( isset( $_GET['report_type'] ) && $_GET['report_type'] === 'product-costs' )
    {
        return 'cost-of-goods';
    }
    return $menu_item_key;
}

Fallback to Dashboard

add_filter( 'wpd_alpha_insights_active_parent_menu_item', 'fallback_to_dashboard' );
function fallback_to_dashboard( $menu_item_key )
{
    // If no active menu detected, default to dashboard
    if ( empty( $menu_item_key ) )
    {
        return 'dashboard';
    }
    return $menu_item_key;
}

External Page Integration

add_filter( 'wpd_alpha_insights_active_parent_menu_item', 'external_integration_active' );
function external_integration_active( $menu_item_key )
{
    // If on WooCommerce product edit page with cost tab open
    global $pagenow;
    if ( $pagenow === 'post.php' && 
         isset( $_GET['post'] ) && 
         get_post_type( $_GET['post'] ) === 'product' &&
         isset( $_GET['tab'] ) && 
         $_GET['tab'] === 'alpha-insights' )
    {
        return 'cost-of-goods';
    }
    return $menu_item_key;
}

Debug Active Menu Detection

add_filter( 'wpd_alpha_insights_active_parent_menu_item', 'debug_active_menu' );
function debug_active_menu( $menu_item_key )
{
    error_log( sprintf(
        'Active Parent Menu: %s | Current Page: %s',
        $menu_item_key ? $menu_item_key : 'none',
        isset( $_GET['page'] ) ? $_GET['page'] : 'unknown'
    ));
    return $menu_item_key;
}

Best Practices

Always return a valid menu item slug or null
Check if menu item exists in your menu structure
Use early returns for better code readability
Test with different pages and scenarios
Consider user roles and capabilities
Document your custom routing logic

Important Notes

Returned slug must match a key in the menu items array
Default detection uses the $_GET['page'] parameter
Returning null means no parent menu will be highlighted
This only affects visual highlighting, not access control
Filter runs on every admin page load

How Active Detection Works

By default, Alpha Insights determines the active parent menu by:

Checking the page URL parameter
Matching it against registered menu slugs
Applying any overrides defined in settings
Applying this filter for final determination

Visual Effect

The active parent menu item typically:

Has a different background color
Shows an indicator or highlight
May display its submenu expanded
Appears bold or styled differently

Common Use Cases

Scenario	Solution
Custom report page	Return 'reports' to highlight Reports menu
External integration page	Return relevant parent slug based on context
Modal or overlay interface	Return null or preserve existing active state
Grouped functionality	Return common parent for related pages

Troubleshooting

No Menu Highlighted

Verify your custom slug exists in menu items
Check for typos in menu slug
Ensure menu item wasn't removed by another filter

Wrong Menu Highlighted

Check filter priority (use higher priority to override)
Verify conditional logic is correct
Log current values for debugging

Related Filters

wpd_alpha_insights_active_submenu_item - Control active submenu item
wpd_alpha_insights_menu_items - Modify menu structure
wpd_alpha_insights_menu_html - Modify menu HTML