Django Admin Module

Django-CFG includes a revolutionary Pydantic-based admin system that transforms how you build Django admin interfaces. Say goodbye to verbose admin classes and hello to clean, declarative, type-safe configurations.

Overview

The Django Admin module provides:

Declarative Configuration - Define admin interfaces using Pydantic models
Type Safety - Full Pydantic 2.x validation and IDE autocomplete
Specialized Field Types - Pre-built field configs for common patterns (badges, currency, dates, users)
Automatic Display Methods - Auto-generated display methods with widgets
HTML Builder Utilities - self.html methods for custom displays
Computed Field Decorators - @computed_field for type-safe custom logic
Modern UI - Seamless Unfold integration with Material Design icons
Query Optimization - Built-in select_related/prefetch_related support
Zero Boilerplate - Minimal code, maximum functionality

Philosophy

Before: Traditional Django Admin

from django.contrib import admin

@admin.register(Payment)
class PaymentAdmin(admin.ModelAdmin):
    list_display = ['id', 'user', 'amount', 'status', 'created_at']
    list_filter = ['status', 'created_at']
    search_fields = ['user__username', 'user__email']

    # Lots of manual configuration...

After: Django-CFG Declarative Admin

from django.contrib import admin
from django_cfg.modules.django_admin import (
    AdminConfig, BadgeField, CurrencyField, DateTimeField, UserField,
)
from django_cfg.modules.django_admin.base import PydanticAdmin

# ✅ Clean, declarative configuration
payment_config = AdminConfig(
    model=Payment,
    select_related=["user"],  # Auto-applied to all queries

    list_display=["internal_payment_id", "user", "amount_usd", "status", "created_at"],

    # Auto-generates display methods with widgets
    display_fields=[
        BadgeField(
            name="internal_payment_id",
            variant="info",
            icon=Icons.RECEIPT
        ),
        UserField(name="user", header=True),  # User with avatar
        CurrencyField(name="amount_usd", currency="USD", precision=2),
        BadgeField(
            name="status",
            label_map={
                "pending": "warning",
                "completed": "success",
                "failed": "danger",
            }
        ),
        DateTimeField(name="created_at", ordering="created_at"),
    ],

    list_filter=["status", "created_at"],
    search_fields=["internal_payment_id", "user__username"],
)

@admin.register(Payment)
class PaymentAdmin(PydanticAdmin):
    """Type-safe, auto-configured admin with zero boilerplate."""
    config = payment_config

Key Features

1. Type-Safe Configuration

All configuration is validated at runtime using Pydantic 2.x:

config = AdminConfig(
    model=MyModel,
    list_display=["name", "status"],
    display_fields=[
        BadgeField(
            name="status",
            variant="primary",  # ✅ IDE autocomplete + validation
            icon=Icons.CHECK_CIRCLE  # ✅ 2234+ icons with autocomplete
        )
    ]
)

2. Specialized Field Types

Pre-built field configurations for common patterns - these automatically generate display methods:

display_fields=[
    # User with avatar
    UserField(name="user", header=True),

    # Formatted currency
    CurrencyField(name="price", currency="USD", precision=2),

    # Status badge with conditional colors
    BadgeField(
        name="status",
        label_map={"active": "success", "inactive": "secondary"}
    ),

    # Datetime with relative time
    DateTimeField(name="created_at", ordering="created_at"),
]

3. HTML Builder Utilities

For custom display methods, use self.html utilities:

@admin.register(Payment)
class PaymentAdmin(PydanticAdmin):
    config = payment_config

    def payment_details_display(self, obj):
        """Custom readonly field using self.html."""
        details = []

        # Badge with icon
        details.append(self.html.badge(
            f"Confirmations: {obj.confirmations_count}",
            variant="info",
            icon=Icons.CHECK_CIRCLE
        ))

        # Inline items with separator
        details.append(self.html.inline([
            self.html.span("Amount:", "font-semibold"),
            self.html.span(f"${obj.amount:.2f}", "")
        ], separator=" "))

        # Icon with text
        details.append(self.html.icon_text(Icons.RECEIPT, obj.internal_payment_id))

        return "<br>".join(details)

    payment_details_display.short_description = "Payment Details"

Available self.html Methods:

self.html.badge(text, variant="primary", icon=None)
    # Colored badge with optional Material icon

self.html.span(text, css_class="")
    # Wrapped text with CSS classes

