thrilltrack-explorer/django/ADMIN_GUIDE.md

ThrillWiki Admin Interface Guide

Overview

The ThrillWiki admin interface uses Django Unfold, a modern, Tailwind CSS-based admin theme that provides a beautiful and intuitive user experience. This guide covers all features of the enhanced admin interface implemented in Phase 2C.

Table of Contents

1. Features
2. Accessing the Admin
3. Dashboard
4. Entity Management
5. Import/Export
6. Advanced Filtering
7. Bulk Actions
8. Geographic Features
9. Customization

---

Features

✨ Modern UI/UX

• Tailwind CSS-based design - Clean, modern interface
• Dark mode support - Automatic theme switching
• Responsive layout - Works on desktop, tablet, and mobile
• Material Design icons - Intuitive visual elements
• Custom green color scheme - Branded appearance

🎯 Enhanced Entity Management

• Inline editing - Edit related objects without leaving the page
• Visual indicators - Color-coded status badges and icons
• Smart search - Search across multiple fields
• Advanced filters - Dropdown filters for easy data navigation
• Autocomplete fields - Fast foreign key selection

📊 Dashboard Statistics

• Total entity counts (Parks, Rides, Companies, Models)
• Operating vs. total counts
• Recent additions (last 30 days)
• Top manufacturers by ride count
• Parks by type distribution

📥 Import/Export

• Multiple formats - CSV, Excel (XLS/XLSX), JSON, YAML
• Bulk operations - Import hundreds of records at once
• Data validation - Error checking during import
• Export filtered data - Export search results

🗺️ Geographic Features

• Dual-mode support - Works with both SQLite (lat/lng) and PostGIS
• Coordinate display - Visual representation of park locations
• Map widgets - Interactive maps for location editing (PostGIS mode)

---

Accessing the Admin

URL

http://localhost:8000/admin/

Creating a Superuser

If you don't have an admin account yet:

cd django
python manage.py createsuperuser

Follow the prompts to create your admin account.

Login

Navigate to /admin/ and log in with your superuser credentials.

---

Dashboard

The admin dashboard provides an at-a-glance view of your ThrillWiki data:

Statistics Displayed

1. Entity Counts

   • Total Parks
   • Total Rides
   • Total Companies
   • Total Ride Models

2. Operational Status

   • Operating Parks
   • Operating Rides
   • Total Roller Coasters

3. Recent Activity

   • Parks added in last 30 days
   • Rides added in last 30 days

4. Top Manufacturers

   • List of manufacturers by ride count

5. Parks by Type

   • Distribution chart of park types

Navigating from Dashboard

Use the sidebar navigation to access different sections:

• Dashboard - Overview and statistics
• Entities - Parks, Rides, Companies, Ride Models
• User Management - Users and Groups
• Content - Media and Moderation

---

Entity Management

Parks Admin

List View Features

• Visual indicators: Icon and emoji for park type
• Location display: City/Country with coordinates
• Status badges: Color-coded operational status
• Ride counts: Total rides and coaster count
• Operator links: Quick access to operating company

Detail View

• Geographic Location section: Latitude/longitude input with coordinate display
• Operator selection: Autocomplete field for company selection
• Inline rides: View and manage all rides in the park
• Date precision: Separate fields for dates and their precision levels
• Custom data: JSON field for additional attributes

Bulk Actions

• export_admin_action - Export selected parks
• activate_parks - Mark parks as operating
• close_parks - Mark parks as temporarily closed

Filters

• Park Type (dropdown)
• Status (dropdown)
• Operator (dropdown with search)
• Opening Date (range filter)
• Closing Date (range filter)

---

Rides Admin

List View Features

• Category icons: Visual ride category identification
• Status badges: Color-coded operational status
• Stats display: Height, Speed, Inversions at a glance
• Coaster badge: Special indicator for roller coasters
• Park link: Quick navigation to parent park

Detail View

• Classification section: Category, Type, Status
• Manufacturer & Model: Autocomplete fields with search
• Ride Statistics: Height, Speed, Length, Duration, Inversions, Capacity
• Auto-coaster detection: Automatically marks roller coasters
• Custom data: JSON field for additional attributes

Bulk Actions

• export_admin_action - Export selected rides
• activate_rides - Mark rides as operating
• close_rides - Mark rides as temporarily closed

Filters

• Ride Category (dropdown)
• Status (dropdown)
• Is Coaster (boolean)
• Park (dropdown with search)
• Manufacturer (dropdown with search)
• Opening Date (range)
• Height (numeric range)
• Speed (numeric range)

---

Companies Admin

List View Features

