Add documentation and usage examples for AbTestProxyBlock

[e0ipso]

Add documentation and usage examples for AbTestProxyBlock

Parent Issue: #22 - Add A/B Testing Proxy Block Plugin
Phase: Polish
Depends On: #23, #24, #25, #26 (all core implementation issues)
Recommended Assignee: AI (comprehensive documentation generation)

Objective

Create comprehensive documentation for the AbTestProxyBlock feature, including usage examples, configuration guides, and integration patterns for different A/B testing scenarios.

Documentation Updates Required

1. Update Main README.md

Location: /README.md

Add section: "Proxy Block Testing"

### Proxy Block Testing

The A/B Test Proxy Block allows you to test different block types or configurations against each other, or test the presence vs absence of blocks entirely.

#### Key Features
- **Block Swapping**: Test different block types in the same location
- **Configuration Variants**: Test different configurations of the same block type
- **Presence Testing**: Test having a block vs not having any block
- **Seamless Integration**: Works with existing A/B testing deciders and analytics

#### Basic Usage
1. Add \"A/B Test Proxy Block\" via Layout Builder
2. Configure render mode (block/empty) and target block
3. Set up A/B test with decider plugin to vary proxy configuration
4. Analytics will track interactions with the proxy block container

#### Use Cases
- Testing different content promotion strategies
- Comparing block effectiveness (CTA vs newsletter signup)
- Layout optimization (sidebar content vs clean layout)
- Content personalization experiments

2. Update CLAUDE.md Technical Documentation

Location: /CLAUDE.md

Add detailed technical section:

## A/B Test Proxy Block

### Architecture Overview
The proxy block system enables A/B testing by dynamically selecting which block to render based on A/B test decisions.

**Plugin Location**: `modules/ab_blocks/src/Plugin/Block/AbTestProxyBlock.php`

### Configuration Structure
```php
$config = [
  'render_mode' => 'block|empty',           // Whether to render block or empty
  'target_block_plugin' => 'plugin_id',    // Target block plugin ID
  'target_block_config' => [...],          // Target block configuration array
];

Integration with A/B Testing System

The proxy block integrates with the existing ab_blocks A/B testing infrastructure:

1. Block Placement: Placed via Layout Builder like any block
2. A/B Configuration: Configured through block's A/B testing settings
3. Decision Logic: Decider plugins determine which proxy configuration to use
4. Analytics Tracking: Standard analytics plugins track proxy block interactions

Common A/B Testing Patterns

Pattern 1: Block Type Testing

// Variant A: Show featured content block
'target_block_plugin' => 'custom_featured_content',
'target_block_config' => ['count' => 3],
'render_mode' => 'block'

// Variant B: Show related articles view
'target_block_plugin' => 'views_block:related_articles-block_1', 
'target_block_config' => [],
'render_mode' => 'block'

// Variant C: Show nothing
'render_mode' => 'empty'

Pattern 2: Configuration Testing

// Variant A: Newsletter signup with title
'target_block_plugin' => 'mailchimp_signup',
'target_block_config' => ['show_title' => TRUE, 'button_text' => 'Subscribe Now'],
'render_mode' => 'block'

// Variant B: Newsletter signup minimal
'target_block_plugin' => 'mailchimp_signup',
'target_block_config' => ['show_title' => FALSE, 'button_text' => 'Join'],
'render_mode' => 'block'

Development Guidelines

• Always validate target block plugin existence in configuration
• Handle target block instantiation failures gracefully
• Bubble cache metadata from target blocks properly
• Respect access control from target blocks
• Log errors for debugging without exposing to users

### 3. Create Usage Examples Documentation

**Location**: `/docs/proxy-block-examples.md` (new file)

```markdown
# A/B Test Proxy Block Examples

This document provides practical examples of using the A/B Test Proxy Block for common testing scenarios.

## Example 1: Homepage Hero Section Testing

**Scenario**: Test different hero section approaches on the homepage.

### Setup
1. Place \"A/B Test Proxy Block\" in the hero region via Layout Builder
2. Configure A/B testing with RandomDecider (50/50 split)
3. Set up three variants:

