blowcomotion.org

Stores the codebase for the blowcomotion.org website

Live Site: https://blowcomotion.org

Template Demo: https://themewagon.github.io/Djoz/index.html

The templates for this codebase are derived from the Djoz theme

Project Structure

This is a Django + Wagtail CMS project with a hybrid app layout:

• blowcomotion — CMS core: Wagtail admin wiring, StreamField blocks, the public form pipeline, settings, root URLs, base templates, and all models (in blowcomotion/models/)
• gigs, attendance, charts, instruments, members — domain apps holding views, forms, URLs, templates, tests, and management commands for their domain

Models live centrally in blowcomotion/models/, not in the domain apps that use them. This is legacy from the #312 hybrid-app split: at the time, moving models into their own apps would have required SeparateDatabaseAndState migrations and Wagtail content-type surgery on live production data, for no real benefit (the domains are FK-entangled anyway). So gigs, attendance, charts, instruments, and members must not gain a models.py or migrations/ of their own — new models for those domains go in blowcomotion/models/.

Going forward, new apps for genuinely new domains are not bound by that constraint — since there's no existing production data to migrate around, a new domain app can define its own models.py and own its own tables like a normal Django app.

Installation

• Clone the repository

  git clone <repository-url>

• Navigate to the project directory

  cd blowcomotion.org

• Create a virtual environment

  python -m venv venv

• Activate the virtual environment

  Windows

  venv\Scripts\activate

  macOS/Linux

  source venv/bin/activate

• Install the required packages

  pip install -r requirements.txt

• Install isort for import sorting

  pip install isort

• Run database migrations

  python manage.py migrate

• Create a superuser account

  python manage.py createsuperuser

Development Tools

Pre-commit Hook for Import Sorting

This project includes a pre-commit git hook that automatically sorts Python imports using isort to maintain consistent code formatting.

Pre-commit Hook Features

• Automatic import sorting: Runs isort on all staged Python files before each commit
• Smart behavior: Only processes files that need changes and re-stages them
• User-friendly: Provides clear feedback and allows review of changes
• Django-optimized: Uses Django-specific import grouping and formatting rules

How It Works

1. When you run git commit, the hook automatically activates
2. It checks all staged .py files for import order issues
3. If issues are found, it fixes them and re-stages the files
4. The commit is paused to allow you to review the changes
5. Run git commit again to complete the commit with properly sorted imports

Configuration

The import sorting behavior is configured in pyproject.toml:

[tool.isort]
profile = "django"
multi_line_output = 3
include_trailing_comma = true
line_length = 88
known_first_party = "blowcomotion,search,website"
sections = ["FUTURE", "STDLIB", "THIRDPARTY", "DJANGO", "FIRSTPARTY", "LOCALFOLDER"]

Manual Usage

You can also run isort manually:

# Check if files need sorting
isort --check-only blowcomotion/

# Fix import order
isort blowcomotion/

Requirements

• isort must be installed: pip install isort
• The hook is automatically executable after cloning the repository

Development Workflow

With the pre-commit hook enabled, your typical development workflow becomes:

# Make changes to Python files
git add blowcomotion/views.py

# Attempt to commit
git commit -m "Update views"

# If imports need fixing, the hook will:
# 1. Automatically fix import order
# 2. Re-stage the fixed files
# 3. Display a message asking you to review and commit again

# Review the changes (optional)
git diff --cached

# Commit again (will succeed if no further issues)
git commit -m "Update views"

This ensures that all Python code follows consistent import formatting standards automatically.

Run the web app

• Start the development server python manage.py runserver
• Open your web browser and go to the homepage
• You can access the admin panel at http://localhost:8000/admin
• To stop the server, press Ctrl+C in the terminal

Testing

The project includes comprehensive unit tests for all major features.

Run all tests

python manage.py test

Run tests with deprecation warnings (useful before Django upgrades)

python -Wa manage.py test

Run specific test modules

# Test attendance functionality
python manage.py test blowcomotion.tests.test_attendance_views

# Test birthday features
python manage.py test blowcomotion.tests.test_birthday_views

# Test member model
python manage.py test blowcomotion.tests.test_member_model

Available test modules

• test_attendance_views.py - Attendance tracking views and forms
• test_attendance_commands.py - Attendance management commands
• test_birthday_views.py - Birthday display views
• test_birthday_command.py - Birthday email notification command
• test_member_model.py - Member model and instrument relationships
• test_chart_api.py - Chart library API endpoints
• test_sync_gigs_command.py - GigoGig API synchronization
• test_dump_data_view.py - Database export functionality
• test_export_charts_command.py - Chart export command
• test_export_library_instruments_command.py - Library instrument export
• test_fetch_embed_data.py - Video embed data fetching
• test_video_feed_block.py - Video feed block functionality
• test_recaptcha.py - reCAPTCHA validation
• test_member_signup_go3.py - Member signup and GO3 integration

Import data from the website to the local database

• Navigate to the live website admin data dump page

• Save the JSON file to your local machine

• Navigate to the project directory

  cd blowcomotion.org

• Import the data into the local database

  python manage.py loaddata <path_to_json_file>

• Log in to the admin panel at http://localhost:8000/admin to verify that the data has been imported successfully

• In Page Explorer, delete the default "Welcome to your new Wagtail site!" page if it still exists

• In Sites settings, set the localhost root page to the imported homepage

Production Deployment

When deploying to production, always run:

• python manage.py collectstatic - Collects all static files (CSS, JS, images) for production
• python manage.py migrate - Applies any new database migrations

Important: Run collectstatic after any changes to static files (CSS, JavaScript, images) to ensure they're available in production.

