## 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:

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

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

### Related Classes

- `WPDAI_Admin_Menu` - Menu management and rendering