Building an Interactive Quiz Game with Streamlit: Turn Documents into Engaging Quizzes
From Dull Docs to Quiz Whiz: Because Even Your Spreadsheets Deserve a Laugh!
Hey everyone! If you’ve ever wanted to create fun, interactive quizzes from everyday documents like Excel spreadsheets, Word files, or even JSON data, I’ve got something exciting to share. I recently built an Interactive Quiz Game Application using Streamlit, and it’s designed to intelligently generate quizzes, let players compete, and track scores on a live leaderboard. The full code is available on GitHub at https://github.com/rod-trent/JunkDrawer/tree/main/QuizBuilder. In this post, I’ll break down what the app is, how it works, why it’s useful, the requirements, setup instructions, and more. Let’s dive in!
What is the Interactive Quiz Game?
This is a web-based application built with Streamlit, a fantastic Python library for creating interactive apps without needing frontend expertise. The core idea is simple: upload a document (like an agenda in Excel or a Q&A list in Word), and the app automatically generates a multiple-choice quiz from it. Players can then take the quiz, submit answers, and see their scores ranked on a leaderboard.
It’s split into two main interfaces:
Play Quiz Tab: For users to select a game, answer questions, and view the leaderboard.
Admin Panel Tab: For admins to upload documents, generate new quizzes, and manage games (password-protected for security).
The app handles various file formats and uses intelligent parsing to create meaningful questions— no manual question-writing required!
Key Features and What It Does
The app is packed with functionality to make quiz creation and playing seamless:
Intelligent Quiz Generation:
Supports multiple file types: Excel (.xlsx/.xls), Word (.docx/.doc), JSON (.json), and CSV (.csv).
Parses content smartly:
For Excel/CSV: Looks for columns like “Question” and “Answer” or generates questions from structured data (e.g., agendas with titles, descriptions, speakers, rooms).
For Word: Scans for Q&A patterns (e.g., “Q: What is...? A: This is...”) or generates from paragraphs.
For JSON: Extracts key-value pairs or pre-formatted quiz data.
All questions are converted to multiple-choice with 4 options (correct answer + 3 plausible wrongs pulled from the document to avoid duplicates).
Limits questions per sheet/section to keep things manageable.
Gameplay Mechanics:
Players select a quiz game from a dropdown.
Enter their name for the leaderboard.
Answer questions one by one (radio buttons for choices).
Immediate feedback: Correct/incorrect with the right answer shown.
Tracks score, accuracy, and progress in real-time.
At the end, shows a review of answers, final stats, and a motivational message based on performance.
Leaderboard System:
Saves scores persistently in JSON files.
Displays top 10 scores with rank, player name, score/total, and accuracy percentage.
Highlights the current player’s entry.
Refreshes dynamically after each game completion.
Admin Features:
Password-protected (default: “admin123” – change this!).
Upload files and generate quizzes with a button click.
Preview generated questions.
View and delete existing games.
Logout functionality.
Data Management:
Stores games, questions, and leaderboards in JSON files for persistence.
Uploads are saved to a local directory.
Ensures directories exist on startup.
The app runs locally or can be deployed to services like Streamlit Sharing or Heroku for sharing with others.
Why It’s Useful
This app solves a few real-world problems:
Education and Training: Teachers or trainers can upload lesson plans, agendas, or study guides and turn them into quizzes for students. It’s great for reinforcing knowledge without manual effort.
Team Building and Events: Use it for company trivia, conference recaps, or fun games based on event schedules.
Self-Learning: Individuals can quiz themselves on notes or data files.
Efficiency: Automates question generation, saving hours of work. The intelligent parsing handles messy real-world documents, like Excel agendas with columns for “Title,” “Speakers,” “Duration,” etc.
Engagement: Leaderboards add competition, making it more fun than static quizzes.
Customization: Easy to tweak for specific needs, like adding more file types or question varieties.
In short, it’s a quick way to gamify content from documents, useful for educators, event organizers, or anyone who deals with structured data.
Requirements
To run this app, you’ll need:
Python 3.8+: The app uses Python features like type hints and Pathlib.
Libraries (installed via pip):
streamlit: For the UI.
pandas: For handling Excel/CSV data.
openpyxl: For Excel file parsing.
python-docx: For Word documents.
json, os, datetime, pathlib, random, typing: Built-in, no install needed.
No external APIs or databases: Everything is local and file-based for simplicity.
Hardware: Runs on any machine with Python; low resource usage.
If deploying online, you’ll need a hosting service that supports Streamlit apps.
How to Implement and Customize
The code is modular and easy to extend. Here’s a high-level overview:
Core Classes:
QuizGenerator: Handles parsing different file types and generating questions. Each method (e.g., generate_from_excel) uses strategies like column detection or structured data inference.
GameManager: Creates, loads, and saves games as JSON.
LeaderboardManager: Manages scores, sorting, and persistence.
UI Functions:
admin_interface(): Handles file uploads, game creation, and management.
user_interface(): Manages gameplay, state (using Streamlit’s session_state), and leaderboard display.
main(): Sets up the app layout with tabs.
To customize:
Change ADMIN_PASSWORD at the top for security.
Add more question types (e.g., true/false) by extending QuizGenerator.
Support new file formats by adding methods like generate_from_pdf.
Style the UI with Streamlit’s themes or custom CSS.
For production, use a real database (e.g., SQLite) instead of JSON for scalability.
The full code is in QuizGame.py on the GitHub repo. Clone it and tweak as needed!
How to Set Up and Run
Follow these steps to get it running:
Clone the Repo:
git clone https://github.com/rod-trent/JunkDrawer.git
cd JunkDrawer/QuizBuilderInstall Dependencies: Create a virtual environment (optional but recommended):
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activateThen install:
pip install streamlit pandas openpyxl python-docxRun the App:
streamlit run QuizGame.pyThis launches a local server (usually at http://localhost:8501). Open it in your browser.
Create Your First Quiz:
Go to the “Admin Panel” tab.
Enter the password (default: “admin123”).
Upload a document (e.g., an Excel with questions/answers).
Give it a title and generate.
Switch to “Play Quiz” and start!
Deployment (Optional):
For sharing: Use Streamlit Community Cloud – just link your GitHub repo.
Or host on Heroku/AWS: Follow Streamlit’s deployment guides.
Note: Local file storage means deployments need persistent storage (e.g., via AWS S3).
Troubleshooting:
If questions aren’t generating, check your document structure (e.g., add “Question” and “Answer” columns).
Errors? Ensure file paths are correct and dependencies are installed.
Security and Best Practices
Change the Password: Hardcoded defaults are fine for local use, but update ADMIN_PASSWORD immediately.
File Handling: Uploads are saved locally; in production, validate/sanitize files to avoid issues.
Data Privacy: Leaderboards store names and scores – consider anonymizing if needed.
Limitations: Currently, all questions are multiple-choice; no timer or multiplayer yet, but easy to add!
Conclusion
This Interactive Quiz Game is a fun, practical project that showcases Streamlit’s power for building data-driven apps. Whether you’re teaching, training, or just having fun, it turns boring documents into engaging experiences. Grab the code from GitHub, try it out, and let me know what you think – fork it, improve it, or share your quizzes!
If you have questions or suggestions, drop a comment below or hit me up on X at Rogan's List dtrent. Happy quizzing!