upskill-event-manager/docs/CONFIGURATION.md

HVAC Plugin Configuration Guide

Table of Contents

• Overview
• System Architecture
• Configuration Files
• User Roles & Permissions
• URL Structure
• Theme Integration
• Page Templates
• Navigation System
• CSS & JavaScript Assets
• Database Structure

Overview

The HVAC Community Events plugin is a comprehensive event management system for HVAC trainers. It integrates with The Events Calendar (TEC) and provides custom functionality for trainer profiles, certificate generation, and event management.

System Architecture

Core Components

hvac-community-events/
├── includes/               # Core PHP classes
├── templates/             # Page templates
├── assets/                # CSS, JS, images
├── bin/                   # CLI scripts
├── scripts/               # Deployment scripts
├── tests/                 # Test suites
└── docs/                  # Documentation

Key Classes

1. HVAC_Plugin - Main plugin class, handles initialization
2. HVAC_Menu_System - Navigation menu management
3. HVAC_Astra_Integration - Theme compatibility layer
4. HVAC_Scripts_Styles - Asset management
5. HVAC_Shortcodes - Shortcode implementations
6. HVAC_Route_Manager - URL routing and rewrites

Configuration Files

.env Configuration

# Staging Environment
UPSKILL_STAGING_IP=146.190.76.204
UPSKILL_STAGING_SSH_USER=roodev
UPSKILL_STAGING_PATH=/home/974670.cloudwaysapps.com/uberrxmprk/public_html
UPSKILL_STAGING_URL=https://upskill-staging.measurequick.com

# Production Environment (only when explicitly needed)
UPSKILL_PRODUCTION_IP=<production-ip>
UPSKILL_PRODUCTION_SSH_USER=<production-user>
UPSKILL_PRODUCTION_PATH=<production-path>
UPSKILL_PRODUCTION_URL=https://upskillhvac.com

Plugin Constants (hvac-community-events.php)

define('HVAC_PLUGIN_VERSION', '2.0.0');
define('HVAC_PLUGIN_PATH', plugin_dir_path(__FILE__));
define('HVAC_PLUGIN_URL', plugin_dir_url(__FILE__));
define('HVAC_PLUGIN_FILE', __FILE__);

User Roles & Permissions

Role Hierarchy

1. hvac_master_trainer - Full access to all features, aggregate reporting
2. hvac_trainer - Standard trainer access, manage own events
3. event_trainer - Legacy role (should be migrated to hvac_trainer)

Capabilities

// Master Trainer
- manage_all_events
- view_all_certificates
- access_master_dashboard
- manage_trainers

// Regular Trainer
- manage_own_events
- generate_certificates
- manage_profile
- manage_venues
- manage_organizers

Important: Dual-Role Users

Users with both trainer and master trainer roles will ONLY see the master trainer navigation to prevent UI duplication.

URL Structure

Hierarchical URLs (implemented June 2025)

/trainer/
├── /dashboard/
├── /event/manage/
├── /certificate-reports/
├── /generate-certificates/
├── /profile/
├── /profile/edit/
├── /venue/list/
├── /venue/manage/
├── /organizer/list/
└── /organizer/manage/

/master-trainer/
├── /master-dashboard/
├── /events/
└── /reports/

Legacy URL Redirects

All old URLs automatically redirect to new hierarchical structure:

• /trainer-dashboard/ → /trainer/dashboard/
• /trainer-profile/ → /trainer/profile/

Theme Integration

Astra Theme Compatibility

The plugin includes HVAC_Astra_Integration class that:

• Forces full-width layouts on all plugin pages
• Removes sidebars completely
• Adds custom body classes
• Overrides theme container widths

Body Classes Added

.hvac-plugin-page
.hvac-trainer-area
.hvac-astra-integrated
.ast-no-sidebar
.ast-full-width-layout

Critical CSS Overrides

/* Force full-width on HVAC pages */
.hvac-astra-integrated .ast-container {
    max-width: 100% !important;
    width: 100% !important;
}

/* Remove all sidebars */
.hvac-astra-integrated .widget-area,
.hvac-astra-integrated #secondary {
    display: none !important;
}

Page Templates

Template Files

All templates must include WordPress header/footer:

<?php
// Template Name: Trainer Dashboard
define('HVAC_IN_PAGE_TEMPLATE', true);
get_header();
?>
<!-- Content -->
<?php
get_footer();
?>

