upskill-event-manager/docs/HVAC-TEMPLATE-SYSTEM-API.md

HVAC Template System API Documentation

Version: 2.0 Date: September 25, 2025 Status: Production Ready

---

📋 Overview

The HVAC Template System API provides comprehensive template management functionality for the HVAC Event Form Builder, including template creation, retrieval, preview, and application capabilities.

🏗️ Architecture

Core Components

1. HVAC_Event_Form_Builder - Form builder with template integration
2. HVAC_Event_Template_Manager - Template CRUD operations
3. HVAC_Shortcodes - AJAX handlers for template operations
4. JavaScript Frontend - Template UI interactions

---

🔧 PHP API Reference

HVAC_Event_Form_Builder Methods

add_template_selector(array $categories = []): self

Adds an enhanced template selector dropdown to the form.

Parameters:

• $categories (array) - Optional array of template categories to filter

Returns: self for method chaining

Example:

$form_builder->add_template_selector(['training', 'workshop', 'certification']);

add_template_actions(): self

Adds template action buttons including "Save as Template".

Returns: self for method chaining

add_progressive_disclosure(): self

Adds the progressive disclosure toggle for advanced options.

Returns: self for method chaining

mark_field_as_advanced(string $field_name): self

Marks a specific field as advanced for progressive disclosure.

Parameters:

• $field_name (string) - Name of the field to mark as advanced

Returns: self for method chaining

Example:

$form_builder->mark_field_as_advanced('event_capacity')
             ->mark_field_as_advanced('event_cost');

load_template(string $template_id): bool

Loads template data into the form builder.

Parameters:

• $template_id (string) - Template ID to load

Returns: bool - Success status

HVAC_Shortcodes AJAX Handlers

ajax_get_template_preview()

Action: hvac_get_template_preview Method: POST Authentication: Required (trainer role)

Request Parameters:

• template_id (string) - Template ID to preview
• nonce (string) - WordPress nonce for security

Response:

{
  "success": true,
  "data": {
    "id": "template_123",
    "name": "Basic Training Template",
    "description": "Standard template for training events",
    "category": "training",
    "field_data": {
      "event_title": "Sample Training Event",
      "event_description": "...",
      "event_capacity": "50"
    },
    "created_by": 1,
    "created_at": "2025-09-25 12:00:00"
  }
}

ajax_load_template_data()

Action: hvac_load_template_data Method: POST Authentication: Required (trainer role)

Request Parameters:

• template_id (string) - Template ID to load
• nonce (string) - WordPress nonce for security

Response:

{
  "success": true,
  "data": {
    "event_title": "Sample Training Event",
    "event_description": "Comprehensive training session",
    "event_capacity": "50",
    "event_cost": "299.00"
  }
}

ajax_save_template()

Action: hvac_save_template Method: POST Authentication: Required (trainer role)

Request Parameters:

• template_name (string) - Template name
• template_description (string) - Template description
• template_category (string) - Template category
• is_public (bool) - Whether template is public
• field_data (object) - Form field data to save
• nonce (string) - WordPress nonce for security

Response:

{
  "success": true,
  "data": {
    "message": "Template saved successfully",
    "template_id": "template_456"
  }
}

---

🎨 JavaScript API Reference

Template Preview Functions

hvacShowTemplatePreview(templateId)

Shows the template preview modal for the specified template.

Parameters:

• templateId (string) - Template ID to preview

Example:

hvacShowTemplatePreview('template_123');

hvacCloseTemplatePreview()

Closes the template preview modal.

hvacApplyTemplate()

Applies the currently previewed template to the form.

Save Template Functions

hvacShowSaveTemplateDialog(event)

Shows the save template dialog.

Parameters:

• event (Event) - Click event to prevent default

hvacCloseSaveDialog()

Closes the save template dialog.

hvacSaveAsTemplate()

Saves the current form as a new template.

Progressive Disclosure Functions

hvacToggleAdvancedOptions()

Toggles the visibility of advanced form options with animations.

Auto-save Functions

performAutoSave()

Performs an auto-save of the current form state.

attemptDraftRecovery()

Attempts to recover draft data on page load.

updateAutoSaveStatus(status, message)

Updates the auto-save status indicator.

Parameters:

• status (string) - Status type: 'saving', 'saved', 'error', 'draft-loaded'
• message (string) - Optional custom message

---

🗄️ Data Structures

Template Object Structure

{
  id: "template_123",
  name: "Training Template",
  description: "Standard training event template",
  category: "training",
  is_public: true,
  field_data: {
    event_title: "Sample Title",
    event_description: "Sample Description",
    event_capacity: "50",
    event_cost: "299.00"
  },
  meta_data: {
    source: "event_form",
    created_at: "2025-09-25T12:00:00Z",
    user_ip: "192.168.1.1"
  },
  created_by: 1,
  created_at: "2025-09-25 12:00:00"
}

Auto-save Data Structure

{
  formData: {
    event_title: "Event Title",
    event_description: "Event Description",
    // ... other form fields
  },
  timestamp: "2025-09-25T12:00:00.000Z",
  url: "https://example.com/trainer/events/create/",
  version: "2.0"
}

---

🔒 Security Implementation

Authentication & Authorization

• Required Role: hvac_trainer or hvac_master_trainer
• Nonce Verification: All AJAX requests require valid WordPress nonce
• Permission Checks: Role validation on all template operations

Input Sanitization

// Template data sanitization
$template_name = sanitize_text_field($_POST['template_name']);
$template_description = sanitize_textarea_field($_POST['template_description']);
$template_category = sanitize_text_field($_POST['template_category']);

