# HVAC Community Events - Refactoring Guide

## Overview

This document describes the refactoring of the HVAC Community Events plugin to follow WordPress best practices for better maintainability and scalability.

## Architecture Changes

### Before (Monolithic Structure)
```
hvac-community-events.php (4000+ lines)
├── All page definitions
├── Activation logic
├── Redirect handling
└── Mixed responsibilities
```

### After (Modular Structure)
```
hvac-community-events.php (30 lines - bootstrap only)
├── includes/
│   ├── class-hvac-plugin.php (Main plugin orchestrator)
│   ├── class-hvac-activator.php (Activation logic)
│   ├── class-hvac-deactivator.php (Deactivation logic)
│   ├── class-hvac-page-manager.php (Page creation/management)
│   └── class-hvac-template-loader.php (Template handling)
└── templates/
    ├── content/ (Gutenberg block content)
    ├── status/ (Status page templates)
    └── pages/ (Other page templates)
```

## Key Improvements

### 1. Separation of Concerns
- **Page Management**: All page-related logic moved to `HVAC_Page_Manager`
- **Template Loading**: Dedicated `HVAC_Template_Loader` class
- **Activation**: Clean `HVAC_Activator` class
- **Content Storage**: Page content in separate HTML files

### 2. Template Override System
Themes can now override plugin templates by copying them to:
```
/your-theme/hvac-community-events/[template-path]
```

### 3. Dynamic Content Placeholders
Content files support placeholders:
- `{home_url}` - Site home URL
- `{logout_url}` - Logout URL
- `{login_url}` - Login URL
- `{site_name}` - Site name
- `{support_email}` - Support email

### 4. Hooks and Filters
New action hooks:
- `hvac_trainer_pending_after_content` - After pending page content
- `hvac_trainer_disabled_after_content` - After disabled page content

## Migration Steps

### 1. Backup Current Plugin
```bash
cp -r hvac-community-events hvac-community-events-backup
```

### 2. Replace Main Plugin File
```bash
mv hvac-community-events-new.php hvac-community-events.php
```

### 3. Test Activation
- Deactivate plugin
- Activate plugin
- Verify all pages are created

### 4. Update Custom Code
If you have custom code referencing the old structure:

**Old way:**
```php
// Pages were hardcoded in main file
$pages = [...]; // 200+ lines of page definitions
```

**New way:**
```php
// Use the page manager
$page_config = HVAC_Page_Manager::get_page_config('trainer-account-pending');
```

## Benefits

1. **Maintainability**: Each component has a single responsibility
2. **Testability**: Classes can be unit tested independently
3. **Extensibility**: Easy to add new pages or modify existing ones
4. **Performance**: Only loads what's needed
5. **Standards**: Follows WordPress coding standards and best practices

## File Locations

### Status Page Content
- `/templates/content/trainer-account-pending.html`
- `/templates/content/trainer-account-disabled.html`

### Status Page Templates
- `/templates/status/trainer-account-pending.php`
- `/templates/status/trainer-account-disabled.php`

### Core Classes
- `/includes/class-hvac-plugin.php` - Main plugin class
- `/includes/class-hvac-page-manager.php` - Page management
- `/includes/class-hvac-template-loader.php` - Template loading
- `/includes/class-hvac-activator.php` - Activation logic
- `/includes/class-hvac-deactivator.php` - Deactivation logic

## Customization

### Adding a New Page
1. Add page definition to `HVAC_Page_Manager::$pages`
2. Create content file in `/templates/content/` (optional)
3. Create template file in `/templates/` (optional)

### Modifying Page Content
1. Edit the HTML file in `/templates/content/`
2. Or override in theme: `/your-theme/hvac-community-events/content/[filename]`

### Custom Templates
1. Copy template from plugin to theme
2. Modify as needed
3. Plugin will automatically use theme version

## Testing Checklist

- [ ] Plugin activates without errors
- [ ] All pages are created correctly
- [ ] Status pages show correct content
- [ ] Template overrides work in theme
- [ ] Access control still functions
- [ ] No PHP errors in logs
- [ ] Performance is maintained

## Rollback Plan

If issues occur:
1. Deactivate plugin
2. Restore backup: `cp -r hvac-community-events-backup/* hvac-community-events/`
3. Reactivate plugin

## Future Enhancements

1. **Block Patterns**: Register Gutenberg block patterns for reusable layouts
2. **REST API**: Add endpoints for page management
3. **CLI Commands**: WP-CLI commands for page operations
4. **Unit Tests**: PHPUnit tests for all classes
5. **Composer**: Autoloading and dependency management