upskill-event-manager/docs/TRAINER-API-REFERENCE.md

HVAC Trainer System API Reference

This document provides detailed API reference for developers working with the HVAC Trainer system, including PHP classes, JavaScript APIs, AJAX endpoints, and database schemas.

Table of Contents

1. PHP Classes
2. AJAX Endpoints
3. JavaScript APIs
4. Database Schema
5. Hooks & Filters
6. Constants & Configuration
7. Error Codes

PHP Classes

HVAC_Trainer_Profile_Manager

File: includes/class-hvac-trainer-profile-manager.php
Purpose: Core trainer profile management functionality

Class Methods

get_instance()

Returns singleton instance of the profile manager.

$manager = HVAC_Trainer_Profile_Manager::get_instance();

Returns: HVAC_Trainer_Profile_Manager - Singleton instance

create_profile($data)

Creates a new trainer profile.

$profile_data = [
    'trainer_first_name' => 'John',
    'trainer_last_name' => 'Smith',
    'trainer_city' => 'Chicago',
    'trainer_state' => 'Illinois',
    'user_id' => 123,
    'certification_type' => 'Certified measureQuick Trainer'
];

$profile_id = $manager->create_profile($profile_data);

Parameters:

• $data (array) - Profile data array

Returns: int|false - Profile post ID on success, false on failure

Data Fields:

• trainer_first_name (string) - First name
• trainer_last_name (string) - Last name
• trainer_display_name (string) - Display name
• trainer_city (string) - City
• trainer_state (string) - State/Province
• trainer_country (string) - Country
• profile_image_url (string) - Profile image URL
• certification_type (string) - Certification level
• user_id (int) - WordPress user ID
• is_public_profile (string) - Public visibility ('1' or '0')

update_profile($profile_id, $data)

Updates an existing trainer profile.

$updated_data = [
    'trainer_city' => 'New York',
    'trainer_state' => 'New York',
    'certification_type' => 'Certified measureQuick Champion'
];

$success = $manager->update_profile(5840, $updated_data);

Parameters:

• $profile_id (int) - Profile post ID
• $data (array) - Updated profile data

Returns: bool - Success status

get_profile($profile_id)

Retrieves a trainer profile.

$profile = $manager->get_profile(5840);

Parameters:

• $profile_id (int) - Profile post ID

Returns: array|false - Profile data array or false if not found

Return Structure:

[
    'profile_id' => 5840,
    'user_id' => 31,
    'name' => 'John Smith',
    'city' => 'Chicago',
    'state' => 'Illinois',
    'certification_type' => 'Certified measureQuick Trainer',
    'profile_image' => 'https://...',
    'business_type' => 'Independent Contractor',
    'event_count' => 5,
    'training_formats' => 'In-Person, Virtual',
    'training_locations' => 'On-site, Remote'
]

get_public_profiles($args = [])

Retrieves all public trainer profiles.

$profiles = $manager->get_public_profiles([
    'posts_per_page' => 20,
    'meta_query' => [
        [
            'key' => 'trainer_state',
            'value' => 'Illinois',
            'compare' => '='
        ]
    ]
]);

Parameters:

• $args (array) - WP_Query arguments

Returns: array - Array of profile data

delete_profile($profile_id)

Deletes a trainer profile.

$success = $manager->delete_profile(5840);

Parameters:

• $profile_id (int) - Profile post ID

Returns: bool - Success status

migrate_certification_colors()

Migrates existing profiles to add certification color fields.

$manager->migrate_certification_colors();

Returns: void

get_certification_color($certification_type)

Gets the color code for a certification type.

$color = $manager->get_certification_color('Certified measureQuick Trainer');
// Returns: '#5077bb'

Parameters:

• $certification_type (string) - Certification type

Returns: string - Hex color code

Color Mapping:

• 'Certified measureQuick Champion' → '#f19a42'
• 'Certified measureQuick Trainer' → '#5077bb'
• Default → '#f0f7e8'

HVAC_Find_Trainer_Page

File: includes/find-trainer/class-hvac-find-trainer-page.php
Purpose: Find A Trainer page functionality

Class Methods

get_instance()

Returns singleton instance.

$page = HVAC_Find_Trainer_Page::get_instance();

render_page()

Renders the complete Find A Trainer page.

$page->render_page();

