upskill-event-manager/docs/TEC-V5-FIELD-MAPPING.md

# The Events Calendar v5.0.8 Field Mapping

## Overview
This document provides the definitive field mapping for The Events Calendar (TEC) v5.0.8 and Community Events 5.0.8, documenting the correct selectors and meta keys for all event-related fields.

## Plugin Versions
- **The Events Calendar**: 6.14.2
- **The Events Calendar Community Events**: 5.0.8
- **Events Calendar Pro**: 7.6.3

## Field Mapping Structure

### 1. Core Event Fields

| Field Name | Meta Key | Input Selector | Field Type | Notes |
|------------|----------|----------------|------------|-------|
| Event Title | post_title | `#title` | text input | Standard WordPress title field |
| Event Description | post_content | `#content` | wysiwyg/textarea | WordPress content editor |
| Event Excerpt | post_excerpt | `#excerpt` | textarea | WordPress excerpt field |
| Event Status | post_status | `#post_status` | select | WordPress status dropdown |

### 2. Date & Time Fields

| Field Name | Meta Key | Input Selector | Field Type | Notes |
|------------|----------|----------------|------------|-------|
| Start Date | `_EventStartDate` | `#EventStartDate` | date input | Format: YYYY-MM-DD |
| End Date | `_EventEndDate` | `#EventEndDate` | date input | Format: YYYY-MM-DD |
| Start Time | - | `#EventStartTime` | time input | Format: HH:MM am/pm |
| End Time | - | `#EventEndTime` | time input | Format: HH:MM am/pm |
| All Day Event | `_EventAllDay` | `#EventAllDay` | checkbox | Boolean (0/1) |
| Start Date UTC | `_EventStartDateUTC` | - | hidden/auto | Calculated from local time |
| End Date UTC | `_EventEndDateUTC` | - | hidden/auto | Calculated from local time |
| Event Duration | `_EventDuration` | - | hidden/auto | Calculated in seconds |
| Timezone | `_EventTimezone` | `select[name="EventTimezone"]` | select | Timezone dropdown |
| Timezone Abbr | `_EventTimezoneAbbr` | - | hidden/auto | Auto-generated (e.g., CST) |

### 3. Cost & Currency Fields

| Field Name | Meta Key | Input Selector | Field Type | Notes |
|------------|----------|----------------|------------|-------|
| Event Cost | `_EventCost` | `#EventCost` | text input | Numeric value |
| Currency Symbol | `_EventCurrencySymbol` | `#EventCurrencySymbol` | text input | Default: $ |
| Currency Code | `_EventCurrencyCode` | `#EventCurrencyCode` | text input | e.g., USD |
| Currency Position | - | `select[name="EventCurrencyPosition"]` | select | prefix/suffix |

### 4. Event Details

| Field Name | Meta Key | Input Selector | Field Type | Notes |
|------------|----------|----------------|------------|-------|
| Event URL | `_EventURL` | `#EventURL` | url input | External event website |
| Show Map | `_EventShowMap` | `#EventShowMap` | checkbox | Boolean (0/1) |
| Show Map Link | `_EventShowMapLink` | `#EventShowMapLink` | checkbox | Boolean (0/1) |
| Event Origin | `_EventOrigin` | - | hidden | Set to 'events-calendar' |

### 5. Venue Fields

| Field Name | Meta Key | Input Selector | Field Type | Notes |
|------------|----------|----------------|------------|-------|
| Venue ID | `_EventVenueID` | `select[name="venue[VenueID]"]` | select | Links to venue post |
| Venue Name | `_VenueVenue` | `input[name="venue[Venue]"]` | text input | For new venues |
| Venue Address | `_VenueAddress` | `input[name="venue[Address]"]` | text input | Street address |
| Venue City | `_VenueCity` | `input[name="venue[City]"]` | text input | City name |
| Venue State/Province | `_VenueStateProvince` | `input[name="venue[State]"]` | text input | State code |
| Venue Zip/Postal | `_VenueZip` | `input[name="venue[Zip]"]` | text input | Postal code |
| Venue Country | `_VenueCountry` | `select[name="venue[Country]"]` | select | Country dropdown |
| Venue Phone | `_VenuePhone` | `input[name="venue[Phone]"]` | tel input | Phone number |
| Venue Website | `_VenueURL` | `input[name="venue[URL]"]` | url input | Venue website |
| Show Venue Map | `_VenueShowMap` | `input[name="venue[ShowMap]"]` | checkbox | Boolean |
| Show Venue Map Link | `_VenueShowMapLink` | `input[name="venue[ShowMapLink]"]` | checkbox | Boolean |

### 6. Organizer Fields

