Getting Started with ClassPulse

This guide will walk you through the setup, installation, and basic usage of ClassPulse, an interactive audience engagement tool.

Prerequisites

• Python 3.8 or higher
• pip (Python package installer)
• Basic familiarity with terminal/command line

Installation

1. Clone the repository

git clone <repository-url>
cd classpulse

1. Create a virtual environment

python3 -m venv venv

1. Activate the virtual environment

On macOS/Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

1. Install dependencies

pip install python-fasthtml

1. Run the application

python app.py

1. Access the application

Open your web browser and navigate to:

http://localhost:5002

Quick Start Guide

For Presenters

1. Login

2. Use the default admin credentials:

   • Username: admin
   • Password: admin123

3. Create a Session

4. From the dashboard, click "Create New Session"
5. Enter a name for your session (e.g., "Python Workshop", "Marketing Presentation")

6. Click "Create Session"

7. Add Questions

8. On the session management page, you'll see options to add different types of questions

9. Click the appropriate button for the question type you want to create:

   • "New Multiple Choice" for multiple-choice questions
   • "New Word Cloud" for word cloud questions
   • "New Rating Scale" for rating questions

10. Configure Your Questions

11. For Multiple Choice Questions:

    • Enter the question title
    • Add options (one per line)
    • Click "Create Question"

12. For Word Cloud Questions:

    • Enter the question title
    • Click "Create Question"

13. For Rating Scale Questions:

    • Enter the question title
    • Specify maximum rating value (default is 5)
    • Click "Create Question"

14. Activate Questions

15. Questions are active by default

16. You can toggle questions on/off using the "Toggle Status" button

17. Share Your Session

18. Note the 6-digit session code displayed on the session management page
19. Share this code with your audience

20. Alternatively, share the QR code which will be displayed on the session page

21. Present Mode

22. Click "Present Mode" to enter the presentation view
23. This view shows real-time results as participants respond

24. The session code and QR code are prominently displayed for easy joining

25. View Results

26. Click "Results" next to any question to view detailed response data

27. Data is visualized according to the question type:

    • Bar charts for multiple choice
    • Word clouds for word cloud questions
    • Bar charts for rating scales

28. Export Data

29. From the question results page, click "Export Results" to download the data as CSV
30. From the session management page, click "Export" to download all session data

For Audience Members

1. Join a Session
2. Navigate to the ClassPulse application (or dedicated join URL if provided)
3. Click "Join a session as audience" on the login page
4. Enter the 6-digit session code provided by the presenter
5. Click "Join"

6. Alternatively, scan the QR code if shown by the presenter

7. Answer Questions

8. You will see all active questions for the session

9. For each question type, the interface is slightly different:

10. Multiple Choice Questions:

    • Select your preferred option
    • Click "Submit Answer"

11. Word Cloud Questions:

    • Enter words or short phrases
    • Click "Submit Answer"

12. Rating Scale Questions:

    • Select a rating from the available options
    • Click "Submit Rating"

13. Confirmation

14. After submitting, you'll see a confirmation message
15. You can change your answers by submitting again if needed

Using Question Types Effectively

Multiple Choice Questions

Best for: - Gauging opinion on specific options - Testing knowledge with single correct answers - Polls with distinct choices

Tips: - Keep options clear and concise - Avoid overlap between options - Limit to 3-6 options for readability - Consider including an "Other" option when appropriate

Example:

Which programming language are you most comfortable with?
- Python
- JavaScript
- Java
- C/C++
- Other

Word Cloud Questions

Best for: - Gathering diverse text responses - Brainstorming sessions - Collecting feedback in the participants' own words

Tips: - Ask open-ended but focused questions - Encourage participants to use single words or short phrases - Let participants know multiple words create multiple entries - Include clear context in the question

Example:

What words would you use to describe today's workshop?

Rating Scale Questions

Best for: - Satisfaction surveys - Measuring agreement/disagreement - Numerical feedback

Tips: - Clearly define what the scale represents - Consider using a 5-point scale for most purposes - Adjust max rating to match your specific needs - Include the scale context in the question

Example:

How useful did you find today's content? (1 = Not at all useful, 5 = Extremely useful)

Best Practices for Effective Sessions

1. Prepare Questions in Advance
2. Create all your questions before the session starts
3. Test them to ensure they work as expected

4. Consider the flow of questions within your presentation

5. Introduce the Tool

6. Take a moment to explain how to join and participate
7. Demonstrate how to respond to each question type

8. Emphasize that responses are anonymous

9. Balance Question Types

10. Use multiple choice for specific, focused feedback
11. Use word clouds for creative, open-ended input

12. Use rating scales for quantifiable feedback

13. Timing Matters

14. Activate questions at appropriate moments during your presentation
15. Give sufficient time for responses (usually 30-60 seconds)

16. Deactivate questions when you're ready to move on

17. Discuss Results

18. Take time to acknowledge and discuss the results
19. Highlight interesting patterns or unexpected responses

20. Use the results to guide further discussion

21. Follow Up

22. Export session data for further analysis
23. Share results with participants if appropriate
24. Use insights to improve future sessions

Customizing ClassPulse

ClassPulse is designed to be extensible. Some common customizations:

1. Changing the Theme

2. Edit static/css/styles.css to customize colors and styling

3. Adding Question Types

4. See the Developer Guide for instructions on adding new question types

5. Custom Authentication

6. Modify utils/auth.py to integrate with your authentication system

7. Display Customizations

8. Adjust chart appearance in static/js/main.js
9. Modify layout templates in utils/components.py

Troubleshooting

Common Issues

Issue: Application won't start - Ensure Python 3.8+ is installed - Verify the virtual environment is activated - Check that you installed all dependencies - Make sure no other application is using port 5002

Issue: Can't log in - Default credentials are admin/admin123 - Check if the database file (classpulse.db) exists and isn't corrupted

Issue: Audience can't join session - Verify the session is active (toggle if needed) - Ensure the correct session code is being used - Check that the audience is using the correct URL

Issue: Real-time updates not working - Ensure WebSockets are supported in the browser - Check network connectivity - Verify that the presenter is in Present Mode

Issue: Charts not displaying - Ensure JavaScript is enabled in the browser - Check the browser console for errors - Verify that responses have been submitted

Next Steps

After getting familiar with the basic functionality, consider exploring:

1. Advanced Features
2. Explore the documentation on exporting and analyzing results

3. Try different question configurations for various scenarios

4. Development

5. Check the Developer Guide for information on extending the platform

6. Review the code structure to understand how components interact

7. Feedback

8. Use ClassPulse in real sessions and gather feedback
9. Contribute improvements to the project

For more detailed information, refer to other documentation: - API Reference - Architecture - Developer Guide - Data Flow - Technical Specification