Returns: void - Outputs HTML directly

get_filter_options()

Gets available filter options for the directory.

$options = $page->get_filter_options();

Returns: array - Filter options structure

Return Structure:

[
    'states' => ['Illinois', 'New York', 'California'],
    'business_types' => ['Contractor', 'Distributor', 'Consultant'],
    'training_formats' => ['In-person', 'Virtual', 'Hybrid'],
    'training_resources' => ['Classroom', 'Training Lab', 'Online']
]

build_query_args($filters, $page = 1, $per_page = 12)

Builds WP_Query arguments from filter criteria.

$filters = [
    'state' => 'Illinois',
    'business_type' => ['Contractor', 'Consultant'],
    'search' => 'John'
];

$args = $page->build_query_args($filters, 1, 20);

Parameters:

• $filters (array) - Filter criteria
• $page (int) - Page number
• $per_page (int) - Results per page

Returns: array - WP_Query arguments

render_trainer_cards($trainers)

Renders HTML for trainer cards.

$trainers = $page->get_filtered_trainers($filters);
$page->render_trainer_cards($trainers);

Parameters:

• $trainers (array) - Array of trainer data

Returns: void - Outputs HTML directly

HVAC_MapGeo_Integration

File: includes/find-trainer/class-hvac-mapgeo-integration.php
Purpose: MapGeo plugin integration for interactive maps

Class Methods

get_instance()

Returns singleton instance.

$integration = HVAC_MapGeo_Integration::get_instance();

modify_map_layout($meta, $map_id = null)

Modifies MapGeo map layout to add trainer profile data.

add_filter('igm_add_meta', [$integration, 'modify_map_layout'], 10, 2);

Parameters:

• $meta (array) - MapGeo metadata
• $map_id (string) - Map ID

Returns: array - Modified metadata

ajax_get_trainer_profile()

AJAX handler for retrieving complete trainer profile data.

add_action('wp_ajax_hvac_get_trainer_profile', [$integration, 'ajax_get_trainer_profile']);
add_action('wp_ajax_nopriv_hvac_get_trainer_profile', [$integration, 'ajax_get_trainer_profile']);

Expected POST Data:

• profile_id (int) - Trainer profile ID
• nonce (string) - Security nonce

Response Format:

{
    "success": true,
    "data": {
        "profile_id": 5840,
        "user_id": "31",
        "name": "John Smith",
        "city": "Chicago",
        "state": "Illinois",
        "certification_type": "Certified measureQuick Trainer",
        "profile_image": "https://...",
        "business_type": "Independent Contractor",
        "event_count": 5,
        "training_formats": "In-Person, Virtual",
        "training_locations": "On-site, Remote",
        "upcoming_events": []
    }
}

ajax_get_trainer_certification()

AJAX handler for getting trainer certification information.

add_action('wp_ajax_hvac_get_trainer_certification', [$integration, 'ajax_get_trainer_certification']);

Expected POST Data:

• profile_id (int) - Trainer profile ID
• nonce (string) - Security nonce

Response Format:

{
    "success": true,
    "data": {
        "certification_type": "Certified measureQuick Trainer",
        "certification_color": "#5077bb"
    }
}

AJAX Endpoints

Trainer Profile Management

hvac_save_trainer_profile

Saves trainer profile changes.

URL: wp-admin/admin-ajax.php
Method: POST
Auth: Required (logged in user)

Parameters:

[
    'action' => 'hvac_save_trainer_profile',
    'profile_id' => 5840,
    'nonce' => 'security_nonce',
    'trainer_first_name' => 'John',
    'trainer_last_name' => 'Smith',
    'trainer_city' => 'Chicago',
    // ... other profile fields
]

Response:

{
    "success": true,
    "data": {
        "message": "Profile saved successfully",
        "profile_id": 5840
    }
}

hvac_auto_save_profile

Auto-saves profile during editing.

Parameters: Same as hvac_save_trainer_profile

Response: Same format with auto-save confirmation

Find A Trainer Directory

hvac_filter_trainers

Filters trainers by multiple criteria.

URL: wp-admin/admin-ajax.php
Method: POST
Auth: Not required (public)

Parameters:

