From 7f0964009a081f3bacbb529fe0d7530660fbbd93 Mon Sep 17 00:00:00 2001
From: twotalesanimation <80506065+twotalesanimation@users.noreply.github.com>
Date: Thu, 4 Dec 2025 20:26:17 +0200
Subject: [PATCH] docs: add events admin system documentation

---
 docs/EVENTS_ADMIN_SYSTEM.md | 176 ++++++++++++++++++++++++++++++++++++
 1 file changed, 176 insertions(+)
 create mode 100644 docs/EVENTS_ADMIN_SYSTEM.md

diff --git a/docs/EVENTS_ADMIN_SYSTEM.md b/docs/EVENTS_ADMIN_SYSTEM.md
new file mode 100644
index 00000000..95c7dbc1
--- /dev/null
+++ b/docs/EVENTS_ADMIN_SYSTEM.md
@@ -0,0 +1,176 @@
+# Events Management Admin System
+
+## Overview
+A complete admin system for managing events on the 4WDCSA website, following the same patterns as the trip management system.
+
+## Files Created
+
+### 1. `/src/admin/manage_events.php`
+**Purpose**: Form for creating and editing events
+
+**Features**:
+- Create new events form
+- Edit existing events form
+- Fields:
+  - Event Name (required)
+  - Event Type (required) - e.g., Workshop, Training, Rally
+  - Location (required)
+  - Date (required)
+  - Time (required)
+  - Feature/Category (required) - e.g., Off-Road Training, Social Event
+  - Description (required) - Full text description
+  - Event Image (required for new, optional for updates)
+  - Promotional Image (optional) - Displayed when users click "View Promo"
+  - Published Status (checkbox) - Controls visibility on website
+
+**Technical Details**:
+- AJAX form submission to `process_event` endpoint
+- Image upload with validation
+- CSRF token protection
+- Responsive Bootstrap grid layout (col-md-6 fields)
+- Success/error message display with auto-redirect
+
+### 2. `/src/admin/process_event.php`
+**Purpose**: Backend endpoint for handling event CRUD operations
+
+**Endpoints**:
+- `POST /process_event` - Create/Update event
+- `GET /process_event?action=delete&event_id={id}` - Delete event
+
+**Features**:
+- Create new events with image uploads
+- Update existing events with optional image replacement
+- Delete events and associated image files
+- CSRF token validation
+- Image type validation (JPEG, PNG, GIF, WebP)
+- File organization in `/assets/images/events/`
+- Automatic timestamp management (created_at, updated_at)
+- User tracking (created_by stores admin user_id)
+
+**Image Handling**:
+- Main event image: Stored with unique ID prefix
+- Promo image: Stored with `_promo_` prefix
+- Both uploaded to `/assets/images/events/`
+
+### 3. `/src/admin/admin_events.php`
+**Purpose**: Admin dashboard for managing all events
+
+**Features**:
+- List all events with sortable columns
+- Real-time search/filter across all columns
+- Create new event button
+- Edit event link for each row
+- Delete event with confirmation dialog
+- Status badges (Published/Draft)
+- Responsive table with alternating row colors
+- Rounded corners on even rows
+
+**Sortable Columns**:
+- Event Name
+- Type
+- Location
+- Date
+- Status
+
+**Actions**:
+- Edit - Redirects to manage_events.php with event_id
+- Delete - Removes event and associated files
+
+## Database Schema Changes
+
+### Migration File: `/docs/migrations/001_add_events_tracking_columns.sql`
+
+**Columns Added to events table**:
+- `created_by` (int) - References user who created the event
+- `published` (tinyint(1)) - Boolean flag for publication status (default 0/false)
+- `created_at` (timestamp) - Automatic timestamp when event is created
+- `updated_at` (timestamp) - Automatic timestamp updated on modification
+
+**Indexes Added**:
+- `idx_date` - For sorting and filtering by date
+- `idx_published` - For filtering published/draft events
+- `idx_created_by` - For tracking who created events
+
+## Design Patterns
+
+### Follows Trip Management System Architecture
+- Same form layout and styling (`.comment-form.bgc-lighter`)
+- Same table styling with sortable headers and filters
+- Same image upload and validation patterns
+- AJAX submission with success/error messaging
+- Auto-redirect on successful operation
+
+### Image Organization
+```
+/assets/images/events/
+├── {unique_id}_{original_filename}.jpg (event images)
+└── {unique_id}_promo_{original_filename}.jpg (promo images)
+```
+
+### Front-end Integration
+The existing `/src/pages/events/events.php` displays published events:
+- Shows event image, name, location, date, time
+- Feature description and full description
+- "View Promo" button displays promotional image in modal
+
+## Usage Workflow
+
+### Creating an Event
+1. Navigate to `/src/admin/manage_events.php`
+2. Fill in all required fields
+3. Upload event image
+4. Optionally upload promotional image
+5. Check "Publish Event" if ready to display
+6. Submit form via AJAX
+7. Redirected to admin_events.php list view
+
+### Editing an Event
+1. Click "Edit" button on admin_events.php
+2. Modify any fields
+3. Image upload is optional - existing image retained if not changed
+4. Update timestamps and user tracking automatic
+5. Submit form
+6. Redirected back to list view
+
+### Deleting an Event
+1. Click "Delete" button on admin_events.php
+2. Confirm deletion in dialog
+3. Event and associated image files removed from server
+4. Page automatically refreshes
+
+### Publishing/Unpublishing
+- Toggle "Publish Event" checkbox before saving
+- Only published events appear on `/src/pages/events/events.php`
+- Draft events hidden from public view
+
+## Security Features
+
+1. **CSRF Token Protection**: All forms include CSRF token validation
+2. **Admin-only Access**: `checkAdmin()` function validates user permissions
+3. **File Validation**: Image type checking (JPEG, PNG, GIF, WebP)
+4. **SQL Injection Prevention**: Prepared statements with parameter binding
+5. **XSS Prevention**: `htmlspecialchars()` used for output escaping
+
+## Styling Classes
+
+**Form Container**: `.comment-form.bgc-lighter.z-1.rel.mb-30.rmb-55`
+**Action Buttons**: `.btn-edit`, `.btn-delete`
+**Status Badges**: `.badge.badge-published`, `.badge.badge-draft`
+**Tables**: Uses sortable header styling with visual sort indicators
+
+## Browser Compatibility
+
+- Modern browsers with AJAX/Fetch API support
+- JavaScript enabled required for filtering and sorting
+- File input accepts image MIME types
+
+## Future Enhancement Opportunities
+
+1. Bulk event operations (bulk delete, publish multiple)
+2. Event categories/tags system
+3. Event capacity limits with registrations
+4. Email notifications for published events
+5. Event calendar view
+6. Event image gallery (multiple images per event)
+7. Recurring events support
+8. Event attendee tracking