upskill-event-manager/docs/role-implementation-plan.md

HVAC Trainer Role Implementation Plan

Overview

This document outlines the plan for implementing the hvac_trainer role in the HVAC Community Events plugin, ensuring proper integration with WordPress core and The Events Calendar plugin suite.

Requirements Analysis

The hvac_trainer role needs to:

1. Allow trainers to manage their own events using The Events Calendar
2. Restrict access to WordPress admin areas
3. Provide custom capabilities for HVAC-specific features
4. Integrate with The Events Calendar's event management capabilities

Implementation Architecture

classDiagram
    class HVAC_Community_Events {
        +activate()
        +deactivate()
        +init()
    }
    
    class HVAC_Roles {
        +create_trainer_role()
        +remove_trainer_role()
        +get_trainer_capabilities()
        +check_trainer_capability(capability)
    }
    
    class HVAC_Registration {
        +create_trainer_account(data)
    }
    
    HVAC_Community_Events --> HVAC_Roles : includes/initializes
    HVAC_Registration --> HVAC_Roles : uses capabilities

Detailed Implementation Steps

1. Create Role Management Class

We will create a new file class-hvac-roles.php with the following functionality:

class HVAC_Roles {
    /**
     * Create the hvac_trainer role
     */
    public function create_trainer_role() {
        // Check if role already exists
        if (get_role('hvac_trainer')) {
            return;
        }
        
        // Add the role with basic capabilities
        add_role(
            'hvac_trainer',
            __('HVAC Trainer', 'hvac-community-events'),
            $this->get_trainer_capabilities()
        );
    }
    
    /**
     * Remove the hvac_trainer role
     */
    public function remove_trainer_role() {
        remove_role('hvac_trainer');
    }
    
    /**
     * Get all capabilities for the hvac_trainer role
     */
    public function get_trainer_capabilities() {
        // Default capabilities
        $caps = array(
            'read' => true,
            'upload_files' => true,
            
            // Custom HVAC capabilities
            'manage_hvac_events' => true,
            'edit_hvac_profile' => true,
            'view_hvac_dashboard' => true,
            'manage_attendees' => true,
            'email_attendees' => true,
            
            // Events Calendar capabilities
            'publish_tribe_events' => true,
            'edit_tribe_events' => true,
            'delete_tribe_events' => true,
            'edit_published_tribe_events' => true,
            'delete_published_tribe_events' => true,
            'read_private_tribe_events' => true,
        );
        
        // Restrict access to admin areas
        $admin_caps = array(
            'manage_options', 
            'moderate_comments',
            'manage_categories',
            'manage_links',
            'edit_others_posts',
            'edit_pages',
            'edit_others_pages',
            'edit_published_pages',
            'publish_pages',
            'delete_pages',
            'delete_others_pages',
            'delete_published_pages',
            'delete_others_posts',
            'import',
            'export',
            'edit_theme_options',
        );
        
        foreach ($admin_caps as $cap) {
            $caps[$cap] = false;
        }
        
        return $caps;
    }
    
    /**
     * Check if current user has a specific HVAC trainer capability
     */
    public function check_trainer_capability($capability) {
        return current_user_can($capability);
    }
}

2. Update Main Plugin Class

We will modify class-hvac-community-events.php to:

• Include the new roles class
• Create the role during plugin activation
• Remove the role during plugin deactivation

private function includes() {
    require_once HVAC_CE_PLUGIN_DIR . 'includes/class-hvac-roles.php';
    require_once HVAC_CE_PLUGIN_DIR . 'includes/class-hvac-registration.php';
}

public function activate() {
    // Create the hvac_trainer role
    $roles = new HVAC_Roles();
    $roles->create_trainer_role();
}

public function deactivate() {
    // Remove the hvac_trainer role
    $roles = new HVAC_Roles();
    $roles->remove_trainer_role();
}

3. Integration with Registration System

The registration system already assigns the 'hvac_trainer' role in the create_trainer_account() method, so no changes are needed there.

4. Admin Redirect for Trainers

To prevent trainers from accessing the WordPress admin area, we'll add a redirect:

public function init() {
    // Prevent trainers from accessing wp-admin
    add_action('admin_init', array($this, 'redirect_trainers_from_admin'));
}

public function redirect_trainers_from_admin() {
    if (current_user_can('view_hvac_dashboard') && !current_user_can('manage_options')) {
        wp_redirect(home_url('/hvac-trainer-dashboard/'));
        exit;
    }
}

5. Testing the Implementation

To ensure the role works correctly, we'll:

1. Test role creation during plugin activation
2. Test trainer registration and role assignment
3. Verify trainer permissions with The Events Calendar
4. Test admin area restrictions
5. Test event creation, editing, and deletion capabilities

Considerations and Potential Issues

1. Plugin Dependencies: The role's capabilities depend on The Events Calendar plugin. We should check if the plugin is active before adding its capabilities.

2. Role Migration: If the capabilities change in a future update, we'll need a mechanism to update existing roles.

3. Role Conflict: If a user already has the WordPress administrator role, adding the trainer role could cause confusion.

4. Backward Compatibility: Ensure compatibility with existing registered trainers if the role didn't previously exist.

Implementation Timeline

1. Create class-hvac-roles.php - 1 hour
2. Update main plugin class - 30 minutes
3. Add admin redirect - 30 minutes
4. Testing and debugging - 2 hours

Total estimated time: 4 hours