**Variant A - Video Hero**:
```php
'render_mode' => 'block',
'target_block_plugin' => 'custom_video_hero',
'target_block_config' => [
  'video_url' => '/themes/custom/mytheme/videos/hero.mp4',
  'overlay_text' => 'Welcome to Our Site'
]

Variant B - Image Carousel:

'render_mode' => 'block', 
'target_block_plugin' => 'views_block:hero_images-carousel',
'target_block_config' => [
  'autoplay' => TRUE,
  'duration' => 5000
]

Variant C - Minimal Text:

'render_mode' => 'block',
'target_block_plugin' => 'custom_html',
'target_block_config' => [
  'content' => '<h1>Simple. Effective. Powerful.</h1>'
]

Analytics Setup

• Track click-through rates to main CTA buttons
• Measure scroll depth and engagement time
• Monitor conversion rates for key actions

Example 2: Sidebar Content Optimization

Scenario: Determine the most effective sidebar content for blog posts.

Setup

1. Place proxy block in sidebar region for blog content type
2. Use EntityViewModeDecider based on node ID for consistent experience
3. Configure variants:

Variant A - Related Articles:

'render_mode' => 'block',
'target_block_plugin' => 'views_block:related_content-sidebar',
'target_block_config' => ['items_per_page' => 5]

Variant B - Newsletter Signup:

'render_mode' => 'block',
'target_block_plugin' => 'mailchimp_signup',
'target_block_config' => [
  'title' => 'Stay Updated',
  'description' => 'Get our latest articles delivered to your inbox.'
]

Variant C - No Sidebar (cleaner layout):

'render_mode' => 'empty'

Expected Results

• Track newsletter signups vs content engagement
• Measure reading completion rates
• Monitor overall page dwell time

Example 3: E-commerce Product Recommendations

Scenario: Test different product recommendation strategies.

Setup

1. Place proxy block below product details
2. Use CustomerSegmentDecider to target different user types
3. Configure personalized variants:

Variant A - Similar Products:

'render_mode' => 'block',
'target_block_plugin' => 'commerce_product_recommendations',
'target_block_config' => [
  'algorithm' => 'similar_products',
  'count' => 4,
  'show_prices' => TRUE
]

Variant B - Frequently Bought Together:

'render_mode' => 'block',
'target_block_plugin' => 'commerce_product_recommendations', 
'target_block_config' => [
  'algorithm' => 'frequently_bought_together',
  'count' => 3,
  'show_bundle_discount' => TRUE
]

Variant C - Recently Viewed:

'render_mode' => 'block',
'target_block_plugin' => 'commerce_recently_viewed',
'target_block_config' => [
  'count' => 6,
  'exclude_current' => TRUE
]

Success Metrics

• Add-to-cart rates for recommended products
• Revenue attribution from recommendations
• User engagement with recommendation blocks

Example 4: Call-to-Action Testing

Scenario: Test different approaches to driving user registration.

Variants to Test:

Variant A - Traditional Form:

'render_mode' => 'block',
'target_block_plugin' => 'user_registration_form',
'target_block_config' => [
  'show_required_fields_only' => TRUE,
  'submit_button_text' => 'Create Account'
]

Variant B - Social Login:

'render_mode' => 'block',
'target_block_plugin' => 'social_auth_buttons',
'target_block_config' => [
  'providers' => ['google', 'facebook', 'twitter'],
  'button_style' => 'large'
]

Variant C - Benefits-focused CTA:

'render_mode' => 'block',
'target_block_plugin' => 'custom_html',
'target_block_config' => [
  'content' => '<div class=\"cta-benefits\">
    <h3>Join thousands of satisfied customers</h3>
    <ul><li>Free shipping</li><li>Exclusive deals</li><li>Priority support</li></ul>
    <a href=\"/user/register\" class=\"btn btn-primary\">Start Saving Today</a>
  </div>'
]

Configuration Best Practices

1. Block Selection Guidelines

• Choose blocks that serve similar purposes for meaningful comparisons
• Ensure target blocks are compatible with the page context
• Test block access permissions across user roles

2. A/B Test Design

• Use appropriate decider plugins for your testing goals
• Consider user experience consistency (avoid jarring changes)
• Plan for sufficient sample sizes before drawing conclusions

3. Performance Considerations

• Monitor cache hit rates for different variants
• Consider the performance impact of complex target blocks
• Use appropriate cache contexts for personalized content

4. Analytics and Measurement

• Define success metrics before starting tests
• Set up proper event tracking for meaningful interactions
• Plan for statistical significance in your test duration

Troubleshooting Common Issues

Issue: Proxy block shows error message

Solution: Check that target block plugin exists and configuration is valid

Issue: Target block doesn't appear

Solution: Verify user has permission to view target block content

Issue: A/B test not switching variants

Solution: Clear caches and verify decider plugin configuration

Issue: Analytics not tracking

Solution: Ensure analytics tracker is configured and JavaScript is loading

Integration with Contrib Modules

Layout Builder Enhancements

• Compatible with Layout Builder restrictions
• Works with Layout Builder permissions
• Supports Layout Builder symmetric translations

Commerce Integration

• Test product display blocks
• Compare checkout flow components
• Optimize cart and wishlist blocks

Content Personalization

• Integrate with Smart Content module decisions
• Use with Audiences and Context modules
• Combine with Rules module for complex logic

### 4. Update Inline Code Documentation

**Add comprehensive phpDoc blocks**:

```php
/**
 * Provides an A/B Test Proxy Block.
 *
 * This block acts as a proxy for other blocks, allowing A/B testing by
 * dynamically selecting which block to render based on A/B test configuration.
 * It supports testing different block types, configurations, or testing
 * presence vs absence of blocks entirely.
 *
 * Configuration options:
 * - render_mode: 'block' to render target block, 'empty' to render nothing
 * - target_block_plugin: Plugin ID of the block to proxy
 * - target_block_config: Configuration array for the target block
 *
 * The proxy block integrates with the existing ab_blocks A/B testing system,
 * working with decider plugins to determine which configuration to use and
 * analytics plugins to track user interactions.
 *
 * @Block(
 *   id = \"ab_test_proxy_block\",
 *   admin_label = @Translation(\"A/B Test Proxy Block\"),
 *   category = @Translation(\"A/B Testing\"),
 *   context_definitions = {
 *     \"entity\" = @ContextDefinition(\"entity\", required = FALSE),
 *   }
 * )
 */