| Field Name | Meta Key | Input Selector | Field Type | Notes |
|------------|----------|----------------|------------|-------|
| Organizer ID | `_EventOrganizerID` | `select[name="organizer[OrganizerID]"]` | select | Links to organizer post |
| Organizer Name | `_OrganizerOrganizer` | `input[name="organizer[Organizer]"]` | text input | For new organizers |
| Organizer Email | `_OrganizerEmail` | `input[name="organizer[Email]"]` | email input | Contact email |
| Organizer Phone | `_OrganizerPhone` | `input[name="organizer[Phone]"]` | tel input | Contact phone |
| Organizer Website | `_OrganizerWebsite` | `input[name="organizer[Website]"]` | url input | Organizer website |

## JavaScript Best Practices for TEC v5.0.8

### 1. Field Access Pattern

```javascript
// Best practice: Check multiple possible selectors
async function getTECField(page, fieldName, selectors) {
    for (const selector of selectors) {
        const element = await page.$(selector);
        if (element && await element.isVisible()) {
            return element;
        }
    }
    return null;
}

// Example usage
const startDateField = await getTECField(page, 'Start Date', [
    '#EventStartDate',
    'input[name="EventStartDate"]',
    '.tribe-datetime-block input[name*="StartDate"]'
]);
```

### 2. Setting Field Values

```javascript
// Date fields
await page.fill('#EventStartDate', '2025-12-25');

// Time fields (may need special handling)
await page.fill('#EventStartTime', '09:00 AM');

// Checkbox fields
const showMapCheckbox = await page.$('#EventShowMap');
if (showMapCheckbox) {
    await showMapCheckbox.check();
}

// Dropdown fields
await page.selectOption('select[name="venue[VenueID]"]', { value: '123' });
```

### 3. Reading Field Values

```javascript
// Text inputs
const eventCost = await page.$eval('#EventCost', el => el.value);

// Checkboxes
const showMap = await page.$eval('#EventShowMap', el => el.checked);

// Dropdowns
const venueId = await page.$eval('select[name="venue[VenueID]"]', el => el.value);
```

## Meta Data Storage

### Direct Meta Update via WP-CLI

```bash
# Update event cost
wp post meta update EVENT_ID _EventCost "299"

# Update venue ID
wp post meta update EVENT_ID _EventVenueID VENUE_ID

# Update date/time
wp post meta update EVENT_ID _EventStartDate "2025-12-25 09:00:00"
wp post meta update EVENT_ID _EventEndDate "2025-12-25 17:00:00"
```

### PHP Meta Update

```php
// Update event meta
update_post_meta($event_id, '_EventCost', '299');
update_post_meta($event_id, '_EventCurrencySymbol', '$');
update_post_meta($event_id, '_EventURL', 'https://example.com/event');
update_post_meta($event_id, '_EventVenueID', $venue_id);
update_post_meta($event_id, '_EventOrganizerID', $organizer_id);

// Date/time with UTC conversion
$start_date = '2025-12-25 09:00:00';
update_post_meta($event_id, '_EventStartDate', $start_date);
update_post_meta($event_id, '_EventStartDateUTC', get_gmt_from_date($start_date));
```

## Testing Checklist

### Essential Fields to Verify
- [ ] Event Title (`#title`)
- [ ] Event Content (`#content`)
- [ ] Start Date (`#EventStartDate`)
- [ ] End Date (`#EventEndDate`)
- [ ] Start Time (`#EventStartTime`)
- [ ] End Time (`#EventEndTime`)
- [ ] Event Cost (`#EventCost`)
- [ ] Event URL (`#EventURL`)
- [ ] Venue Selection/Creation
- [ ] Organizer Selection/Creation
- [ ] Map Display Options

### Field Persistence Test
1. Create/edit event with all fields
2. Save event
3. Reload edit page
4. Verify all fields retained values
5. Check database meta values

## Known Issues & Workarounds

### Issue 1: Cost Field May Be Hidden
Some TEC configurations hide the cost field if Events Tickets is active.
**Workaround**: Check for field visibility before attempting to fill.

### Issue 2: Venue/Organizer Dropdowns
These may be AJAX-loaded or use Select2/Chosen libraries.
**Workaround**: Wait for elements to be fully loaded before interaction.

### Issue 3: Date Format Variations
Different sites may use different date formats based on WordPress settings.
**Workaround**: Check site date format setting and adjust accordingly.

## Version History
- **v1.0** (2025-08-18): Initial mapping for TEC v5.0.8
- Based on staging environment testing
- Verified with Events Calendar Community Events 5.0.8

## References
- [TEC Developer Docs](https://theeventscalendar.com/knowledgebase/)
- [TEC GitHub Repository](https://github.com/the-events-calendar/the-events-calendar)
- WordPress Meta API Documentation