thrillwiki_django_no_react/docs/admin/base_classes.md

Admin Base Classes and Mixins

This document describes the base admin classes and mixins available for building standardized Django admin interfaces in ThrillWiki.

Overview

The admin infrastructure provides reusable components that ensure consistency, optimize performance, and reduce code duplication across all admin interfaces.

Base Classes

BaseModelAdmin

The foundational admin class that all model admins should inherit from.

from apps.core.admin import BaseModelAdmin

class MyModelAdmin(BaseModelAdmin):
    list_display = ['name', 'status', 'created_at']

Features:

• Consistent pagination (50 items per page)
• Optimized result count behavior
• Standard empty value display
• Save buttons at top of forms
• Filter preservation after saves

Mixins

QueryOptimizationMixin

Provides automatic query optimization to prevent N+1 queries.

from apps.core.admin import QueryOptimizationMixin, BaseModelAdmin

class RideAdmin(QueryOptimizationMixin, BaseModelAdmin):
    list_display = ['name', 'park', 'manufacturer']
    list_select_related = ['park', 'manufacturer']
    list_prefetch_related = ['reviews', 'photos']

Attributes:

• list_select_related: List of ForeignKey fields to select
• list_prefetch_related: List of related fields to prefetch

ReadOnlyAdminMixin

Disables add, change, and delete permissions for auto-generated data.

from apps.core.admin import ReadOnlyAdminMixin, BaseModelAdmin

class RankingAdmin(ReadOnlyAdminMixin, BaseModelAdmin):
    list_display = ['ride', 'rank', 'calculated_at']

Use cases:

• Rankings and leaderboards
• Audit logs and history
• Calculated statistics
• State transition logs

TimestampFieldsMixin

Provides standard handling for created_at and updated_at fields.

from apps.core.admin import TimestampFieldsMixin, BaseModelAdmin

class MyModelAdmin(TimestampFieldsMixin, BaseModelAdmin):
    fieldsets = [
        ('Basic Info', {'fields': ['name', 'description']}),
    ] + TimestampFieldsMixin.get_timestamp_fieldset()

Features:

• Automatically adds timestamp fields to readonly_fields
• Provides a collapsible fieldset for metadata

SlugFieldMixin

Configures automatic slug population from name field.

from apps.core.admin import SlugFieldMixin, BaseModelAdmin

class ParkAdmin(SlugFieldMixin, BaseModelAdmin):
    slug_source_field = 'name'  # Optional, defaults to 'name'

ExportActionMixin

Adds CSV and JSON export functionality.

from apps.core.admin import ExportActionMixin, BaseModelAdmin

class ParkAdmin(ExportActionMixin, BaseModelAdmin):
    export_fields = ['id', 'name', 'status', 'created_at']
    export_filename_prefix = 'parks'

Actions added:

• Export selected to CSV
• Export selected to JSON

BulkStatusChangeMixin

Provides bulk status change actions.

from apps.core.admin import BulkStatusChangeMixin, BaseModelAdmin

class RideAdmin(BulkStatusChangeMixin, BaseModelAdmin):
    status_field = 'status'
    status_choices = [
        ('active', 'Activate'),
        ('inactive', 'Deactivate'),
    ]

ModerationMixin

Adds moderation actions for user-generated content.

from apps.core.admin import ModerationMixin, BaseModelAdmin

class ReviewAdmin(ModerationMixin, BaseModelAdmin):
    moderation_status_field = 'moderation_status'
    moderated_by_field = 'moderated_by'
    moderated_at_field = 'moderated_at'

Actions added:

• Approve selected items
• Reject selected items

Combining Mixins

Mixins can be combined to create feature-rich admin classes:

from apps.core.admin import (
    BaseModelAdmin,
    QueryOptimizationMixin,
    ExportActionMixin,
    TimestampFieldsMixin,
    SlugFieldMixin,
)

class ParkAdmin(
    QueryOptimizationMixin,
    ExportActionMixin,
    TimestampFieldsMixin,
    SlugFieldMixin,
    BaseModelAdmin
):
    list_display = ['name', 'operator', 'status', 'created_at']
    list_select_related = ['operator', 'location']
    list_prefetch_related = ['areas', 'rides']
    export_fields = ['id', 'name', 'slug', 'status']

Best Practices

1. Always use BaseModelAdmin as the final parent class
2. List mixins before BaseModelAdmin in inheritance order
3. Define list_select_related for all ForeignKey fields in list_display
4. Use prefetch_related for reverse relations and M2M fields
5. Test query counts using Django Debug Toolbar
6. Add export_fields explicitly for control over exported data

Performance Targets

• List views: < 10 queries
• Change views: < 15 queries
• Page load time: < 500ms for 100 records