• Type icons: Manufacturer 🏭, Operator 🎡, Designer ✏️
• Type badges: Color-coded company type indicators
• Entity counts: Parks and rides associated
• Status indicator: Active (green) or Closed (red)
• Location display: Primary location

Detail View

• Company types: Multi-select for manufacturer, operator, designer
• History section: Founded/Closed dates with precision
• Inline parks: View all operated parks
• Statistics: Cached counts for performance

Bulk Actions

• export_admin_action - Export selected companies

Filters

• Company Types (dropdown)
• Founded Date (range)
• Closed Date (range)

---

Ride Models Admin

List View Features

• Model type icons: Visual identification (🎢, 🌊, 🎡, etc.)
• Manufacturer link: Quick access to manufacturer
• Typical specs: Height, Speed, Capacity summary
• Installation count: Number of installations worldwide

Detail View

• Manufacturer: Autocomplete field
• Typical Specifications: Standard specifications for the model
• Inline installations: List of all rides using this model

Bulk Actions

• export_admin_action - Export selected ride models

Filters

• Model Type (dropdown)
• Manufacturer (dropdown with search)
• Typical Height (numeric range)
• Typical Speed (numeric range)

---

Import/Export

Exporting Data

1. Navigate to the entity list view (e.g., Parks)
2. Optionally apply filters to narrow down data
3. Select records to export (or none for all)
4. Choose action: "Export"
5. Select format: CSV, Excel (XLS/XLSX), JSON, YAML, HTML
6. Click "Go"
7. Download the file

Importing Data

1. Navigate to the entity list view
2. Click "Import" button in the top right
3. Choose file format
4. Select your import file
5. Click "Submit"
6. Review import preview
7. Confirm import

Import File Format

CSV/Excel Requirements

• First row must be column headers
• Use field names from the model
• For foreign keys, use the related object's name
• Dates in ISO format (YYYY-MM-DD)

Example Company CSV

name,slug,location,company_types,founded_date,website
Intamin,intamin,"Schaan, Liechtenstein","[""manufacturer""]",1967-01-01,https://intamin.com
Cedar Fair,cedar-fair,"Sandusky, Ohio, USA","[""operator""]",1983-03-01,https://cedarfair.com

Example Park CSV

name,slug,park_type,status,latitude,longitude,operator,opening_date
Cedar Point,cedar-point,amusement_park,operating,41.4779,-82.6838,Cedar Fair,1870-01-01

Import Error Handling

If import fails:

1. Review error messages carefully
2. Check data formatting
3. Verify foreign key references exist
4. Ensure required fields are present
5. Fix issues and try again

---

Advanced Filtering

Filter Types

1. Dropdown Filters

• Single selection from predefined choices
• Examples: Park Type, Status, Ride Category

2. Related Dropdown Filters

• Dropdown with search for foreign keys
• Examples: Operator, Manufacturer, Park
• Supports autocomplete

3. Range Date Filters

• Filter by date range
• Includes "From" and "To" fields
• Examples: Opening Date, Closing Date

4. Range Numeric Filters

• Filter by numeric range
• Includes "Min" and "Max" fields
• Examples: Height, Speed, Capacity

5. Boolean Filters

• Yes/No/All options
• Example: Is Coaster

Combining Filters

Filters can be combined for precise queries:

Example: Find all operating roller coasters at Cedar Fair parks over 50m tall

1. Go to Rides admin
2. Set "Ride Category" = Roller Coaster
3. Set "Status" = Operating
4. Set "Park" = (search for Cedar Fair parks)
5. Set "Height Min" = 50

Search vs. Filters

• Search: Text-based search across multiple fields (name, description, etc.)
• Filters: Structured filtering by specific attributes
• Best Practice: Use filters to narrow down, then search within results

---

Bulk Actions

Available Actions

All Entities

• Export - Export selected records to file

Parks

• Activate Parks - Set status to "operating"
• Close Parks - Set status to "closed_temporarily"

Rides

• Activate Rides - Set status to "operating"
• Close Rides - Set status to "closed_temporarily"

How to Use Bulk Actions

1. Select records using checkboxes
2. Choose action from dropdown at bottom of list
3. Click "Go"
4. Confirm action if prompted
5. View success message

Tips

• Select all on page: Use checkbox in header row
• Select all in query: Click "Select all X items" link
• Bulk actions respect permissions
• Some actions cannot be undone

---

Geographic Features

SQLite Mode (Default for Local Development)

Fields Available:

• latitude - Decimal field for latitude (-90 to 90)
• longitude - Decimal field for longitude (-180 to 180)
• location - Text field for location name

Coordinate Display:

• Read-only field showing current coordinates
• Format: "Longitude: X.XXXXXX, Latitude: Y.YYYYYY"

