upskill-event-manager/docs/WELCOME-POPUP-SYSTEM.md

HVAC Welcome Popup System Documentation

Overview

The Welcome Popup System provides a guided onboarding experience for new HVAC trainers, introducing them to platform features through an interactive carousel modal. The system respects user account status and provides accessibility-compliant navigation.

Version: 1.0.6
Status: ✅ Complete
Deployed: 2025-08-05

Features

🎯 Core Functionality

• Interactive Carousel: 4-card slideshow introducing platform features
• Account Status Filtering: Only shows to approved users
• Accessibility Compliant: WCAG 2.1 AA standards
• Responsive Design: Works on desktop, tablet, and mobile
• Dismissal Management: "Don't show this again" functionality
• WordPress Integration: Proper theme colors and button styling

📱 User Experience

Content Structure

1. Welcome Card: Platform introduction with 4 key benefits
2. Events Card: Event management features (3 key points)
3. Profile Card: Trainer profile and visibility features (4 key points)
4. Features Card: Reporting and analytics capabilities (3 key points)

Navigation

• Arrow Buttons: Previous/Next navigation
• Dot Indicators: Direct card access
• Keyboard Support: Tab navigation and ESC to close
• Touch Support: Mobile-friendly controls

Technical Implementation

🏗️ Architecture

includes/class-hvac-welcome-popup.php    # Main popup logic
assets/css/hvac-welcome-popup.css        # Styling and layout
assets/js/hvac-welcome-popup.js          # JavaScript functionality

🎨 Styling System

Layout Structure

.hvac-welcome-popup                    # Full-screen overlay
  .hvac-welcome-modal                  # Main modal container
    .hvac-welcome-content              # Content wrapper
      .hvac-welcome-carousel           # Carousel container
        .hvac-welcome-card             # Individual cards
      .hvac-welcome-navigation         # Navigation controls
      .hvac-welcome-footer             # Action buttons

Key CSS Specifications

• Modal: max-width: 800px, max-height: 90vh
• Carousel: min-height: 460px (desktop), responsive scaling
• Navigation: Proper spacing with margin: 20px 0 50px
• Footer: z-index: 10 with white background
• Colors: Astra theme integration with CSS custom properties

🔒 Access Control

Account Status Logic

private function user_can_see_popup() {
    // Admin users: Always show (for testing)
    if (current_user_can('manage_options')) return true;
    
    // Get account status via HVAC_Trainer_Status
    $account_status = HVAC_Trainer_Status::get_trainer_status($user_id);
    
    // Allow: approved, active, inactive users
    // Block: pending, disabled users
    $allowed_statuses = ['approved', 'active', 'inactive'];
    return in_array($account_status, $allowed_statuses);
}

Status Behavior Matrix

Account Status	Popup Shown	Reason
pending	❌ No	Awaiting approval
approved	✅ Yes	Account approved
active	✅ Yes	Recently active
inactive	✅ Yes	Approved but needs re-engagement
disabled	❌ No	Account suspended
Admin	✅ Yes	Testing/management

📝 Content Management

Card Content

Each card contains:

• Icon: Dashicons integration
• Title: Main heading (32px, theme colors)
• Subtitle: Descriptive text
• Bullet Points: 3-4 key features with checkmarks
• Note Section: Additional context (card 1 only)

Dismissal System

• User Meta: hvac_welcome_popup_dismissed
• AJAX Endpoints:
  • hvac_check_welcome_dismissed
  • hvac_dismiss_welcome_popup
• Nonce Security: hvac_welcome_nonce

API Reference

🔌 AJAX Endpoints

Check Dismissal Status

jQuery.post(ajaxurl, {
    action: 'hvac_check_welcome_dismissed',
    nonce: hvac_welcome.nonce
}, function(response) {
    // response.data.dismissed (boolean)
});

Dismiss Popup

jQuery.post(ajaxurl, {
    action: 'hvac_dismiss_welcome_popup',
    nonce: hvac_welcome.nonce,
    dont_show_again: true
}, function(response) {
    // response.success (boolean)
});

🎛️ JavaScript API

Global Object

window.HVACWelcomePopup = {
    showPopup(),
    hidePopup(),
    checkAndShowPopup(),
    nextCard(),
    prevCard(),
    goToCard(index)
}

Events

• hvac:welcome:shown - Popup displayed
• hvac:welcome:dismissed - Popup closed
• hvac:welcome:card-changed - Card navigation

Accessibility Features

♿ WCAG 2.1 AA Compliance

Focus Management

• Proper Tab Order: Close → Navigation → Footer elements
• Focus Indicators: 2px blue outline on all interactive elements
• Keyboard Navigation: Arrow keys, Tab, Enter, ESC support

