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/WPD_Admin_Menu.php

Method: WPD_Admin_Menu::get_active_parent_menu_item()

Line: ~592

Parameters

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:

1. Checking the page URL parameter
2. Matching it against registered menu slugs
3. Applying any overrides defined in settings
4. 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

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

Related Classes

• WPD_Admin_Menu – Menu management and rendering