class AbTestProxyBlock extends BlockBase implements ContainerFactoryPluginInterface {
  // ... implementation with detailed method documentation
}

5. Configuration Schema Documentation

Location: modules/ab_blocks/config/schema/ab_blocks.schema.yml

Add comprehensive schema comments:

block.settings.ab_test_proxy_block:
  type: mapping
  label: 'A/B Test Proxy Block settings'
  mapping:
    render_mode:
      type: string
      label: 'Render mode'
      # Determines whether to render the target block or show empty content
      # Values: 'block' (render target block) or 'empty' (render nothing)
    target_block_plugin:
      type: string  
      label: 'Target block plugin ID'
      # The plugin ID of the block to render when render_mode is 'block'
      # Must be a valid block plugin that exists in the system
    target_block_config:
      type: sequence
      label: 'Target block configuration'
      # Configuration array passed to the target block plugin
      # Structure depends on the target block's configuration schema
      sequence:
        type: string

Testing Documentation

Manual Testing Checklist

Create checklist for QA testing:

## A/B Test Proxy Block - Testing Checklist

### Basic Functionality
- [ ] Block appears in Layout Builder under \"A/B Testing\" category
- [ ] Configuration form loads without errors
- [ ] Block selection dropdown populates with available blocks
- [ ] Render mode selection works (block/empty)
- [ ] Form validation prevents invalid configurations
- [ ] Block saves and displays configured content correctly

### A/B Testing Integration  
- [ ] Block works with RandomDecider plugin
- [ ] Block works with TimeoutDecider plugin
- [ ] Different variants display different content
- [ ] Analytics tracking fires correctly
- [ ] Cache invalidation works properly

### Error Handling
- [ ] Invalid target block configuration handled gracefully
- [ ] Missing target block plugin shows appropriate error
- [ ] Access denied scenarios work correctly
- [ ] Form errors display user-friendly messages

### Performance
- [ ] Cache metadata bubbles correctly from target blocks
- [ ] Page load times acceptable with proxy blocks
- [ ] Memory usage within expected limits

Acceptance Criteria

• README.md updated with proxy block overview and basic usage
• CLAUDE.md contains comprehensive technical documentation
• Detailed usage examples document created with real-world scenarios
• All public methods have comprehensive phpDoc documentation
• Configuration schema thoroughly documented
• Manual testing checklist created for QA
• Troubleshooting guide covers common issues
• Integration patterns documented for contrib modules

Context for AI Implementation

This is a comprehensive documentation task requiring:

1. User-Focused Documentation: Write for different audiences (end users, developers, QA)
2. Practical Examples: Provide real-world scenarios that users can relate to
3. Technical Accuracy: Ensure all code examples and technical details are correct
4. Comprehensive Coverage: Document all features, edge cases, and integration points
5. Maintainable Structure: Organize documentation for easy updates and navigation

Documentation Strategy:

• Start with user benefits and use cases
• Provide step-by-step implementation guides
• Include code examples with explanations
• Cover troubleshooting and best practices
• Reference existing A/B testing documentation patterns
• Use consistent terminology throughout

Key Focus Areas:

• Real-world usage examples that demonstrate value
• Clear configuration examples with expected outcomes
• Integration guidance for common Drupal contrib modules
• Performance and best practice recommendations
• Troubleshooting common implementation issues