122 lines
4.1 KiB
Markdown
122 lines
4.1 KiB
Markdown
# Voting Deadline Feature
|
|
|
|
## Overview
|
|
|
|
The voting deadline feature adds a countdown timer to the MOTM (Man of the Match) voting page and prevents votes from being cast after the specified deadline.
|
|
|
|
## Features
|
|
|
|
### 1. Admin Configuration
|
|
- Admins can set a voting deadline when configuring match details
|
|
- The deadline field is optional - leave it empty for no deadline
|
|
- Uses a datetime-local input for easy date and time selection
|
|
- The deadline is automatically saved with the match settings
|
|
|
|
### 2. Countdown Timer
|
|
- Displays a prominent countdown timer on the voting page
|
|
- Shows time remaining in a user-friendly format:
|
|
- Days, hours, minutes, seconds (when days remaining)
|
|
- Hours, minutes, seconds (when hours remaining)
|
|
- Minutes, seconds (when minutes remaining)
|
|
- Seconds only (when less than 1 minute remaining)
|
|
- Color-coded alerts:
|
|
- Blue (info) - More than 5 minutes remaining
|
|
- Yellow (warning) - Less than 5 minutes remaining
|
|
- Red (danger) - Less than 1 minute remaining
|
|
|
|
### 3. Vote Protection
|
|
- **Client-side**: Form inputs are disabled when the deadline is reached
|
|
- **Server-side**: Backend validation prevents vote submission after deadline
|
|
- Shows a clear "Voting has closed" message when deadline passes
|
|
- Both frontend and backend validation ensure votes cannot bypass the deadline
|
|
|
|
## Usage
|
|
|
|
### For Administrators
|
|
|
|
1. Navigate to **Admin Dashboard** → **MOTM Settings**
|
|
2. Fill in the match details (date, opponent, etc.)
|
|
3. Set the **Voting Deadline** using the date/time picker
|
|
- Example: `2025-10-15 18:00` (6 PM on October 15, 2025)
|
|
4. Click **Save Settings** or **Activate MotM Vote**
|
|
|
|
### For Voters
|
|
|
|
When a deadline is set:
|
|
- The voting page will display a countdown timer at the top
|
|
- The timer updates every second
|
|
- When the deadline is reached:
|
|
- The countdown is replaced with "Voting has closed"
|
|
- All form fields are disabled
|
|
- The submit button shows "Voting Closed"
|
|
- Attempting to submit after the deadline shows an error message
|
|
|
|
## Database Migration
|
|
|
|
### For Existing Installations
|
|
|
|
If you're upgrading from a version without the voting deadline feature, run the migration script:
|
|
|
|
```bash
|
|
python add_voting_deadline.py
|
|
```
|
|
|
|
This script will:
|
|
- Add the `votingdeadline` column to the `motmadminsettings` table
|
|
- Check if the column already exists (safe to run multiple times)
|
|
- Support both PostgreSQL and SQLite databases
|
|
|
|
### For New Installations
|
|
|
|
New installations will automatically include the `voting_deadline` column when creating the database.
|
|
|
|
## Technical Details
|
|
|
|
### Database Schema
|
|
|
|
**Table**: `motmadminsettings` (or `admin_settings` in ORM)
|
|
|
|
New column:
|
|
- `votingdeadline` (TIMESTAMP/DATETIME, nullable)
|
|
|
|
### Files Modified
|
|
|
|
1. **database.py** - Added `voting_deadline` column to `AdminSettings` model
|
|
2. **forms.py** - Added `votingDeadline` field to `adminSettingsForm2`
|
|
3. **main.py** - Updated routes:
|
|
- `/admin/motm` - Save and load deadline
|
|
- `/motm/<randomUrlSuffix>` - Pass deadline to template
|
|
- `/motm/vote-thanks` - Validate deadline on submission
|
|
4. **templates/motm_admin.html** - Added deadline input field
|
|
5. **templates/motm_vote.html** - Added countdown timer UI and JavaScript
|
|
|
|
### Security Considerations
|
|
|
|
- Client-side validation provides immediate feedback
|
|
- Server-side validation in `vote_thanks()` route is the authoritative check
|
|
- Users cannot bypass the deadline by manipulating JavaScript
|
|
- Timezone-aware datetime handling ensures consistency
|
|
|
|
## Troubleshooting
|
|
|
|
### Issue: Countdown timer not appearing
|
|
- **Cause**: No deadline set in admin settings
|
|
- **Solution**: Set a deadline in the MOTM settings page
|
|
|
|
### Issue: "Column doesn't exist" error
|
|
- **Cause**: Database needs migration
|
|
- **Solution**: Run `python add_voting_deadline.py`
|
|
|
|
### Issue: Votes still accepted after deadline
|
|
- **Cause**: Server timezone mismatch
|
|
- **Solution**: Ensure server datetime is correctly configured
|
|
|
|
## Future Enhancements
|
|
|
|
Potential improvements for future versions:
|
|
- Timezone selection for deadline
|
|
- Email notifications when voting closes
|
|
- Automatic deadline based on match date (e.g., 24 hours after match)
|
|
- Grace period for late votes with visual indicator
|
|
|