self.html.inline(items, separator=" | ")
    # Join items horizontally

self.html.icon(icon_name, size="xs")
    # Material icon only

self.html.icon_text(icon_or_text, text, icon_size="xs", color=None)
    # Icon + text combination with optional color

self.html.colored_text(text, color=None)
    # Colored text without icon

self.html.link(url, text, css_class="", target="")
    # Clickable link

self.html.empty(text="—")
    # Empty placeholder

4. Computed Field Decorator

For custom display logic in list views, use @computed_field:

from django_cfg.modules.django_admin import computed_field, Icons

@admin.register(User)
class UserAdmin(PydanticAdmin):
    config = user_config

    @computed_field("Status", ordering="is_active")
    def status_display(self, obj):
        """Enhanced status with icons."""
        if obj.is_superuser:
            return self.html.badge("Superuser", variant="danger", icon=Icons.ADMIN_PANEL_SETTINGS)
        elif obj.is_staff:
            return self.html.badge("Staff", variant="warning", icon=Icons.SETTINGS)
        elif obj.is_active:
            return self.html.badge("Active", variant="success", icon=Icons.CHECK_CIRCLE)
        else:
            return self.html.badge("Inactive", variant="secondary", icon=Icons.CANCEL)

    @computed_field("Full Name")
    def full_name(self, obj):
        """Full name with badge."""
        name = obj.get_full_name()
        if not name:
            return self.html.badge("No name", variant="secondary", icon=Icons.PERSON)
        return self.html.badge(name, variant="primary", icon=Icons.PERSON)

5. Annotated Fields

For computed values from database aggregations:

from django.db.models import Count

config = AdminConfig(
    model=User,
    # Define annotations
    annotations={
        'transaction_count': Count('transactions'),
    },
)

@admin.register(User)
class UserAdmin(PydanticAdmin):
    config = config

    @annotated_field("Transactions", annotation_name="transaction_count")
    def transaction_display(self, obj):
        """Display transaction count from annotation."""
        count = getattr(obj, 'transaction_count', 0)
        if count == 0:
            return self.html.empty()
        return self.html.badge(f"{count} transactions", variant="info", icon=Icons.RECEIPT)

6. Material Design Icons

2234+ Material icons with full IDE autocomplete:

from django_cfg.modules.django_admin import Icons

Icons.CHECK_CIRCLE       # ✓
Icons.CANCEL             # ✗
Icons.RECEIPT            # Receipt
Icons.EMAIL              # Email
Icons.PERSON             # Person
Icons.ADMIN_PANEL_SETTINGS  # Admin
Icons.SHOPPING_CART      # Cart
Icons.CURRENCY_BITCOIN   # Bitcoin
Icons.BUSINESS           # Business
# ... 2234+ more icons

7. Query Optimization

Built-in database optimization - applied automatically:

config = AdminConfig(
    model=Order,

    # Auto-applied to all queries
    select_related=["user", "product"],
    prefetch_related=["items"],

    # Aggregate annotations
    annotations={
        'total_items': Count('items'),
        'total_amount': Sum('items__price'),
    },
)

Architecture

┌─────────────────────────────────────────┐
│         PydanticAdmin                    │
│  (Base class with config processing)    │
└────────────────┬────────────────────────┘
                 │
                 ├──> AdminConfig (Pydantic model)
                 │    ├── list_display
                 │    ├── display_fields []
                 │    ├── fieldsets []
                 │    ├── actions []
                 │    └── optimizations
                 │
                 ├──> Field Configs
                 │    ├── BadgeField → auto-generates display method
                 │    ├── CurrencyField → auto-generates display method
                 │    ├── DateTimeField → auto-generates display method
                 │    └── UserField → auto-generates display method
                 │
                 ├──> Custom Display Methods
                 │    ├── @computed_field → for list display
                 │    ├── @annotated_field → for aggregations
                 │    └── self.html → for readonly fields
                 │
                 └──> Widget Registry
                      ├── badge → render_badge()
                      ├── currency → render_currency()
                      └── datetime → render_datetime()

Integration with Unfold

The admin module is designed to work seamlessly with Django Unfold:

from django_cfg.modules.django_admin.base import PydanticAdmin

# PydanticAdmin inherits from:
# UnfoldImportExportModelAdmin
#   └─ ImportExportModelAdmin  # Import/Export functionality
#   └─ UnfoldModelAdmin        # Modern Unfold UI
#        └─ Django ModelAdmin