// Field data sanitization
foreach ($field_data as $key => $value) {
    $sanitized_key = sanitize_key($key);
    if (is_array($value)) {
        $sanitized_field_data[$sanitized_key] = array_map('sanitize_text_field', $value);
    } else {
        $sanitized_field_data[$sanitized_key] = sanitize_text_field($value);
    }
}

Error Handling

• Template Not Found: Returns appropriate error messages
• Permission Denied: Blocks unauthorized access attempts
• Validation Failures: Provides specific validation error messages
• Storage Limits: Handles localStorage quota exceeded gracefully

---

🎯 Usage Examples

Creating a Form with Template Support

// Initialize form builder with template support
$form_builder = new HVAC_Event_Form_Builder('hvac_event_form', true);

// Create form with all template features
$form_builder->create_event_form([
    'include_template_selector' => true,
    'include_venue_fields' => true,
    'include_organizer_fields' => true,
    'include_cost_fields' => true,
    'include_capacity_fields' => true,
    'include_datetime_fields' => true,
    'template_categories' => ['general', 'training', 'workshop', 'certification']
]);

// Render the form
echo $form_builder->render();

JavaScript Template Integration

jQuery(document).ready(function($) {
    // Initialize template selector functionality
    $(document).on('change', '[name="event_template"]', function() {
        const templateId = $(this).val();
        if (templateId && templateId !== '0') {
            hvacShowTemplatePreview(templateId);
        }
    });

    // Initialize auto-save
    createAutoSaveIndicator();
    setTimeout(attemptDraftRecovery, 500);

    // Initialize progressive disclosure
    if ($('.advanced-field').length > 0) {
        setupAdvancedFieldGroups();
    }
});

Custom Template Categories

// Define custom template categories
$custom_categories = [
    'certification' => 'Certification Events',
    'webinar' => 'Online Webinars',
    'conference' => 'Conference Sessions',
    'workshop' => 'Hands-on Workshops'
];

// Add template selector with custom categories
$form_builder->add_template_selector(array_keys($custom_categories));

---

📊 Performance Considerations

Auto-save Optimization

• Debounce Timing: 1-3 seconds based on field type
• Selective Storage: Only saves fields with meaningful content
• Quota Management: Falls back to essential fields if storage full
• Background Operation: Uses visibilitychange for tab switching

Template Loading

• Cached Results: Template lists cached for performance
• AJAX Optimization: Minimal data transfer for preview/apply operations
• Progressive Loading: Templates loaded on demand

Animation Performance

• CSS Transitions: Hardware-accelerated transforms
• Staggered Reveals: 50ms delays prevent janky animations
• Efficient Selectors: Optimized jQuery selectors

---

🧪 Testing Guidelines

Unit Testing

// Test template creation
$template_data = [
    'name' => 'Test Template',
    'category' => 'testing',
    'field_data' => ['event_title' => 'Test Event']
];

$result = $template_manager->create_template($template_data);
$this->assertTrue($result['success']);

Integration Testing

// Test template preview functionality
QUnit.test('Template Preview', function(assert) {
    const done = assert.async();

    hvacShowTemplatePreview('test_template_123');

    setTimeout(function() {
        assert.ok($('#hvac-template-preview').is(':visible'), 'Preview modal shown');
        done();
    }, 500);
});

Auto-save Testing

// Test auto-save functionality
QUnit.test('Auto-save Operation', function(assert) {
    $('#event-title').val('Test Event').trigger('input');

    setTimeout(function() {
        const draftData = localStorage.getItem('hvac_event_draft');
        assert.ok(draftData, 'Draft data saved');

        const parsed = JSON.parse(draftData);
        assert.equal(parsed.formData.event_title, 'Test Event', 'Title saved correctly');
    }, 3500);
});

---

🚀 Deployment Notes

Dependencies

• WordPress 5.0+
• jQuery 3.0+
• HVAC Event Template Manager
• TEC Core (for event creation)

File Structure

includes/
├── class-hvac-event-form-builder.php
├── class-hvac-shortcodes.php
└── class-hvac-event-template-manager.php

templates/
└── page-tec-create-event.php

assets/
├── css/ (inline styles in template)
└── js/  (inline scripts in template)

Configuration

// Enable template mode in form builder
$form_builder = new HVAC_Event_Form_Builder('form_id', true); // true enables templates

// Configure auto-save timing (optional)
define('HVAC_AUTOSAVE_DELAY_TEXT', 3000);    // 3 seconds for text fields
define('HVAC_AUTOSAVE_DELAY_SELECT', 1000);  // 1 second for dropdowns

---

📚 Related Documentation

• PHASE-2B-TEMPLATE-SYSTEM-FEATURES.md - Complete feature documentation
• PHASE-2-TEC-INTEGRATION-ANALYSIS.md - Integration analysis
• ARCHITECTURE.md - System architecture
• TROUBLESHOOTING.md - Common issues and solutions

---

🐛 Troubleshooting

Common Issues

Template Preview Not Loading

// Check AJAX URL and nonce
console.log('AJAX URL:', ajaxurl);
console.log('Nonce:', $('[name="hvac_event_form_nonce"]').val());

// Verify template ID is valid
console.log('Template ID:', templateId);

Auto-save Not Working

// Check localStorage availability
if (typeof(Storage) !== "undefined") {
    console.log('localStorage available');
} else {
    console.log('localStorage not supported');
}

// Check for quota exceeded errors
try {
    localStorage.setItem('test', 'data');
    console.log('Storage working');
} catch(e) {
    console.log('Storage error:', e);
}

Progressive Disclosure Issues

// Check advanced field detection
console.log('Advanced fields found:', $('.advanced-field').length);

// Verify localStorage state
console.log('Advanced options state:', localStorage.getItem('hvac_advanced_options_visible'));

---

API Documentation generated for HVAC Template System v2.0 🤖 Generated with Claude Code