upskill-event-manager/docs/implementation_plan.md

Implementation Plan: Phase 1 & 2 Features

This document outlines the implementation plan for Phase 1 & 2 features of the HVAC Community Events Management System.

Goal

Implement Phase 1 features: Community Login Page, Registration Page, Basic Dashboard, Create/Modify Event Pages, Event Summary Page. Implement Phase 2 features: Zoho CRM API Integration, Email Attendees functionality, Enhanced event management, and Comprehensive transaction reporting.

Design References

The implementation should follow the design patterns and layouts shown in the reference screenshots located in the design_references/ directory:

• upskillhvac.com_hce-dashboard_ (4).png: Trainer dashboard layout with statistics and events table
• upskillhvac.com_hce-event-summary__event_id=1662 (1).png: Event summary page with details and transactions
• upskillhvac.com_hce-login_.png: Login page layout and styling
• upskillhvac.com_hce-modify-event__event_id=1662.png: Event editing interface

These design references serve as visual guides for layout, information organization, and user interface elements.

WordPress Theme Integration

All implementations must leverage the existing WordPress theme (Upskill HVAC, a child theme of Astra) and styling plugins:

• Use theme hooks and filters for template modifications
• Utilize theme-provided CSS classes rather than creating custom styling
• Ensure responsive behavior matches theme's breakpoints
• Leverage Spectra Pro components for enhanced layouts
• Use Essential Blocks for advanced UI components when appropriate
• Follow the theme's color scheme and typography

Current Focus & Next Steps (As of 2025-04-08 13:52:00)

Status: Investigating test environment issues in staging deployment.

• Unit tests failing with the following issues:
  • Path resolution problems in test-event-summary-data.php
  • Database connection issues in staging environment
• Integration tests partially working:
  • Dashboard data retrieval tests failing (0 events when expecting 5)
  • Event management tests skipped due to TEC CE active state
• E2E tests status unchanged from previous update

Next Steps:

• Fix test environment issues:
  1. Correct file paths in test-event-summary-data.php
  2. Implement or fix process_event_submission method
  3. Configure proper database access for tests
• Re-evaluate test strategy for TEC CE integration
• Continue with Phase 2 planning after test environment stabilization

---

Original Plan (Archive):

1. Verify E2E Login Tests: Run the E2E tests for the Community Login page (Task 2.8) to confirm the recent fixes were successful. (Requires Test Mode) - DONE
2. Update Status: Update memory-bank/progress.md and memory-bank/activeContext.md based on the test results (pass/fail). - DONE
3. Proceed with Implementation Plan:
   • If tests pass: Identify the next task from the "Tasks" section below (e.g., Task 0.6 unit test validation, Task 1.10 registration E2E tests, Task 3 Trainer Dashboard). (Likely requires Code Mode or Test Mode)
   • If tests fail: Further investigation and debugging are needed. (Requires Debug Mode)

Workflow Diagram (Archive):

graph TD
    A[Start: Verify E2E Login Tests] --> B{Run E2E Login Tests (Test Mode)};
    B --> C{Tests Pass?};
    C -- Yes --> D[Update Memory Bank (Pass)];
    D --> E[Identify Next Task from Plan Below];
    E --> F[Switch to Code/Test Mode for Implementation];
    C -- No --> G[Update Memory Bank (Fail)];
    G --> H[Switch to Debug Mode];

---

Tasks