Always Unfold-Ready

Every admin class using PydanticAdmin automatically gets:

✅ Modern Unfold UI
✅ Material Design icons
✅ Import/Export support (optional)
✅ Responsive layout

Benefits

For Developers

Less Code - 60-80% reduction in admin boilerplate
Type Safety - Catch errors at configuration time, not runtime
Consistency - Standardized patterns across all admins
Maintainability - Declarative configs are easier to read and modify
IDE Support - Full autocomplete for all config options
Rich Utilities - self.html builder and Display utilities for complex formatting

For Teams

Faster Onboarding - New developers understand declarative configs faster
Code Reviews - Less code to review, more focus on logic
Standards - Built-in best practices and patterns
Documentation - Self-documenting configuration

For Projects

Performance - Built-in query optimization
UI/UX - Consistent, modern interface
Extensibility - Easy to add custom fields and actions
Future-Proof - Type-safe configurations evolve with your schema

Complete Example

from django.contrib import admin
from django_cfg.modules.django_admin import (
    AdminConfig, BadgeField, CurrencyField, DateTimeField,
    FieldsetConfig, Icons, UserField, computed_field,
)
from django_cfg.modules.django_admin.base import PydanticAdmin

# Declarative config
payment_config = AdminConfig(
    model=Payment,

    # Performance
    select_related=["user", "currency"],

    # List display
    list_display=["internal_payment_id", "user", "amount_usd", "status", "created_at"],

    # Auto-generated display methods
    display_fields=[
        BadgeField(name="internal_payment_id", variant="info", icon=Icons.RECEIPT),
        UserField(name="user", header=True),
        CurrencyField(name="amount_usd", currency="USD", precision=2),
        BadgeField(
            name="status",
            label_map={
                "pending": "warning",
                "completed": "success",
                "failed": "danger",
            }
        ),
        DateTimeField(name="created_at", ordering="created_at"),
    ],

    # Fieldsets
    fieldsets=[
        FieldsetConfig(title="Basic", fields=["id", "internal_payment_id", "user"]),
        FieldsetConfig(title="Payment", fields=["amount_usd", "currency", "status"]),
        FieldsetConfig(title="Details", fields=["payment_details_display"], collapsed=True),
    ],

    readonly_fields=["payment_details_display"],
    list_filter=["status", "created_at"],
    search_fields=["internal_payment_id", "user__username"],
)

@admin.register(Payment)
class PaymentAdmin(PydanticAdmin):
    config = payment_config

    # Custom readonly field using self.html
    def payment_details_display(self, obj):
        """Detailed payment info using self.html utilities."""
        details = []

        details.append(self.html.inline([
            self.html.span("Internal ID:", "font-semibold"),
            self.html.span(obj.internal_payment_id, "")
        ], separator=" "))

        if obj.transaction_hash:
            details.append(self.html.inline([
                self.html.span("Transaction:", "font-semibold"),
                self.html.link(obj.get_explorer_link(), obj.transaction_hash[:16] + "...", target="_blank")
            ], separator=" "))

        if obj.confirmations_count > 0:
            details.append(self.html.badge(
                f"{obj.confirmations_count} confirmations",
                variant="info",
                icon=Icons.CHECK_CIRCLE
            ))

        return "<br>".join(details)

    payment_details_display.short_description = "Payment Details"

Next Steps

Quick Start - Get started in 5 minutes
Field Types - Complete field reference
Configuration - AdminConfig options, decorators, utilities
Filters - Complete guide to filters and third-party integrations
Examples - Real-world examples

Key Concepts

Declarative fields (BadgeField, CurrencyField, etc.) auto-generate display methods
@computed_field decorator for custom list display logic
self.html utilities for custom readonly fields
Display utilities (UserDisplay, MoneyDisplay, DateTimeDisplay) for advanced formatting

Overview​

Philosophy​

Before: Traditional Django Admin​

After: Django-CFG Declarative Admin​

Key Features​

1. Type-Safe Configuration​

2. Specialized Field Types​

3. HTML Builder Utilities​

4. Computed Field Decorator​

5. Annotated Fields​

6. Material Design Icons​

7. Query Optimization​

Architecture​

Integration with Unfold​

Benefits​

For Developers​

For Teams​

For Projects​

Complete Example​

Next Steps​