Filter: wpd_alpha_insights_active_submenu_item

Control which submenu item is highlighted as active within a parent menu section.

Description

This filter determines which child/submenu item appears as active/selected under a parent menu. Essential for custom submenu pages or when you need to override the default active submenu detection.

Location

File: includes/classes/WPDAI_Admin_Menu.php

Method: WPDAI_Admin_Menu::get_active_submenu_item()

Line: ~685

Parameters

Parameter	Type	Description
$submenu_item_key	string\|null	The currently detected active submenu item slug
$parent_menu_item_key	string	The parent menu item slug
$children	array	Array of available submenu items under this parent

Return

Type: string|null

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

Example Usage

Set Active Submenu for Custom Page

add_filter( 'wpd_alpha_insights_active_submenu_item', 'custom_active_submenu', 10, 3 );
function custom_active_submenu( $submenu_key, $parent_key, $children )
{
    // Only apply to Reports parent menu
    if ( $parent_key !== 'reports' )
    {
        return $submenu_key;
    }
    // If on custom report page, highlight specific submenu
    if ( isset( $_GET['custom_report'] ) && $_GET['custom_report'] === 'advanced' )
    {
        return 'advanced-reports';
    }
    return $submenu_key;
}

Default to First Submenu

add_filter( 'wpd_alpha_insights_active_submenu_item', 'default_first_submenu', 10, 3 );
function default_first_submenu( $submenu_key, $parent_key, $children )
{
    // If no submenu detected and children exist, activate first one
    if ( empty( $submenu_key ) && ! empty( $children ) )
    {
        return array_key_first( $children );
    }
    return $submenu_key;
}

Route Based on Query Parameters

add_filter( 'wpd_alpha_insights_active_submenu_item', 'query_based_submenu', 10, 3 );
function query_based_submenu( $submenu_key, $parent_key, $children )
{
    // Only for Expenses menu
    if ( $parent_key !== 'expenses' )
    {
        return $submenu_key;
    }
    // Different subpages activate different submenus
    if ( isset( $_GET['subpage'] ) )
    {
        $subpage = sanitize_text_field( $_GET['subpage'] );
        switch ( $subpage )
        {
            case 'add-expense':
                return 'add-new-expense';
            case 'manage-expenses':
                return 'all-expenses';
            case 'expense-categories':
                return 'categories';
            default:
                return $submenu_key;
        }
    }
    return $submenu_key;
}

Context-Aware Submenu Selection

add_filter( 'wpd_alpha_insights_active_submenu_item', 'context_aware_submenu', 10, 3 );
function context_aware_submenu( $submenu_key, $parent_key, $children )
{
    if ( $parent_key !== 'cost-of-goods' )
    {
        return $submenu_key;
    }
    // If editing a product, highlight appropriate submenu
    if ( isset( $_GET['action'] ) && $_GET['action'] === 'edit' && 
         isset( $_GET['product_id'] ) )
    {
        $product = wc_get_product( $_GET['product_id'] );
        if ( $product && $product->is_type( 'variable' ) )
        {
            return 'variable-products';
        }
        else
        {
            return 'simple-products';
        }
    }
    return $submenu_key;
}

Category-Based Submenu

add_filter( 'wpd_alpha_insights_active_submenu_item', 'category_submenu', 10, 3 );
function category_submenu( $submenu_key, $parent_key, $children )
{
    if ( $parent_key !== 'reports' )
    {
        return $submenu_key;
    }
    // Activate submenu based on selected category
    if ( isset( $_GET['category'] ) )
    {
        $category = sanitize_text_field( $_GET['category'] );
        // Map categories to submenu items
        $category_map = array(
            'sales' => 'sales-reports',
            'profit' => 'profit-reports',
            'products' => 'product-reports',
            'customers' => 'customer-reports'
        );
        if ( isset( $category_map[$category] ) )
        {
            return $category_map[$category];
        }
    }
    return $submenu_key;
}

Role-Based Submenu

add_filter( 'wpd_alpha_insights_active_submenu_item', 'role_based_submenu', 10, 3 );
function role_based_submenu( $submenu_key, $parent_key, $children )
{
    if ( $parent_key !== 'dashboard' )
    {
        return $submenu_key;
    }
    // Different default submenu for different user roles
    $user = wp_get_current_user();
    if ( empty( $submenu_key ) )
    {
        if ( in_array( 'shop_manager', $user->roles ) )
        {
            return 'manager-dashboard';
        }
        elseif ( in_array( 'accountant', $user->roles ) )
        {
            return 'financial-dashboard';
        }
    }
    return $submenu_key;
}

Validate Submenu Exists

add_filter( 'wpd_alpha_insights_active_submenu_item', 'validate_submenu', 10, 3 );
function validate_submenu( $submenu_key, $parent_key, $children )
{
    // If detected submenu doesn't exist in children, fallback to first
    if ( ! empty( $submenu_key ) && ! isset( $children[$submenu_key] ) ) {
        error_log( sprintf(
            'Invalid submenu "%s" for parent "%s", falling back to first child',
            $submenu_key,
            $parent_key
        ));
        
        return ! empty( $children ) ? array_key_first( $children ) : null;
    }
    
    return $submenu_key;
}

Best Practices

Always check the $parent_key to target specific parent menus
Verify submenu exists in $children array before returning it
Use early returns for better code readability
Handle null/empty values gracefully
Test with all parent menus that have submenus
Document your custom routing logic

Important Notes

Filter runs for each parent menu that has children
Returned slug must exist in the $children array
Default behavior activates first child if on parent page
Returning null means no submenu will be highlighted
This only affects visual highlighting, not access control

How Active Submenu Detection Works

Alpha Insights determines active submenu by:

Checking subpage URL parameter
Matching against registered submenu slugs
Checking page parameter if no subpage
Defaulting to first child if on parent page
Applying this filter for final determination

Children Array Structure

$children = array(
'submenu-slug-1' => array(
'label' => 'Submenu Item 1',
'url' => '...',
'order' => 1
),
'submenu-slug-2' => array(
'label' => 'Submenu Item 2',
'url' => '...',
'order' => 2
)
);

Common Use Cases

Scenario	Solution
Custom submenu page	Return custom submenu slug based on URL params
Grouped functionality	Map multiple pages to same submenu
Context-based selection	Choose submenu based on data being viewed
Fallback behavior	Return first/last child when no match found

Debugging

add_filter( 'wpd_alpha_insights_active_submenu_item', 'debug_active_submenu', 999, 3 );
function debug_active_submenu( $submenu_key, $parent_key, $children )
{
    error_log( sprintf(
        'Parent: %s | Active Submenu: %s | Available: %s',
        $parent_key,
        $submenu_key ? $submenu_key : 'none',
        implode( ', ', array_keys( $children ) )
    ));
    return $submenu_key;
}

Troubleshooting

No Submenu Highlighted

Check submenu slug matches key in children array
Verify parent menu has children defined
Ensure submenu wasn't removed by another filter

Wrong Submenu Highlighted

Check filter priority (higher priority = later execution)
Verify parent_key is what you expect
Log available children to debug

Related Filters

wpd_alpha_insights_active_parent_menu_item - Control active parent menu
wpd_alpha_insights_menu_items - Modify menu structure
wpd_alpha_insights_menu_html - Modify menu HTML