• Phase 1: Core Functionality

  • 0. Development Environment Setup

    • 0.1. Configure Docker environment with WordPress, Nginx, and MariaDB
    • 0.2. Set up PHP-FPM configuration
    • 0.3. Configure WordPress with proper settings
    • 0.4. Set up development domain and SSL
    • 0.5. Implement development scripts
    • 0.6. Configure testing environment
      • PHPUnit setup complete
      • WordPress test framework installed
      • Created test bootstrap file
      • Test database configuration
      • Updated wp-tests-config.php with Docker environment settings
      • Configured test framework file locations
      • Run initial unit tests to validate environment [2025-03-30]

  • 1. Implement Community Registration Page

    • 1.1. Create a custom registration form with the required fields as specified in docs/REQUIREMENTS.md.
    • 1.2. Implement input validation and sanitization as specified in docs/REQUIREMENTS.md.
    • 1.3. Implement logic to create a new user with the "hvac_trainer" role.
    • 1.4. Implement logic to create a Training Venue Profile if the user selects "Yes".
    • 1.5. Implement logic to add custom fields to the user's profile, including mapping to The Events Calendar organizer fields.
    • 1.6. Implement email notification to admin upon new registration.
    • 1.7. Use Astra theme form styling and responsive layout patterns.
    • 1.8. Add unit tests for registration form validation.
    • 1.9. Add integration tests to verify user creation, profile updates, and organizer mapping.
    • 1.10. Perform E2E tests [2025-03-31]

  • 2. Implement Community Login Page

    • 2.1. Create a custom login form using theme-compatible styling.
    • 2.2. Implement authentication logic (core WP auth, failure redirect).
    • 2.3. Implement "Remember me" option.
    • 2.4. Implement password reset functionality.
    • 2.5. Redirect to Trainer Dashboard after successful login.
    • 2.6. Style the login page using Astra theme components (basic styling).
    • 2.7. Add unit tests for authentication logic.
    • 2.8. Add integration tests to verify login and redirection.

    Testing Details

    Unit Tests (2.7):

    • Authentication with valid/invalid credentials
    • Redirect logic for success/failure cases
    • "Remember me" cookie functionality
    • Password reset flow validation

    Integration Tests (2.8):

    • Complete login form submission flow

    • Role-based access verification

    • Session management

    • Error handling

    • Status (2025-03-29): All E2E tests for login functionality passed after fixes. E2E Tests:

    • Browser-based login scenarios

    • Mobile responsiveness

    • Cross-browser compatibility

  • 3. Implement Trainer Dashboard (Core complete, pending UI refinement)

    • 3.1. Create a custom dashboard page template that extends the theme's default template.
    • 3.2. Add navigation buttons for Create Event, View Trainer Profile, and Logout using theme button styles.
    • 3.3. Implement Overall Statistics Summary using theme-compatible cards or blocks.
    • 3.4. Implement Events Table using theme's table styling.
    • 3.5. Add sorting/filtering capabilities using theme-styled tabs.
    • 3.6. Ensure responsive behavior matches theme's breakpoints. (Basic E2E check done)
    • 3.7. Add unit tests for dashboard statistics calculations.
    • 3.8. Add integration tests to verify dashboard data is displayed correctly. (Access control tests skipped)

  • 3.9. UI Refinement & Styling (Completed 2025-04-01)

    • 4. Implement Create/Modify Event Pages (Fallback logic & basic UI complete)

      • 4.1. Create custom event creation and modification pages using theme templates. (Page created via activation hook, shortcode used)
      • 4.2. Leverage functionality from The Events Calendar Community Events plugin. (Primary path uses TEC CE handler/functions)
      • 4.3. Add instructions section to the pages using theme typography.
      • 4.4. Add Return to Dashboard button using theme button styles.
      • 4.5. Ensure form styling matches theme patterns. (Basic container/button styling applied)
      • 4.6. Add unit tests for event creation and modification logic. (Removed - TEC CE handles form submission)
      • 4.7. Add integration tests to verify events are created and modified correctly in The Events Calendar. [2025-04-01]

    • 5. Implement Event Summary Page (Core complete, transaction test skipped)

      • 5.1. Create a custom event summary page template based on the theme's single post template.
      • 5.2. Display Event Details in theme-styled card sections.
      • 5.3. Implement breadcrumb navigation using theme's breadcrumb component.
      • 5.4. Format content sections using theme's typography and spacing.
      • 5.5. Implement Transactions Table using theme's table styling.
      • 5.6. Ensure all buttons use theme's button classes and styling.
      • 5.7. Add unit tests for event summary data retrieval.
      • 5.8. Add integration tests to verify event summary data is displayed correctly. (Transaction test skipped due to env issues)

    • 6. Customize TEC Community Events Pages (via Child Theme Overrides) - ABANDONED

      • [ ] 6.1. Create override directory: upskill-hvac-astra-child/tribe-events/community/.
      • [ ] 6.2. Copy original templates (edit-event.php, event-list.php, edit-organizer.php) to override directory.
      • [ ] 6.3. Customize edit-event.php override:
        • [ ] Add Astra theme wrapper (#primary, #main).
        • [ ] Add Astra breadcrumbs.
        • [ ] Add action buttons (Return to Dashboard, View Event).
      • [ ] 6.4. Customize event-list.php override:
        • [ ] Add Astra theme wrapper (#primary, #main).
        • [ ] Add Astra breadcrumbs.
        • [ ] Add action buttons (Return to Dashboard, Add New Event).
      • [ ] 6.5. Customize edit-organizer.php override:
        • [ ] Add Astra theme wrapper (#primary, #main).
        • [ ] Add Astra breadcrumbs.
        • [ ] Add action buttons (Return to Dashboard).
      • [ ] 6.6. (Optional) Investigate/implement hooks/filters to customize confirmation messages if needed.
      • Reason: Encountered persistent duplication and layout issues with overrides. Switching to shortcode-based approach. See docs/tec-ce-shortcode-integration-plan.md.

    • 7. Integrate TEC Community Events via Shortcodes [2025-04-02]

      • 7.1. Update plugin activation to create manage-event and my-events pages with shortcodes.
      • 7.2. Update dashboard template links to point to new pages (/manage-event/, /my-events/).
      • 7.3. Cleanup unused template overrides and old shortcode logic (class-event-handler.php).
      • 7.4. Run tests (Integration PASS, E2E PASS except shortcode rendering). [2025-04-02]
        • Note: E2E tests verifying the rendering of TEC CE shortcodes (community-events.spec.ts) were skipped due to environment-specific issues.

• Phase 2: Enhanced Features

  • 1. Implement Zoho CRM API Integration

    • 1.1. Research Zoho CRM API and identify relevant endpoints.
    • 1.2. Create a Zoho CRM API client class in PHP.
    • 1.3. Implement authentication with Zoho CRM API.
    • 1.4. Implement function to create records for each training event in the "Campaigns" table.
    • 1.5. Implement function to update each Campaign record with ticket sales, attendance & certificate activities.
    • 1.6. Create settings page to configure Zoho CRM API credentials using theme's styling.
    • 1.7. Add unit tests for Zoho CRM API client class.
    • 1.8. Add integration tests to verify data is synced to Zoho CRM.

  • 2. Implement Email Attendees Functionality

    • 2.1. Create an "Email Attendees" page using theme templates.
    • 2.2. Add filtering options for event selector, ticket type, and attendee filter using theme form elements.
    • 2.3. Implement a rich-text editor for email body compatible with the theme.
    • 2.4. Add CC field and subject line using theme form styling.
    • 2.5. Implement function to send emails to selected attendees.
    • 2.6. Add unit tests for email sending functionality.
    • 2.7. Add integration tests to verify emails are sent correctly.

  • 3. Implement Enhanced Event Management

    • 3.1. Review existing event management features and identify areas for enhancement.
    • 3.2. Implement new features based on trainer feedback and requirements using theme components.
    • 3.3. Ensure consistency with design references while using theme elements.
    • 3.4. Add unit tests for new event management features.
    • 3.5. Add integration tests to verify new features work correctly with The Events Calendar.

  • 4. Implement Comprehensive Transaction Reporting

    • 4.1. Create an "Order Summary" page with basic details using theme templates.
    • 4.2. Display order number, purchaser name and email, date of purchase, number of tickets, and total price using theme typography.
    • 4.3. Display attendee information for each ticket purchased in theme-styled tables.
    • 4.4. Add filtering and sorting capabilities to the transaction table using theme components.
    • 4.5. Add unit tests for transaction reporting functionality.
    • 4.6. Add integration tests to verify transaction data is displayed correctly.

WordPress Theme Integration Implementation

• Template Structure

  • Create template parts following Astra's template organization pattern
  • Implement content-*.php templates for different view types
  • Use get_template_part() to maintain theme compatibility

• Styling Approach

  • Enqueue stylesheets properly with theme dependencies
  • Use minimal custom CSS, only for specialized components
  • Implement responsive design using theme's media queries
  • Utilize theme colors via CSS variables or the WordPress color palette

• JavaScript Integration

  • Enqueue scripts properly with theme dependencies
  • Utilize jQuery or vanilla JS depending on theme's approach
  • Implement AJAX functionality for dynamic content loading
  • Ensure JS interactions follow theme's interaction patterns

Testing and Deployment

• Development Environment: All development and testing should be performed within the Docker-based development environment as described in the wordpress-dev directory.
• Production Data: The production website should only be accessed to download all of the production server data as a reference and to import into the dev server so that the dev server environment mirrors the production server.
• Testing:
  • Unit Tests: Use PHPUnit to test individual classes and functions.
  • Integration Tests: Use WordPress testing framework to test integration with WordPress and The Events Calendar.
  • E2E Tests: Use Playwright to test user journeys and UI interactions.
  • Theme Compatibility Testing: Test across different screen sizes and browsers to ensure theme responsiveness.
• Deployment: Follow the configuration-based deployment process outlined in docs/deployment.md.

Status

• Not Started
• In Progress
• Complete