jonny/gcp-hockey-results
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
00f6c6576a
gcp-hockey-results/motm_app/VOTING_DEADLINE_IMPLEMENTATION.md

4.7 KiB
Raw Blame History

Voting Deadline Implementation Summary

✅ Feature Complete

The voting deadline feature has been successfully implemented! This feature adds a countdown timer to the MOTM voting page and prevents votes from being cast after a specified deadline.

What's New

1. Admin Interface

  • Added a "Voting Deadline" field in the MOTM Settings page
  • Admins can set when voting should close using a datetime picker
  • The field is optional - leave it blank for unlimited voting

2. Voting Page

  • Countdown Timer: Shows time remaining in real-time
    • Updates every second
    • Color-coded alerts (blue → yellow → red as deadline approaches)
    • Displays in human-friendly format (days, hours, minutes, seconds)
  • Automatic Lockout: When deadline hits zero:
    • Timer is replaced with "Voting has closed" message
    • All form inputs are disabled
    • Submit button shows "Voting Closed"

3. Security

  • Client-side validation: Immediate feedback to users
  • Server-side validation: Authoritative check (cannot be bypassed)
  • Returns error page if someone tries to submit after deadline

Files Changed

Backend (Python)

  1. database.py - Added voting_deadline column to AdminSettings model
  2. forms.py - Added votingDeadline field to admin form
  3. main.py - Updated three routes:
    • /admin/motm - Save and load deadline
    • /motm/<randomUrlSuffix> - Pass deadline to template
    • /motm/vote-thanks - Validate deadline on submission

Frontend (Templates)

  1. templates/motm_admin.html - Added deadline input field with datetime picker
  2. templates/motm_vote.html - Added countdown timer UI and JavaScript logic

Migration

  1. add_voting_deadline.py - Database migration script (auto-run)
  2. VOTING_DEADLINE_FEATURE.md - User documentation

How to Use

As an Admin

  1. Go to Admin Dashboard → MOTM Settings
  2. Fill in match details (date, opponent, etc.)
  3. Set the Voting Deadline:
    • Click the datetime picker field
    • Select date and time when voting should close
    • Example: 2025-10-15 18:00 (6 PM on Oct 15)
  4. Click Save Settings or Activate MotM Vote

As a Voter

  • If a deadline is set, you'll see a countdown timer at the top of the voting page
  • The timer shows exactly how much time is left
  • When time runs out, you won't be able to vote
  • Try to vote before the deadline! ⏰

Database Migration

The migration has been automatically completed for your database! ✅

The votingdeadline column has been added to the admin_settings table.

If you need to run it again on another database:

python add_voting_deadline.py

Testing the Feature

Test Scenario 1: Set a deadline 5 minutes in the future

  1. Go to MOTM Settings
  2. Set deadline to 5 minutes from now
  3. Save and activate voting
  4. Open the voting page
  5. Watch the countdown timer
  6. Timer should change color as it gets closer to zero
  7. When it hits zero, form should be disabled

Test Scenario 2: Try to vote after deadline

  1. Wait for deadline to pass
  2. Try to submit a vote
  3. Should show error: "Voting has closed. The deadline has passed."

Test Scenario 3: No deadline

  1. Leave the deadline field empty
  2. Save settings
  3. Voting page should NOT show countdown timer
  4. Voting should work indefinitely

Browser Compatibility

The countdown timer uses standard JavaScript and should work on:

  • ✅ Chrome/Edge (all recent versions)
  • ✅ Firefox (all recent versions)
  • ✅ Safari (all recent versions)
  • ✅ Mobile browsers

Color Coding

The countdown timer changes color based on urgency:

Time Remaining Color Meaning
> 5 minutes Blue (Info) Plenty of time
1-5 minutes Yellow (Warning) Getting close!
< 1 minute Red (Danger) Hurry!

Tips

  1. Set realistic deadlines: Give voters enough time to participate
  2. Consider timezones: The deadline uses server time
  3. Test first: Try with a short deadline to see how it works
  4. No deadline needed: Leave blank for unlimited voting

Troubleshooting

Issue: Countdown not showing

Solution: Make sure you've set a deadline in the admin settings

Issue: "Voting has closed" but should be open

Solution: Check the deadline in admin settings - may be set incorrectly

Issue: Time seems wrong

Solution: Server timezone may differ from your local time

Next Steps

The feature is ready to use! Here's what you can do:

  1. ✅ Set up your next match in MOTM Settings
  2. ✅ Add a voting deadline
  3. ✅ Share the voting URL with your team
  4. ✅ Watch the votes come in before the deadline!

Need help? Check VOTING_DEADLINE_FEATURE.md for detailed documentation.