[
    'action' => 'hvac_filter_trainers',
    'nonce' => 'security_nonce',
    'filters' => [
        'state' => ['Illinois', 'New York'],
        'business_type' => ['Contractor'],
        'training_format' => ['In-person', 'Virtual']
    ],
    'page' => 1,
    'per_page' => 12
]

Response:

{
    "success": true,
    "data": {
        "html": "<div class='hvac-trainer-card'>...</div>",
        "pagination": "<div class='hvac-pagination'>...</div>",
        "count": 25,
        "page": 1,
        "max_pages": 3
    }
}

hvac_search_trainers

Searches trainers by text query.

Parameters:

[
    'action' => 'hvac_search_trainers',
    'nonce' => 'security_nonce',
    'search' => 'John Smith',
    'page' => 1,
    'per_page' => 12
]

Response: Same format as filter trainers

hvac_get_filter_options

Gets available filter options.

Parameters:

[
    'action' => 'hvac_get_filter_options',
    'nonce' => 'security_nonce'
]

Response:

{
    "success": true,
    "data": {
        "states": ["Illinois", "New York", "California"],
        "business_types": ["Contractor", "Distributor", "Consultant"],
        "training_formats": ["In-person", "Virtual", "Hybrid"],
        "training_resources": ["Classroom", "Training Lab", "Online"]
    }
}

Contact Forms

hvac_submit_contact_form

Submits contact form to trainer.

Parameters:

[
    'action' => 'hvac_submit_contact_form',
    'nonce' => 'security_nonce',
    'trainer_id' => 5840,
    'contact_name' => 'Jane Doe',
    'contact_email' => 'jane@example.com',
    'contact_phone' => '555-1234',
    'message' => 'I would like to inquire about training...'
]

Response:

{
    "success": true,
    "data": {
        "message": "Your message has been sent successfully"
    }
}

JavaScript APIs

HVAC_FindTrainer Object

File: assets/js/find-trainer.js
Purpose: Client-side Find A Trainer functionality

Configuration

var HVAC_FindTrainer = {
    config: {
        ajax_url: hvac_find_trainer.ajax_url,
        nonce: hvac_find_trainer.nonce,
        filters: {},
        current_page: 1,
        per_page: 12
    }
};

Methods

init(options)

Initializes the Find A Trainer system.

HVAC_FindTrainer.init({
    ajax_url: '/wp-admin/admin-ajax.php',
    nonce: 'security_nonce',
    filters: {
        state: [],
        business_type: [],
        training_format: []
    }
});

Parameters:

• options (object) - Configuration options

performSearch(query)

Performs text search for trainers.

HVAC_FindTrainer.performSearch('John Smith');

Parameters:

• query (string) - Search query

applyFilters()

Applies current filter settings.

HVAC_FindTrainer.config.filters.state = ['Illinois'];
HVAC_FindTrainer.applyFilters();

updateResults(response)

Updates the display with new results.

HVAC_FindTrainer.updateResults({
    success: true,
    data: {
        html: '<div>...</div>',
        pagination: '<div>...</div>',
        count: 25
    }
});

Parameters:

• response (object) - AJAX response object

showTrainerProfile(profileId)

Shows trainer profile modal.

HVAC_FindTrainer.showTrainerProfile(5840);

Parameters:

• profileId (int) - Trainer profile ID

MapGeo Integration JavaScript

File: Embedded in class-hvac-mapgeo-integration.php
Purpose: MapGeo map interaction handling

Global Functions

window.hvac_show_trainer_modal(markerData)

Custom MapGeo action handler for trainer markers.

window.hvac_show_trainer_modal({
    hvac_profile_id: 5840,
    id: 'trainer_5840',
    title: 'John Smith'
});

Parameters:

• markerData (object) - Marker data from MapGeo

Global Variables

window.hvacTrainerDataCache

Cache object for trainer profile data.

// Cache structure
window.hvacTrainerDataCache = {
    '5840': {
        profile_id: 5840,
        name: 'John Smith',
        certification_type: 'Certified measureQuick Trainer'
        // ... other profile data
    }
};

window.hvacPendingRequests

Tracking object for pending AJAX requests.

// Pending requests structure
window.hvacPendingRequests = {
    '5840': true  // Profile ID 5840 has pending request
};

window.lastMapGeoTrainerData

Stores the most recent trainer data logged by MapGeo.

