gcp-hockey-results/motm_app/VOTING_DEADLINE_FEATURE.md

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:

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