Touch Targets

• Minimum Size: 44px × 44px on mobile devices
• Proper Spacing: No overlapping clickable areas
• Clear Boundaries: Visual separation between elements

Screen Reader Support

• ARIA Labels: All navigation buttons properly labeled
• Semantic HTML: Proper heading hierarchy
• Alternative Text: Icons have descriptive labels

Motion Preferences

@media (prefers-reduced-motion: reduce) {
    .hvac-welcome-modal,
    .hvac-welcome-card,
    .hvac-welcome-nav { 
        animation: none;
        transition: none;
    }
}

Development History

Version Timeline

v1.0.6 (2025-08-05) - ✅ FINAL

• Fixed: Navigation overlap with content
• Improved: Carousel height calculations
• Enhanced: Mobile responsive spacing
• Status: Production ready

v1.0.5 (2025-08-05)

• Added: Inactive users to allowed status list
• Fixed: Account status filtering logic

v1.0.4 (2025-08-05)

• Changed: From certification_status to account_status
• Improved: Status checking with HVAC_Trainer_Status class

v1.0.3 (2025-08-05)

• Added: Certification status filtering
• Blocked: Pending/disabled users from seeing popup

v1.0.2 (2025-08-05)

• Fixed: Accessibility overlapping elements
• Added: Proper z-index layering
• Improved: WCAG compliance

v1.0.1 (2025-08-05)

• Reduced: Bullet points from 5-6 to 3-4 per card
• Added: Astra theme integration
• Fixed: Overflow scrolling behavior

v1.0.0 (2025-08-05)

• Created: Initial welcome popup system
• Implemented: 4-card carousel design
• Added: Basic dismiss functionality

Testing & Quality Assurance

🧪 Test Coverage

Automated Tests

• File: tests/e2e/welcome-popup-visual-verification.test.ts
• Coverage: Element positioning, interaction, responsiveness
• Screenshots: Automated visual verification

Manual Testing Checklist

• Popup appears for approved users
• Popup blocked for pending/disabled users
• Navigation works on all devices
• Footer elements fully clickable
• Hard refresh shows updated styles
• Dismiss functionality works
• Account status filtering accurate

Browser Compatibility

• ✅ Chrome 90+
• ✅ Firefox 85+
• ✅ Safari 14+
• ✅ Edge 90+
• ✅ Mobile browsers (iOS/Android)

🔧 Troubleshooting

Common Issues

Popup not showing for approved users

# Check user account status
wp eval "echo get_user_meta(USER_ID, 'account_status', true);"

# Reset dismissal
wp eval "delete_user_meta(USER_ID, 'hvac_welcome_popup_dismissed');"

Navigation still overlapping

# Force cache clear and hard refresh
wp cache flush
# Browser: Ctrl+Shift+R

Styling not loading

# Check CSS file exists
ls -la wp-content/plugins/hvac-community-events/assets/css/hvac-welcome-popup.css

# Verify version in file header
head -10 wp-content/plugins/hvac-community-events/assets/css/hvac-welcome-popup.css

Configuration

🛠️ Customization Options

Content Modification

Edit content in: assets/js/hvac-welcome-popup.js lines 50-200

Styling Changes

Edit styles in: assets/css/hvac-welcome-popup.css

Account Status Rules

Modify logic in: includes/class-hvac-welcome-popup.php:user_can_see_popup()

🎯 Performance Optimization

• Conditional Loading: Only loads on trainer pages
• Lazy Initialization: JavaScript loads after DOM ready
• Efficient AJAX: Minimal server requests
• Cache-Friendly: Static assets with version numbers

Security Considerations

🔐 Security Features

• Nonce Verification: All AJAX requests protected
• Capability Checks: User permission validation
• Input Sanitization: All user input sanitized
• XSS Prevention: Proper output escaping

🛡️ Security Best Practices

// Nonce verification
wp_verify_nonce($_POST['nonce'], 'hvac_welcome_nonce');

// Capability check
if (!$this->user_can_see_popup()) {
    wp_send_json_error('Access denied');
}

// Input sanitization
$dont_show_again = (bool) sanitize_text_field($_POST['dont_show_again']);

Conclusion

The HVAC Welcome Popup System provides a comprehensive, accessible, and user-friendly onboarding experience for HVAC trainers. The system properly integrates with WordPress standards, respects user account status, and maintains high accessibility standards.

Key Achievements:

• ✅ Fully accessible (WCAG 2.1 AA)
• ✅ Responsive design
• ✅ Account status aware
• ✅ WordPress standards compliant
• ✅ Production ready

Deployment Status: Live on staging (v1.0.6) - Ready for production deployment when requested.