Template Assignment

Templates are automatically assigned during plugin activation. Manual assignment:

update_post_meta($page_id, '_wp_page_template', 'templates/page-trainer-dashboard.php');

Available Templates

• page-trainer-dashboard.php
• page-trainer-profile.php
• page-certificate-reports.php
• page-generate-certificates.php
• page-manage-event.php
• page-master-dashboard.php

Navigation System

Menu Registration

// Rendered via HVAC_Menu_System::render_trainer_menu()
// Includes dropdown support and mobile hamburger menu

Menu Structure

[
    'Events' => [
        'Dashboard',
        'New Event'
    ],
    'Certificates' => [
        'Reports',
        'New Certificate'
    ],
    'Customize' => [
        'Personal Profile',
        'Training Organizers',
        'Training Venues'
    ]
]

Navigation Rules

1. Check user capabilities before rendering
2. Dual-role users see only master trainer menu
3. Use HVAC_NAV_RENDERED constant to prevent duplicates

CSS & JavaScript Assets

Asset Loading

Managed by HVAC_Scripts_Styles class:

// CSS files loaded conditionally on plugin pages
- hvac-dashboard.css
- hvac-menu-system.css
- hvac-layout.css
- hvac-profile.css

// JavaScript with proper dependencies
- hvac-dashboard.js (requires jQuery)
- hvac-menu-system.js
- hvac-profile.js

Loading Conditions

private function is_plugin_page() {
    // Checks URL patterns
    // Checks page templates
    // Checks HVAC_IN_PAGE_TEMPLATE constant
}

Database Structure

Custom Tables

None - plugin uses WordPress posts, user meta, and post meta

Post Meta Keys

// Event meta
'_EventStartDate'
'_EventEndDate'
'_EventVenueID'
'_EventOrganizerID'

// Page meta
'_wp_page_template'
'site-sidebar-layout'
'ast-site-sidebar-layout'

User Meta Keys

'hvac_trainer_photo'
'hvac_certifications'
'hvac_bio'
'hvac_website'
'hvac_location'
'hvac_training_formats'
'hvac_training_audience'

Environment-Specific Settings

Staging

• Debug logging enabled
• Cache clearing after deployment
• Test data seeding available

Production

• Debug logging disabled
• Performance optimizations active
• Double confirmation required for deployment

Integration Points

The Events Calendar (TEC)

• Events created as 'tribe_events' post type
• Venues managed through TEC
• Organizers synced with TEC

Zoho CRM

• OAuth integration for data sync
• Refresh token handling
• Production-only activation

Certificate Generation

• TCPDF library for PDF creation
• Custom certificate templates
• Batch processing support

Trainer Profile Sharing System

• QR code generation using QR Server API
• Shareable profile URLs with rewrite rules
• AJAX-powered sharing modals
• Professional profile cards with certification badges

Profile Sharing Configuration

QR Code Generation

The system uses QR Server API for generating QR codes:

// API Endpoint
https://api.qrserver.com/v1/create-qr-code/

// Parameters
- size: QR code dimensions (default: 200x200)
- data: URL to encode
- ecc: Error correction level (L, M, Q, H)

Share URL Structure

Profile sharing URLs follow this pattern:

https://example.com/find-a-trainer/profile/{profile_id}/

Important: URLs must include trailing slash for WordPress rewrite rules to work properly.

Rewrite Rules

Custom rewrite rules handle direct profile access:

add_rewrite_rule(
    '^find-a-trainer/profile/([0-9]+)/?$',
    'index.php?pagename=find-a-trainer&trainer_profile_id=$matches[1]',
    'top'
);

AJAX Endpoints

Profile sharing uses these AJAX actions:

• hvac_get_profile_share_data - Retrieves profile data and QR code URL
• Requires nonce verification: hvac_profile_sharing

CSS Classes for Styling

.hvac-share-modal               # Modal overlay
.hvac-share-profile-card        # Profile card container
.hvac-share-avatar              # Profile image container
.hvac-share-qr                  # QR code container
.hvac-mq-badge-overlay          # Certification badge overlay

JavaScript Localization

Profile sharing requires these localized variables:

hvac_sharing.ajax_url           # WordPress AJAX URL
hvac_sharing.nonce             # Security nonce
hvac_sharing.strings.copied    # "Copied!" message
hvac_sharing.strings.copy_error # Copy error message