ben/upskill-event-manager
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
upskill-event-manager/docs/README.md
bengizmo c349428451 feat: Implement comprehensive enhanced CSV import system with taxonomy integration 
COMPREHENSIVE CSV IMPORT SYSTEM REDESIGN

Problem Resolved:
- Trainer profiles missing critical information from CSV_Trainers_Import_1Aug2025.csv
- Existing import system used hardcoded data instead of reading actual CSV file
- Missing 19 fields of professional information including phone numbers, websites, certifications

Solution Implemented:
- Complete enhanced CSV import system reading actual CSV file with 43 trainer records
- Full taxonomy integration for business_type and training_audience classifications
- Comprehensive field mapping for all 19 available CSV fields
- Multi-value taxonomy handling for comma-separated fields
- Automatic venue/organizer creation based on CSV flags

Key Components Added:
- includes/enhanced-csv-import-from-file.php: Main CSV import class with comprehensive processing
- Updated includes/class-hvac-geocoding-ajax.php: Enhanced AJAX integration
- includes/taxonomy-migration.php: Safe data migration utilities
- Comprehensive error handling, progress tracking, and logging

Fields Now Imported:
- Contact: Name, Email, Phone, Website
- Professional: Company, Role, Certification details (date, type, status)
- Location: Country, State, City
- Taxonomies: Business Type, Training Audience with multi-value support
- System: Application Details, User ID, Venue/Organizer creation flags

Testing Results:
- 43 CSV rows processed successfully
- 43 trainer profiles updated with enhanced data
- Proper taxonomy assignments with comma-separated value handling
- Automatic venue/organizer creation
- Zero errors during import process
- Complete data integrity preserved

TAXONOMY SYSTEM ENHANCEMENTS

Trainer Profile Taxonomy Implementation:
- WordPress taxonomies for business_type and training_audience
- Dynamic form loading from taxonomy terms with fallback support
- Multi-value checkbox and radio interfaces
- Safe data migration from text fields to taxonomies

Template Updates:
- templates/template-edit-profile.php: Dynamic taxonomy loading
- templates/page-master-trainer-profile-edit.php: Enhanced taxonomy management
- templates/page-master-dashboard.php: Fixed critical PHP fatal error

Critical Bug Fixes:
- Fixed HVAC_Community_Events::get_instance() undefined method error
- Master dashboard template now uses correct instance() method
- Eliminated PHP fatal errors preventing master trainer access

COMPREHENSIVE TESTING & VALIDATION

E2E Testing with Playwright:
- 87.5% test pass rate (7/8 tests passing)
- Registration form taxonomy integration verified
- Profile editing with taxonomy selections confirmed
- Data persistence across sessions validated
- Comprehensive visual evidence captured

Documentation Updates:
- docs/API-REFERENCE.md: Complete CSV import AJAX endpoint documentation
- docs/DEVELOPMENT-GUIDE.md: CSV import architecture and best practices
- docs/README.md: Enhanced system overview with CSV import features
- CLAUDE.md: Comprehensive memory entry for future reference

Production Impact:
- Complete trainer profiles with professional information
- Enhanced business categorization through taxonomy system
- Automatic event management preparation with venues/organizers
- Improved master trainer dashboard functionality
- Zero data loss with comprehensive error handling

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-04 05:57:08 -03:00

5.5 KiB
Raw Blame History

HVAC Community Events Plugin Documentation

Overview

The HVAC Community Events plugin is a comprehensive event management system designed specifically for HVAC trainers. It integrates seamlessly with WordPress and The Events Calendar to provide trainer profiles, certificate generation, venue management, certification tracking, advanced reporting capabilities, and comprehensive CSV import functionality with taxonomy integration.

Documentation Structure

📋 Configuration Guide

Complete reference for plugin configuration including:

  • System architecture overview
  • Configuration files and constants
  • User roles and permissions
  • URL structure and routing
  • Theme integration (Astra)
  • Database structure

💻 Development Guide

Best practices and guidelines for developers:

  • Development environment setup
  • Coding standards (WordPress, PHP, JS, CSS)
  • Architecture principles and patterns
  • Git workflow and deployment process
  • Testing strategies
  • Security best practices
  • Performance optimization

