 |
Summary | A theme component that transforms private messages with an AI bot into an interactive quiz experience. |
 |
Repository | GitHub - VaperinaDEV/discourse-quizmaster: A theme component that transforms private messages with an AI bot into an interactive quiz experience. |
 |
Install Guide | How to install a theme or theme component |
 |
New to Discourse Themes? | Beginner’s guide to using Discourse Themes |
Install this theme component
Interactive Quiz Theme Component
Hello 
I’ve created a theme component that transforms private messages with an AI bot into an interactive quiz experience. The component automatically formats quiz questions, handles answer submission, tracks progress, and manages quiz completion with a convenient header dropdown for quick quiz initiation.
Features
1. Header Dropdown Quiz Launcher
A customizable dropdown button in the site header provides quick access to different quiz types:
- Fully configurable via theme settings using object schema
- Multi-language support with i18n integration for labels, descriptions, and messages
- Customizable icons for each quiz difficulty level
- Default options include: Easy, Normal, Hard, and Mixed difficulty quizzes
- Each option sends a pre-configured message to the AI bot to start the quiz
2. Automatic Quiz Question Formatting
The component detects and formats multiple-choice questions from the AI bot’s posts. When the bot posts a list starting with “A)”, “B)”, etc., these are automatically converted into clickable quiz options with custom styling.
3. One-Click Answer Submission
Users can click directly on answer options (A, B, C, D) to submit their response. The component:
- Prevents duplicate submissions with a loading state
- Automatically replies to the correct post
- Formats answers consistently (e.g., “My answer: A) Option text”)
- Provides error handling with user feedback
4. Question Counter
A progress indicator appears on each quiz question showing:
- Current question number vs. maximum allowed
- Customizable maximum questions (default: 50)
- Only visible on the AI bot’s posts
5. Automatic Quiz Termination
The component includes intelligent quiz management:
- Milestone checkpoints: Shows a “Terminate Quiz” button every 10 questions (after question 11, 21, 31, etc.)
- Hard limit enforcement: Automatically sends a termination message when reaching the maximum question count
- Duplicate prevention: Tracks termination state to prevent multiple termination posts
- Validation checks: Ensures termination only happens when appropriate
6. UI Modifications
When in a quiz conversation:
- Removes AI retry/share buttons from bot posts (non-admins)
- Removes reply button from bot posts in private messages
- Prevents quiz creators from deleting their own posts (preserves quiz history)
- Adds custom CSS body class
is-quiz-chatfor styling
Configuration
The component uses these theme settings:
# Quiz behavior settings
quizmaster_username: "YourBotUsername" # The AI bot's username
show_for_groups: "" # Header dropdown show for groups
quiz_max_questions: 50 # Maximum questions before auto-termination
# Header button settings
button_icon: "question-circle" # Icon for the main quiz button
# Dropdown quiz options (object schema) max 4
dropdown_items:
type: objects
default:
- label_template: quiz_easy_label
description_template: quiz_easy_description
icon: star
message_template: quizmaster_input_easy
- label_template: quiz_normal_label
description_template: quiz_normal_description
icon: star-half-alt
message_template: quizmaster_input_normal
- label_template: quiz_hard_label
description_template: quiz_hard_description
icon: certificate
message_template: quizmaster_input_hard
- label_template: quiz_mixed_label
description_template: quiz_mixed_description
icon: random
message_template: quizmaster_input_mixed
schema:
properties:
label_template:
type: string
description_template:
type: string
icon:
type: string
message_template:
type: string
svg_icons:
default: "far-star-half"
type: list
list_type: "compact"
description: "List of FontAwesome 6 icons used in this theme component"
Translation Keys
Add these to your theme’s locale files for full i18n support:
English (en.yml)
en:
js:
# Header button
quiz: "Quiz"
# Dropdown labels
quiz_easy_label: "Easy Quiz"
quiz_normal_label: "Normal Quiz"
quiz_hard_label: "Hard Quiz"
quiz_mixed_label: "Mixed Quiz"
# Dropdown descriptions
quiz_easy_description: "Basic questions for beginners"
quiz_normal_description: "Average difficulty questions"
quiz_hard_description: "Advanced level challenge"
quiz_mixed_description: "Random difficulty questions"
# Message templates
quizmaster_input_easy: "Give me an easy quiz question"
quizmaster_input_normal: "Give me a normal difficulty quiz question"
quizmaster_input_hard: "Give me a hard quiz question"
quizmaster_input_mixed: "Give me a mixed difficulty quiz question"
# Quiz interaction
my_answer: "My answer to the question is:"
terminate_quiz: "Thanks for the game, I'd like a summary!"
max_questions_text: "questions (or until my source runs dry). Every 10, you choose: stay or venture on."
Use Cases
This component is perfect for:
- Educational quizzes with AI tutors
- Training assessments
- Knowledge testing
- Interactive learning experiences
- Gamified content delivery
- Language learning applications
- Certification prep courses
The component handles all the complexity of tracking state, preventing errors, and managing the quiz lifecycle automatically, providing a smooth experience for both quiz creators and participants. The header dropdown makes it incredibly easy for users to start quizzes.
Customization
Administrators can easily customize the quiz experience by:
- Modifying quiz difficulty labels and descriptions in locale files
- Adding new language translations
- Changing icons for different quiz types
- Adjusting the message templates sent to the AI bot
- Configuring which user groups see the header button
- Setting maximum question limits
All customizations are done through the admin interface without touching any code.
AI System Prompt
The component works seamlessly with AI bots by detecting a simple list format. Here’s an example system prompt for your mystical AI bot (customize as needed):
You are the strict but fair professional mystical Quizmaster. Speak with authority but helpfulness, as if you were a modern wizard. Use some magic-related phrases (e.g. 'Let's see what lies in the mist of your knowledge...'), but stick to the technical facts.
### QUIZ DIFFICULTY LEVELS (MODES)
The user will initiate the conversation by specifying a difficulty level. Use the following guidelines to calibrate the depth of your questions:
1. **Easy:**
[Your easy mode criteria here]
2. **Normal:**
[Your normal mode criteria here]
3. **Hard:**
[Your hard mode criteria here]
4. **Mixed:** Randomly select a difficulty and a category for every question.
---
### DYNAMIC RESPONSE LOGIC
**INSTRUCTION:** For every new question, pick a different Category (A-E) than the previous 5 questions.
- **VARIETY RULES:** Never repeat a question or its topic within the same session.
- **LEVEL-UP SUGGESTION:** After every 10-question milestone, if the user has a 100% success rate on Easy or Normal, suggest moving to the next level within the evaluation block.
### CORE RULES:
1. **Continuous Flow:** After evaluating an answer, immediately provide the next question in the SAME message.
2. **Terminating the game:**
* If the user writes: "Thanks for playing, I'd like a summary!", stop immediately.
* Provide a final evaluation based ONLY on answered questions.
* Provide the final score and a mystical goodbye.
3. **SINGLE OUTPUT:** **CRITICAL: Provide the evaluation, the current score, and the NEXT question exactly ONCE. Do not repeat the question or the options list within the same response.**
### RESPONSE STRUCTURE & FORMATTING (MANDATORY):
> [Correct/Incorrect emoji] **[Brief explanation of the previous answer.]**
*Current Score: [X] points*
---
### [Next Question text goes here]
* A) [OPTION_A_TEXT]
* B) [OPTION_B_TEXT]
* C) [OPTION_C_TEXT]
* D) [OPTION_D_TEXT]
---
### AUTOMATION RULES (FOR THE AI):
- **NO WRAP TAGS:** Do not use `[wrap]` tags or any special Discourse syntax for buttons.
- **STRICT LIST FORMAT:** You MUST provide the four options as a simple bulleted list exactly as shown above, starting with "A)", "B)", "C)", and "D)".
- **SYSTEM INTEGRATION:** The external system will automatically detect your A-D list and convert it into interactive buttons. Do not attempt to style the buttons yourself.
### CONSTRAINTS:
- **Language Consistency:** Always respond in the same language the user used.
- The explanation must be inside a blockquote (>).
Note: We initially tried using [wrap] tags to create buttons, but the AI sometimes missed the closing ], breaking the functionality. The simple bulleted list format (* A), * B), etc.) is much more reliable and nearly impossible for the AI to get wrong. The theme component automatically detects this format and converts it into interactive buttons.
I would truly love to hear about your use case. Please share!