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

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

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

### Related Classes

- `WPDAI_Admin_Menu` - Menu management and rendering