window.lastMapGeoTrainerData = {
    id: 'trainer_5840',
    title: 'John Smith',
    latitude: 41.8781,
    longitude: -87.6298
};

Database Schema

Custom Post Type: trainer_profile

wp_posts Table Fields

-- Core post fields for trainer_profile
CREATE TABLE wp_posts (
    ID bigint(20) unsigned NOT NULL AUTO_INCREMENT,
    post_title tinytext NOT NULL,           -- Trainer display name
    post_content longtext NOT NULL,         -- Profile description
    post_status varchar(20) NOT NULL,       -- 'publish', 'draft', 'pending'
    post_type varchar(20) NOT NULL,         -- 'trainer_profile'
    post_date datetime NOT NULL,
    post_modified datetime NOT NULL,
    PRIMARY KEY (ID),
    KEY type_status_date (post_type, post_status, post_date, ID)
);

wp_postmeta Table Fields

-- Profile metadata structure
INSERT INTO wp_postmeta (post_id, meta_key, meta_value) VALUES
-- Personal Information
(5840, 'trainer_first_name', 'John'),
(5840, 'trainer_last_name', 'Smith'),
(5840, 'trainer_display_name', 'John Smith'),
(5840, 'trainer_city', 'Chicago'),
(5840, 'trainer_state', 'Illinois'),
(5840, 'trainer_country', 'USA'),
(5840, 'profile_image_url', 'https://...'),
(5840, 'linkedin_profile_url', 'https://linkedin.com/...'),

-- Certification Information
(5840, 'certification_type', 'Certified measureQuick Trainer'),
(5840, 'certification_status', 'Active'),
(5840, 'certification_color', '#5077bb'),
(5840, 'date_certified', '2024-01-15'),
(5840, 'personal_accreditation', 'Additional certifications'),

-- System Fields
(5840, 'user_id', '31'),
(5840, 'is_public_profile', '1'),
(5840, '_last_geocode_attempt', '1691234567'),
(5840, 'geocoded_lat', '41.8781136'),
(5840, 'geocoded_lng', '-87.6297982'),

-- Business Information
(5840, 'annual_revenue_target', '100000'),
(5840, 'application_details', 'Registration details...');

Taxonomy Tables

Business Type Taxonomy

-- wp_terms entries for business_type taxonomy
INSERT INTO wp_terms (term_id, name, slug) VALUES
(1, 'Manufacturer', 'manufacturer'),
(2, 'Distributor', 'distributor'),
(3, 'Contractor', 'contractor'),
(4, 'Consultant', 'consultant'),
(5, 'Educator', 'educator'),
(6, 'Government', 'government'),
(7, 'Other', 'other');

-- wp_term_taxonomy entries
INSERT INTO wp_term_taxonomy (term_taxonomy_id, term_id, taxonomy, parent, count) VALUES
(1, 1, 'business_type', 0, 5),
(2, 2, 'business_type', 0, 8),
(3, 3, 'business_type', 0, 12);

-- wp_term_relationships entries (linking posts to terms)
INSERT INTO wp_term_relationships (object_id, term_taxonomy_id, term_order) VALUES
(5840, 3, 0);  -- Profile 5840 is linked to Contractor business type

Database Indexes

Recommended Indexes for Performance

-- Optimize meta queries
CREATE INDEX idx_postmeta_profile_queries 
ON wp_postmeta (meta_key, meta_value(50), post_id);

-- Optimize trainer profile queries
CREATE INDEX idx_posts_trainer_profile 
ON wp_posts (post_type, post_status, post_date);

-- Optimize geocoded trainer queries
CREATE INDEX idx_geocoded_trainers 
ON wp_postmeta (meta_key, post_id) 
WHERE meta_key IN ('geocoded_lat', 'geocoded_lng', 'is_public_profile');

Common Database Queries

Get All Public Trainers

SELECT p.ID, p.post_title,
       lat.meta_value as latitude,
       lng.meta_value as longitude,
       cert.meta_value as certification_type