Features

Attendance Tracker

The attendance tracking system allows band leaders to record and manage attendance for rehearsals and performances with integrated gig management.

Key Features

• Section-based tracking: Record attendance by band section (Woodwinds, High Brass, etc.)
• Section-aware roster: Members default to their primary section, while additional instruments make them available (flagged) in those sections too
• Member and guest support: Track both band members and guests/visitors
• Instrument capture: Record the specific instrument each member played for that session
• Event types: Differentiate between rehearsals and performances
• Gig integration: Automatically fetch and select from confirmed gigs when recording performance attendance
• Smart gig selection: Gigs are filtered by date, band (Blowcomotion), and confirmation status
• Dynamic form behavior: Event type selection shows/hides relevant fields (gig selection for performances, notes for rehearsals)
• Comprehensive reporting: View attendance statistics and trends
• Admin management: Full CRUD operations for attendance records through Wagtail admin

Gig Integration (New Feature)

The attendance system now integrates with the GigoGig API to provide seamless gig selection:

• Automatic gig fetching: When "Performance" is selected, available gigs are loaded for the chosen date
• Real-time updates: Gig options update dynamically when the date changes
• Smart filtering: Only shows confirmed Blowcomotion gigs for the selected date
• Caching: Gig data is cached for 10 minutes to improve performance
• Fallback handling: Gracefully handles API errors and provides fallback options

How to Use

1. Recording Attendance: Access the attendance capture interface at /attendance/
2. Section Navigation: Select a band section to record attendance for that group
3. Date Selection: Choose the date for the attendance session
4. Event Type:
   • Select "Rehearsal" for practice sessions (shows notes field)
   • Select "Performance" for gigs (shows gig selection dropdown)
5. Gig Selection (Performances only): Choose from available confirmed gigs for the selected date
6. Member Selection: Check off members who attended
7. Instrument Choice: The instrument is automatically determined for each attendee based on the section being viewed and the member's instrument assignments (no manual selection required)
8. Guest Entry: Add names of guests/visitors (one per line)
9. Submit: Record attendance with automatic event information

Technical Features

• API Integration: Connects to GigoGig API for real-time gig data
• JavaScript Enhancement: Dynamic form behavior with HTMX for seamless user experience
• Caching Strategy: Intelligent caching to reduce API calls and improve performance
• Error Handling: Robust error handling for network issues and API failures

Admin Management

• Navigate to Wagtail Admin > Band Stuff > Attendance Records
• View, edit, and delete attendance records
• Filter by date, member, or search notes
• Export data for external analysis
• View gig information in attendance notes

Security

• Protected by HTTP Basic Authentication
• Password configurable through Wagtail Admin > Settings > Site Settings > Access Control

Birthdays Function

The birthdays feature displays upcoming band member birthdays to help celebrate and recognize members.

Birthday Features

• Upcoming birthdays: Shows members with birthdays in the current month
• Privacy-aware: Only displays month/day, respects member privacy
• Mobile-friendly: Responsive design for all devices
• Admin integration: Birthday data managed through member profiles

How to Access

1. Access: Navigate to /birthdays/ to view the birthdays page
2. Display: Shows members with birthdays in the current month
3. Information: Displays member name, birthday (month/day), and photo if available

Birthday Admin Management

• Member Profiles: Add birthday information in Wagtail Admin > Band Stuff > Members
• Fields: birth_month, birth_day, and optional birth_year
• Privacy: Birth year is optional and not displayed publicly

Birthday Security

• Protected by HTTP Basic Authentication
• Password configurable through Wagtail Admin > Settings > Site Settings > Access Control

Environment Variables

The following environment variables can be configured:

• GIGO_API_URL - API endpoint for GIGO integration (default: http://localhost:8000/api)
• GIGO_API_KEY - API key for GIGO integration (required for gig features)

GigoGig API Integration

The attendance system integrates with the GigoGig API to fetch gig information:

API Endpoints Used

• GET /gigs - Fetches all gigs, filtered client-side for date/band/status
• GET /gigs/{id} - Fetches specific gig details (used for attendance notes)

API Configuration

1. Set the GIGO_API_URL environment variable to your GigoGig API base URL
2. Set the GIGO_API_KEY environment variable with your API key
3. The system will automatically fetch gigs when recording performance attendance

Local API Endpoint

The application also provides a local API endpoint for gig data:

• GET /attendance/gigs-for-date/?date=YYYY-MM-DD - Returns filtered gigs for a specific date

This endpoint is used by the JavaScript frontend and includes caching for performance.

Admin Configuration

Site settings, including access control passwords, are configured through the Wagtail admin interface:

1. Access Wagtail Admin > Settings > Site Settings
2. Configure passwords in the Access Control section
3. Set email recipients for forms in the Form Email Recipients section
4. Update donation links in the Donation Links section
5. Manage social media links and site branding

Recent Changes

Member Model Refactoring (October 2025)

The Member model was refactored to improve instrument management and section assignment. See MEMBER_MODEL_REFACTOR.md for complete details.

Key changes:

• Split instruments into primary_instrument (single) and additional_instruments (multiple)
• Members appear in their primary section by default, with additional instruments surfaced (and flagged as "Additional") in the relevant sections for quick access during attendance
• Migration 0076 automatically converted existing data
• Admin search uses Django queries instead of Wagtail FTS for better SQLite compatibility

Breaking changes:

• Attendance views now filter by primary_instrument instead of many-to-many instruments
• Templates display member.primary_instrument instead of looping through member.instruments.all
• Forms require setting primary instrument for proper section assignment