🔧 Troubleshooting Guide

Solutions to common issues:

  • 404 errors and missing pages
  • Navigation and menu problems
  • CSS and theme conflicts
  • Database issues
  • Performance problems
  • Recovery procedures
  • Debugging techniques

🏗️ Architecture Documentation

Technical architecture details:

  • Plugin structure
  • Class responsibilities
  • Hook system
  • Data flow
  • Integration points

Quick Start

Installation

  1. Upload plugin to /wp-content/plugins/
  2. Activate through WordPress admin
  3. Plugin automatically creates required pages
  4. Configure settings as needed

Key Features

  • Trainer Profiles: Comprehensive trainer management with photos, certifications, and statistics
  • Event Management: Full integration with The Events Calendar
  • Certificate Generation: Automated PDF certificate creation with custom templates
  • Venue Management: Organize training locations with TEC integration
  • Master Dashboard: Aggregate reporting for master trainers
  • Hierarchical URLs: SEO-friendly URL structure (/trainer/dashboard/)

User Roles

  1. hvac_trainer: Standard trainer role

    • Manage own events
    • Generate certificates
    • Manage profile, venues, organizers

  2. hvac_master_trainer: Advanced trainer role

    • All trainer capabilities
    • View aggregate reports
    • Access master dashboard
    • Manage other trainers

Important Notes

  • Dual-role users (both trainer and master trainer) will only see the master trainer navigation
  • Plugin requires The Events Calendar to be installed and active
  • Optimized for Astra theme but compatible with most WordPress themes
  • PHP 7.4+ required (PHP 8.0+ recommended)

Support

For issues or questions:

  1. Check the Troubleshooting Guide
  2. Review error logs in /wp-content/debug.log
  3. Contact development team with detailed error information

Recent Fixes & Updates

Enhanced CSV Import System (August 4, 2025) ✅

Comprehensive CSV import system with taxonomy integration

  • Problem: Trainer profiles missing critical information from CSV file - phone numbers, company websites, certification details, business classifications
  • Root Cause: Import system using hardcoded data instead of reading actual CSV file with 19 available fields
  • Solution: Complete CSV import system redesign with comprehensive field mapping
  • Key Features:
    • Reads actual CSV_Trainers_Import_1Aug2025.csv file (43 trainer records)
    • Imports all 19 fields: contact info, professional details, certification data
    • Full taxonomy integration for business types and training audiences
    • Automatic venue/organizer creation based on CSV flags
    • Multi-value taxonomy handling (comma-separated values)
    • Comprehensive error handling and progress tracking
  • Result: Complete trainer profiles with professional information, proper categorization, and enhanced event management capabilities

Certificate Pages Template System (August 1, 2025) ✅

Fixed critical template loading issue affecting certificate pages

  • Problem: Certificate pages (/trainer/certificate-reports/, /trainer/generate-certificates/) were bypassing WordPress template system, showing bare shortcode content without theme headers, navigation, or styling
  • Root Cause: load_custom_templates() method loading content-only templates instead of proper page templates
  • Solution: Updated template paths to use full page templates with proper WordPress integration
  • Additional Fixes:
    • Eliminated duplicate breadcrumbs by disabling Astra theme breadcrumbs on plugin pages
    • Restored missing navigation menu by removing problematic constant checks
  • Result: Certificate pages now display with complete theme integration, proper headers/footers, navigation, and consistent styling

Previous Major Updates

  • Taxonomy Implementation (August 4, 2025) - WordPress taxonomies for trainer profile classification with E2E testing
  • Navigation and Layout System (August 1, 2025) - Dual-role user navigation, sidebar removal, profile page templates
  • Role and Certification System (August 1, 2025) - Comprehensive user roles and certification tracking with 10 role options
  • Major Plugin Refactor (July 30, 2025) - Registration system overhaul, new trainer pages, comprehensive navigation system

Version History

  • v2.0.0 (Current) - Major refactor with modular architecture
  • v1.0.0 - Initial release

Last updated: August 2025