FROM wp_posts p
LEFT JOIN wp_postmeta pub ON p.ID = pub.post_id AND pub.meta_key = 'is_public_profile'
LEFT JOIN wp_postmeta lat ON p.ID = lat.post_id AND lat.meta_key = 'geocoded_lat'  
LEFT JOIN wp_postmeta lng ON p.ID = lng.post_id AND lng.meta_key = 'geocoded_lng'
LEFT JOIN wp_postmeta cert ON p.ID = cert.post_id AND cert.meta_key = 'certification_type'
WHERE p.post_type = 'trainer_profile'
AND p.post_status = 'publish'
AND pub.meta_value = '1'
AND lat.meta_value IS NOT NULL
AND lng.meta_value IS NOT NULL;

Get Trainers by State

SELECT p.ID, p.post_title, state.meta_value as state
FROM wp_posts p
INNER JOIN wp_postmeta state ON p.ID = state.post_id AND state.meta_key = 'trainer_state'
INNER JOIN wp_postmeta pub ON p.ID = pub.post_id AND pub.meta_key = 'is_public_profile'
WHERE p.post_type = 'trainer_profile'
AND p.post_status = 'publish'
AND pub.meta_value = '1'
AND state.meta_value = 'Illinois'
ORDER BY p.post_title;

Hooks & Filters

Action Hooks

hvac_trainer_profile_created

Fired when a new trainer profile is created.

add_action('hvac_trainer_profile_created', function($profile_id, $profile_data) {
    // Custom logic after profile creation
    error_log("New trainer profile created: " . $profile_id);
}, 10, 2);

Parameters:

• $profile_id (int) - Created profile ID
• $profile_data (array) - Profile data used for creation

hvac_trainer_profile_updated

Fired when a trainer profile is updated.

add_action('hvac_trainer_profile_updated', function($profile_id, $old_data, $new_data) {
    // Custom logic after profile update
    if ($old_data['trainer_city'] !== $new_data['trainer_city']) {
        // Location changed - trigger geocoding
        do_action('hvac_trigger_geocoding', $profile_id);
    }
}, 10, 3);

Parameters:

• $profile_id (int) - Updated profile ID
• $old_data (array) - Previous profile data
• $new_data (array) - New profile data

hvac_trainer_profile_geocoded

Fired when a trainer profile is successfully geocoded.

add_action('hvac_trainer_profile_geocoded', function($profile_id, $lat, $lng) {
    // Custom logic after geocoding
    error_log("Profile {$profile_id} geocoded to: {$lat}, {$lng}");
}, 10, 3);

Parameters:

• $profile_id (int) - Profile ID
• $lat (float) - Latitude
• $lng (float) - Longitude

Filter Hooks

hvac_trainer_profile_data

Filters profile data before saving.

add_filter('hvac_trainer_profile_data', function($data, $profile_id) {
    // Modify profile data before saving
    if (empty($data['trainer_display_name'])) {
        $data['trainer_display_name'] = $data['trainer_first_name'] . ' ' . $data['trainer_last_name'];
    }
    return $data;
}, 10, 2);

Parameters:

• $data (array) - Profile data
• $profile_id (int) - Profile ID (0 for new profiles)

Returns: array - Modified profile data

hvac_trainer_query_args

Filters WP_Query arguments for trainer queries.

add_filter('hvac_trainer_query_args', function($args, $context) {
    // Modify query arguments
    if ($context === 'find_trainer_page') {
        $args['posts_per_page'] = 20; // Show more results
    }
    return $args;
}, 10, 2);

Parameters:

• $args (array) - WP_Query arguments
• $context (string) - Query context ('find_trainer_page', 'admin_list', etc.)

Returns: array - Modified query arguments

hvac_trainer_card_data

Filters trainer card display data.

add_filter('hvac_trainer_card_data', function($card_data, $profile_id) {
    // Add custom fields to card display
    $card_data['custom_field'] = get_post_meta($profile_id, 'custom_field', true);
    return $card_data;
}, 10, 2);

Parameters:

• $card_data (array) - Card display data
• $profile_id (int) - Profile ID

Returns: array - Modified card data

hvac_mapgeo_marker_data

Filters MapGeo marker data for trainers.

add_filter('hvac_mapgeo_marker_data', function($marker_data, $profile_id) {
    // Customize marker appearance
    $cert_type = get_post_meta($profile_id, 'certification_type', true);
    if ($cert_type === 'Certified measureQuick Champion') {
        $marker_data['icon'] = 'champion_icon';
        $marker_data['fill'] = '#f19a42';
    }
    return $marker_data;
}, 10, 2);

Parameters:

