upskill-event-manager/docs/VENUE-MANAGEMENT.md

Venue Management System Documentation

Version: 2.0.0
Last Updated: August 28, 2025
Component: HVAC_Venues
Status: ✅ Production Ready

Table of Contents

1. Overview
2. Features
3. User Interface
4. Technical Architecture
5. Database Schema
6. API Reference
7. Integration with The Events Calendar
8. Security Considerations
9. Troubleshooting

Overview

The Venue Management System provides trainers with comprehensive tools to create, manage, and organize training venues. This system is fully integrated with The Events Calendar (TEC) plugin, allowing seamless venue selection during event creation.

Key Benefits

• Centralized Management: All venues in one searchable directory
• Reusability: Create once, use for multiple events
• Location Services: Automatic geocoding and map integration
• Access Control: Trainers can only edit their own venues
• TEC Integration: Native support for The Events Calendar

Features

Core Functionality

1. Venue Listing (/trainer/venue/list/)

• Searchable Directory: Filter venues by name, city, or state
• Pagination: 20 venues per page with navigation
• Ownership Indicators: Visual badges for user's own venues
• Quick Actions: Edit buttons for owned venues
• Responsive Table: Mobile-optimized display

2. Venue Management (/trainer/venue/manage/)

• Create New Venues: Complete form with validation
• Edit Existing Venues: Update all venue details
• Delete Venues: Safe deletion with event check
• Rich Information: Address, contact, and description fields

Data Fields

Required Fields

• Venue Name: Unique identifier for the venue
• Street Address: Physical location
• City: Municipality name
• State/Province: Regional identifier
• Zip/Postal Code: Postal information
• Country: Selected from supported countries

Optional Fields

• Description: Detailed venue information
• Phone Number: Contact telephone
• Website URL: Venue website
• Show Map: Display map on event pages
• Show Map Link: Include directions link

Advanced Features

Location Services

• Geocoding: Automatic latitude/longitude calculation
• Map Display: Interactive maps on public pages
• Directions: Google Maps integration

Search and Filter

• Text Search: Find venues by name
• State Filter: Filter by state/province
• Pagination: Navigate large venue lists
• Sort Options: Alphabetical by default

User Interface

Venue List Page

┌─────────────────────────────────────────────┐
│ Training Venues            [Add New Venue]  │
├─────────────────────────────────────────────┤
│ [Search: ________] [State: All ▼] [Filter]  │
├─────────────────────────────────────────────┤
│ Name │ Address │ City │ State │ Actions     │
├──────┼─────────┼──────┼───────┼────────────┤
│ Main │ 123 St  │ NYC  │ NY    │ [Edit]     │
│ Hall │         │      │       │ Your Venue │
└─────────────────────────────────────────────┘

Venue Management Form

┌─────────────────────────────────────────────┐
│ Create New Venue / Edit Venue               │
├─────────────────────────────────────────────┤
│ Venue Information                           │
│ ├─ Venue Name: [_______________] *          │
│ └─ Description: [_______________]           │
│                                             │
│ Location Details                            │
│ ├─ Street Address: [___________] *          │
│ ├─ City: [_________] *                      │
│ ├─ State: [________] *                      │
│ ├─ Zip: [_____] *                          │
│ └─ Country: [United States ▼] *            │
│                                             │
│ Contact Information                         │
│ ├─ Phone: [___________]                    │
│ └─ Website: [_________]                    │
│                                             │
│ [Save Venue] [Cancel] [Delete]             │
└─────────────────────────────────────────────┘

Technical Architecture

Class Structure

class HVAC_Venues {
    // Singleton pattern
    private static $instance = null;
    
    public static function instance() {
        if (null === self::$instance) {
            self::$instance = new self();
        }
        return self::$instance;
    }
    
    // Core methods
    public function render_venues_list()
    public function render_venue_manage()
    public function ajax_save_venue()
    public function ajax_delete_venue()
    public function ajax_load_venue()
}

File Structure

includes/
├── class-hvac-venues.php          # Main venue class
assets/
├── css/
│   └── hvac-venues.css           # Venue styles
└── js/
    └── hvac-venues.js            # Venue JavaScript
templates/
├── page-trainer-venue-list.php    # List template
└── page-trainer-venue-manage.php  # Manage template

AJAX Endpoints

Save Venue

• Action: wp_ajax_hvac_save_venue
• Nonce: hvac_venues_nonce
• Parameters: venue data fields
• Response: Success/error with venue ID

Delete Venue

• Action: wp_ajax_hvac_delete_venue
• Nonce: hvac_venues_nonce
• Parameters: venue_id
• Response: Success/error message

Load Venue

• Action: wp_ajax_hvac_load_venue
• Nonce: hvac_venues_nonce
• Parameters: venue_id
• Response: Venue data object

Database Schema

Post Type

• Type: tribe_venue
• Status: publish
• Author: Current user ID

Post Meta Fields

