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

Method: WPD_Admin_Menu::get_active_submenu_item()

Line: ~685

Parameters

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:

1. Checking subpage URL parameter
2. Matching against registered submenu slugs
3. Checking page parameter if no subpage
4. Defaulting to first child if on parent page
5. 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

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

Related Classes

• WPD_Admin_Menu – Menu management and rendering