Search:

• /api/v1/parks/nearby/ uses bounding box approximation

PostGIS Mode (Production)

Additional Features:

• location_point - PointField for geographic data
• Interactive map widget in admin
• Accurate distance calculations
• Optimized geographic queries

Setting Up PostGIS: See POSTGIS_SETUP.md for detailed instructions.

Entering Coordinates

1. Find coordinates using Google Maps or similar
2. Enter latitude in "Latitude" field
3. Enter longitude in "Longitude" field
4. Enter location name in "Location" field
5. Coordinates are automatically synced to location_point (PostGIS mode)

Coordinate Format:

• Latitude: -90.000000 to 90.000000
• Longitude: -180.000000 to 180.000000
• Use negative for South/West

---

Customization

Settings Configuration

The Unfold configuration is in config/settings/base.py:

UNFOLD = {
    "SITE_TITLE": "ThrillWiki Admin",
    "SITE_HEADER": "ThrillWiki Administration",
    "SITE_SYMBOL": "🎢",
    "SHOW_HISTORY": True,
    "SHOW_VIEW_ON_SITE": True,
    # ... more settings
}

Customizable Options

Branding

• SITE_TITLE - Browser title
• SITE_HEADER - Header text
• SITE_SYMBOL - Emoji or icon in header
• SITE_ICON - Logo image paths

Colors

• COLORS["primary"] - Primary color palette (currently green)
• Supports full Tailwind CSS color specification

Navigation

• SIDEBAR["navigation"] - Custom sidebar menu structure
• Can add custom links and sections

Adding Custom Dashboard Widgets

The dashboard callback is in apps/entities/admin.py:

def dashboard_callback(request, context):
    """Customize dashboard statistics."""
    # Add your custom statistics here
    context.update({
        'custom_stat': calculate_custom_stat(),
    })
    return context

Custom Admin Actions

Add custom actions to admin classes:

@admin.register(Park)
class ParkAdmin(ModelAdmin):
    actions = ['export_admin_action', 'custom_action']
    
    def custom_action(self, request, queryset):
        # Your custom logic here
        updated = queryset.update(some_field='value')
        self.message_user(request, f'{updated} records updated.')
    custom_action.short_description = 'Perform custom action'

---

Tips & Best Practices

Performance

1. Use filters before searching - Narrow down data set first
2. Use autocomplete fields - Faster than raw ID fields
3. Limit inline records - Use show_change_link for large datasets
4. Export in batches - For very large datasets

Data Quality

1. Use import validation - Preview before confirming
2. Verify foreign keys - Ensure related objects exist
3. Check date precision - Use appropriate precision levels
4. Review before bulk actions - Double-check selections

Navigation

1. Use breadcrumbs - Navigate back through hierarchy
2. Bookmark frequently used filters - Save time
3. Use keyboard shortcuts - Unfold supports many shortcuts
4. Search then filter - Or filter then search, depending on need

Security

1. Use strong passwords - For admin accounts
2. Enable 2FA - If available (django-otp configured)
3. Regular backups - Before major bulk operations
4. Audit changes - Review history in change log

---

Troubleshooting

Issue: Can't see Unfold theme

Solution:

cd django
python manage.py collectstatic --noinput

Issue: Import fails with validation errors

Solution:

• Check CSV formatting
• Verify column headers match field names
• Ensure required fields are present
• Check foreign key references exist

Issue: Geographic features not working

Solution:

• Verify latitude/longitude are valid decimals
• Check coordinate ranges (-90 to 90, -180 to 180)
• For PostGIS: Verify PostGIS is installed and configured

Issue: Filters not appearing

Solution:

• Clear browser cache
• Check admin class has list_filter defined
• Verify filter classes are imported
• Restart development server

Issue: Inline records not saving

Solution:

• Check form validation errors
• Verify required fields in inline
• Check permissions for related model
• Review browser console for JavaScript errors

---

Additional Resources

Documentation

• Django Unfold: https://unfoldadmin.com/
• django-import-export: https://django-import-export.readthedocs.io/
• Django Admin: https://docs.djangoproject.com/en/4.2/ref/contrib/admin/

ThrillWiki Docs

• API_GUIDE.md - REST API documentation
• POSTGIS_SETUP.md - Geographic features setup
• MIGRATION_PLAN.md - Database migration guide
• README.md - Project overview

---

Support

For issues or questions:

1. Check this guide first
2. Review Django Unfold documentation
3. Check project README.md
4. Review code comments in apps/entities/admin.py

---

Last Updated: Phase 2C Implementation
Version: 1.0
Admin Theme: Django Unfold 0.40.0