_VenueAddress       -- Street address
_VenueCity          -- City name
_VenueState         -- State abbreviation
_VenueStateProvince -- Full state/province name
_VenueZip           -- Postal code
_VenueCountry       -- Country name
_VenuePhone         -- Phone number
_VenueURL           -- Website URL
_VenueShowMap       -- Boolean (show map)
_VenueShowMapLink   -- Boolean (show directions)
_VenueLat           -- Latitude (geocoded)
_VenueLng           -- Longitude (geocoded)

API Reference

PHP Functions

Creating a Venue

// Using TEC function
$venue_id = tribe_create_venue([
    'Venue' => 'Conference Center',
    'Address' => '123 Main St',
    'City' => 'New York',
    'StateProvince' => 'NY',
    'Zip' => '10001',
    'Country' => 'United States',
    'Phone' => '555-0123',
    'URL' => 'https://example.com'
]);

// Using HVAC wrapper
$venues = HVAC_Venues::instance();
$venue_data = $venues->create_venue($data);

Retrieving Venues

// Get all venues for current user
$venues = get_posts([
    'post_type' => 'tribe_venue',
    'author' => get_current_user_id(),
    'posts_per_page' => -1
]);

// Get venue by ID
$venue = get_post($venue_id);
$address = get_post_meta($venue_id, '_VenueAddress', true);

Updating a Venue

// Using TEC function
tribe_update_venue($venue_id, [
    'Venue' => 'Updated Name',
    'City' => 'Updated City'
]);

// Direct update
update_post_meta($venue_id, '_VenueCity', 'New City');

JavaScript Functions

Save Venue via AJAX

jQuery.ajax({
    url: hvacVenues.ajax_url,
    type: 'POST',
    data: {
        action: 'hvac_save_venue',
        nonce: hvacVenues.nonce,
        venue_name: 'Conference Center',
        venue_address: '123 Main St',
        // ... other fields
    },
    success: function(response) {
        if (response.success) {
            console.log('Venue saved:', response.data.venue_id);
        }
    }
});

Integration with The Events Calendar

Event Creation

When creating an event, venues appear in a dropdown:

// Venues are automatically available in TEC
// No additional integration required

Venue Selection

// In event creation form
$('#EventVenueID').val(venue_id);

Public Display

Venues are displayed on event pages with:

• Full address
• Map (if enabled)
• Directions link (if enabled)
• Contact information

Security Considerations

Access Control

• Creation: Any logged-in trainer can create venues
• Editing: Only venue owner can edit
• Deletion: Only venue owner can delete
• Viewing: All trainers can view all venues

Data Validation

// All inputs are sanitized
$venue_name = sanitize_text_field($_POST['venue_name']);
$venue_address = sanitize_text_field($_POST['venue_address']);
$venue_url = esc_url_raw($_POST['venue_website']);
$venue_description = wp_kses_post($_POST['venue_description']);

Nonce Verification

// All AJAX requests verify nonces
check_ajax_referer('hvac_venues_nonce', 'nonce');

SQL Injection Prevention

// Using WordPress prepared statements
$wpdb->prepare("SELECT * FROM $wpdb->posts WHERE ID = %d", $venue_id);

Troubleshooting

Common Issues

Venue Not Appearing in Event Creation

Problem: Created venue doesn't show in dropdown
Solution: Check venue post_status is 'publish'

// Verify venue status
$venue = get_post($venue_id);
if ($venue->post_status !== 'publish') {
    wp_update_post(['ID' => $venue_id, 'post_status' => 'publish']);
}

Cannot Delete Venue

Problem: Delete button doesn't work
Solution: Venue is being used by events

// Check for events using venue
$events = get_posts([
    'post_type' => 'tribe_events',
    'meta_key' => '_EventVenueID',
    'meta_value' => $venue_id
]);
if (!empty($events)) {
    // Cannot delete - venue in use
}

Map Not Displaying

Problem: Map doesn't show on event page
Solution: Enable map display

update_post_meta($venue_id, '_VenueShowMap', 'true');
update_post_meta($venue_id, '_VenueShowMapLink', 'true');

Error Messages

Error	Meaning	Solution
"Unauthorized"	User not logged in or not a trainer	Check user role
"Cannot delete venue"	Venue is being used by events	Remove venue from events first
"Invalid venue ID"	Venue doesn't exist	Verify venue ID
"Permission denied"	User doesn't own the venue	Only edit own venues

Best Practices

Performance

• Caching: Venue queries are cached
• Pagination: Large lists are paginated
• Lazy Loading: Maps load on demand

User Experience

• Auto-save: Form data persists
• Validation: Real-time field validation
• Feedback: Clear success/error messages

Development

• Singleton Pattern: Use HVAC_Venues::instance()
• Hooks: Use WordPress actions/filters
• Security: Always validate and sanitize

Future Enhancements

Planned Features

• Bulk Import: CSV venue upload
• Venue Categories: Organize by type
• Capacity Tracking: Maximum attendees
• Amenities: List venue features
• Photo Gallery: Multiple venue images
• Availability Calendar: Booking system
• Reviews: Trainer venue ratings

API Extensions

• REST API: Full CRUD operations
• GraphQL: Query support
• Webhooks: Event notifications

---

For additional support, see TROUBLESHOOTING.md or contact the development team.