• $marker_data (array) - Marker data
• $profile_id (int) - Profile ID

Returns: array - Modified marker data

Constants & Configuration

Plugin Constants

// Plugin version
define('HVAC_PLUGIN_VERSION', '1.0.0');

// Plugin paths
define('HVAC_PLUGIN_PATH', plugin_dir_path(__FILE__));
define('HVAC_PLUGIN_URL', plugin_dir_url(__FILE__));

// MapGeo configuration
define('HVAC_MAPGEO_MAP_ID', '5872');

// Performance settings
define('HVAC_TRAINER_CACHE_TIMEOUT', HOUR_IN_SECONDS);
define('HVAC_TRAINER_GEOCODING_TIMEOUT', 30); // seconds

// Debug mode
define('HVAC_DEBUG', false);

Configuration Options

WordPress Options

// Google Maps API key for geocoding
update_option('hvac_google_maps_api_key', 'your_api_key_here');

// Default trainer profile settings
update_option('hvac_trainer_default_settings', [
    'auto_geocode' => true,
    'public_by_default' => false,
    'require_approval' => true
]);

// Find A Trainer page settings
update_option('hvac_find_trainer_settings', [
    'results_per_page' => 12,
    'enable_map' => true,
    'enable_contact_forms' => true,
    'cache_timeout' => 3600
]);

Error Codes

AJAX Error Codes

Code	Constant	Description
1001	HVAC_ERROR_INVALID_NONCE	Nonce verification failed
1002	HVAC_ERROR_INSUFFICIENT_PERMISSIONS	User lacks required permissions
1003	HVAC_ERROR_PROFILE_NOT_FOUND	Trainer profile not found
1004	HVAC_ERROR_INVALID_DATA	Invalid or missing data
1005	HVAC_ERROR_SAVE_FAILED	Profile save operation failed
1006	HVAC_ERROR_GEOCODING_FAILED	Geocoding service error
1007	HVAC_ERROR_EMAIL_FAILED	Email delivery failed

Error Handling Example

// In AJAX handler
public function ajax_save_trainer_profile() {
    // Verify nonce
    if (!wp_verify_nonce($_POST['nonce'], 'hvac_trainer_profile')) {
        wp_send_json_error([
            'code' => 1001,
            'message' => 'Security verification failed'
        ]);
        return;
    }
    
    // Check permissions
    if (!current_user_can('edit_hvac_profile')) {
        wp_send_json_error([
            'code' => 1002,
            'message' => 'Insufficient permissions'
        ]);
        return;
    }
    
    // Validate profile ID
    $profile_id = intval($_POST['profile_id']);
    if (!$profile_id || get_post_type($profile_id) !== 'trainer_profile') {
        wp_send_json_error([
            'code' => 1003,
            'message' => 'Trainer profile not found'
        ]);
        return;
    }
    
    // Process save operation
    $result = $this->save_profile($profile_id, $_POST);
    
    if (is_wp_error($result)) {
        wp_send_json_error([
            'code' => 1005,
            'message' => $result->get_error_message()
        ]);
        return;
    }
    
    wp_send_json_success([
        'message' => 'Profile saved successfully',
        'profile_id' => $profile_id
    ]);
}

JavaScript Error Handling

// Client-side error handling
function handleAjaxError(response) {
    if (!response.success && response.data.code) {
        switch (response.data.code) {
            case 1001:
                // Nonce error - refresh page
                location.reload();
                break;
            case 1002:
                // Permission error
                alert('You do not have permission to perform this action.');
                break;
            case 1003:
                // Profile not found
                alert('Trainer profile not found.');
                break;
            default:
                // Generic error
                alert('An error occurred: ' + response.data.message);
        }
    }
}

// Usage in AJAX calls
jQuery.ajax({
    url: hvac_trainer.ajax_url,
    method: 'POST',
    data: requestData,
    success: function(response) {
        if (response.success) {
            // Handle success
        } else {
            handleAjaxError(response);
        }
    },
    error: function(jqXHR, textStatus, errorThrown) {
        console.error('AJAX Error:', textStatus, errorThrown);
        alert('Network error occurred. Please try again.');
    }
});

This API reference provides comprehensive technical documentation for developers working with the HVAC Trainer system. For additional examples and use cases, refer to the main system documentation.