django-admin-js 1.0.2

A modern Django Admin experience built with Tailwind CSS and progressive JavaScript enhancements.

DjangoAdmin.JS

A modern, responsive, and gorgeous Django Admin experience built with Tailwind CSS and progressive JavaScript enhancements. Features a beautifully redesigned UI, customizable graphic styles (glassmorphism/minimalist), seamless AJAX page loads (no full page reloads), asynchronous form actions, and a Spotlight-like interactive Command Palette.

👉 Launch the Live Interactive Demo Page to experience it directly in your browser!

---

✨ Features & Capabilities

• 🎨 Tailwind CSS Driven & Modern UI: Sleek premium aesthetics with responsive layouts for mobile, tablet, and desktop viewports.
• 🌗 Dark Mode Support: Built-in support for dark themes with instant toggles and settings syncing.
• ⚡ Seamless AJAX Navigation (PJAX): Instant search, pagination, and sorting filtering without page reloads.
• 📩 Asynchronous Forms & Actions: Non-blocking form submissions and delete actions, with inline validation error styling and success toast notifications.
• ⚙️ Unified Configuration Settings: Easily configure global settings, default layout styles, and colors in settings.py.
• 🎭 Dynamic Layout Presets:
  • default: Clean rounded cards with soft shadows.
  • glassmorphism: Frosty translucent glass panels with real-time backdrop blur.
  • minimalist: High-contrast, borders-first layout with focused input outlines.
• 🔍 Raycast/Spotlight Command Palette (Ctrl+K / Cmd+K): Live search bar with instant actions, styled command triggers (e.g. /style glassmorphism, /color emerald, /mode dark), and quick view routes.

---

🚀 Quick Start

1. Installation

Install via pip from PyPI:

pip install django-admin-js

2. Configuration

Add django_admin_js to your INSTALLED_APPS before django.contrib.admin:

INSTALLED_APPS = [
    "django_admin_js",  # Must be before admin
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # ... your apps
]

Add DjangoAdminJSMiddleware to the beginning of your MIDDLEWARE list to capture AJAX exception tracebacks and display them inside toasts:

MIDDLEWARE = [
    "django_admin_js.middleware.DjangoAdminJSMiddleware",  # Add at the top
    "django.middleware.security.SecurityMiddleware",
    # ... other middlewares
]

3. Customization Options (Optional)

You can customize behaviors, visual styles, and color themes of DjangoAdmin.JS by adding the DJANGO_ADMIN_JS settings dictionary in your settings.py:

DJANGO_ADMIN_JS = {
    # Error display level on AJAX failure. Options:
    # - "generic": Shows a generic 500 error toast
    # - "title": Shows only the exception message string in the toast (default)
    # - "stacktrace": Shows both the exception message and the scrollable stacktrace inside the toast
    "ERROR_LEVEL": "title",

    # Enable/Disable Live Search (As-You-Type instant filtering in list views)
    "LIVE_SEARCH": True,

    # Minimum characters required to trigger live search (defaults to 3)
    "LIVE_SEARCH_MIN_CHARS": 3,

    # Debounce delay in milliseconds before triggering search (defaults to 300)
    "LIVE_SEARCH_DEBOUNCE_MS": 300,

    # Enable/Disable the Header Theme & Layout Switcher popover widget
    "THEME_PICKER": True,

    # Enable/Disable the Header Language Switcher widget (defaults to False)
    # Note: Requires i18n URL patterns path("i18n/", include("django.conf.urls.i18n")) to be defined in urls.py
    "LANGUAGE_SWITCHER": True,

    # List of languages available in the switcher (defaults to settings.LANGUAGES)
    # Each language is a tuple: (code, name, optional_icon_class_or_emoji)
    # Supports FontAwesome classes (e.g. "fa-solid fa-globe") and flag-icons (e.g. "fi fi-it")
    "LANGUAGES": [
        ("it", "Italiano", "fi fi-it"),
        ("en", "English", "fi fi-gb"),
        ("es", "Español", "fi fi-es"),
    ],

    # Initial color theme preset (defaults to "indigo" if not specified)
    # Built-in presets: "indigo", "emerald", "amber", "rose", "violet", "ocean"
    "DEFAULT_THEME": "indigo",

    # Initial graphic layout style 
    # Options: "default", "glassmorphism", "minimalist"
    "THEME_STYLE": "default",

    # Enable/Disable Collapsible Sidebar sections for each application (defaults to True)
    "SIDEBAR_COLLAPSIBLE": True,

    # Initial collapse state of sidebar app sections (defaults to False)
    "SIDEBAR_COLLAPSED_DEFAULT": False,

    # Enable/Disable Client-Side AJAX SPA Routing (defaults to False).
    # Useful when using third-party JavaScript widgets/plugins that require full DOM reloads
    # to re-initialize scripts (e.g. CKEditor, TinyMCE, custom complex JS widgets).
    "DISABLE_CLIENT_ROUTING": False,

    # Custom text for the admin header branding (defaults to Django administration)
    "SITE_HEADER": "My Custom Admin",

    # Custom URL or path for the admin header and login logo
    "SITE_LOGO": "/static/my_app/logo.png",

    # Custom links to show in the sidebar.
    # If the key matches an existing app label (e.g. "auth"), links are appended to that app.
    # Otherwise, a brand new app section is created in the sidebar.
    "CUSTOM_LINKS": {
        "store": [
            {
                "name": "Custom Report",
                "url": "/admin/custom-report/",
                "icon": "fa-solid fa-chart-line",
            }
        ],
        "external_tools": [
            {
                "name": "Google",
                "url": "https://google.com",
                "icon": "fa-brands fa-google",
            }
        ]
    },

    # Map models/apps to icons.
    # Supports FontAwesome classes (FontAwesome 6.4.0 is bundled),
    # Heroicon keywords ("user", "users", "group", "site", "cog", "database", "key", "shield", "tag", "folder"),
    # or direct custom raw HTML/SVG.
    "MODEL_ICONS": {
        "auth.user": "fa-solid fa-user-shield",
        "auth.group": "fa-solid fa-users-gear",
        "management.teammember": "fa-solid fa-user-tie",
        "management.project": "fa-solid fa-diagram-project",
        "store.product": "fa-solid fa-box-open",
        # Case-insensitive, supports either <app_label>.<model_name> or just <model_name>
    },

    # Custom Model Actions (rendered as buttons on the opposite side of default list actions)
    "CUSTOM_MODEL_ACTIONS": {
        "store.order": [
            {
                "name": "Export Report",
                "url": "/admin/store/order/export/",
                "icon": "fa-solid fa-file-export",
                "class": "bg-indigo-600 hover:bg-indigo-700 text-white border-transparent", # Optional CSS classes
                "target": "_blank", # Optional target attribute
            }
        ]
    }
}

💻 Client-side JavaScript API

DjangoAdmin.JS exposes a global utility helper class DjangoAdminJS on the window object to allow developer interaction within custom views or Django admin pages:

Show Alerts (Toasts)

You can programmatically trigger a toast notification from your JavaScript code:

// Show a warning alert
DjangoAdminJS.showAlert("Attenzione, operazione non consentita!", DjangoAdminJS.ALERT_SEVERITY.WARN);

API Signature

DjangoAdminJS.showAlert(message, severity, duration = 5000);

Available Severities (DjangoAdminJS.ALERT_SEVERITY)

• DjangoAdminJS.ALERT_SEVERITY.INFO (Default)
• DjangoAdminJS.ALERT_SEVERITY.SUCCESS
• DjangoAdminJS.ALERT_SEVERITY.WARN
• DjangoAdminJS.ALERT_SEVERITY.ERROR

---

📊 Compatibility

• Django: 5.0, 5.1, 5.2+
• Python: 3.10, 3.11, 3.12+

---

🛠 Local Development & Demo

To test and develop django-admin-js locally, you can use the self-contained example project. It comes pre-configured with django-browser-reload to automatically refresh your browser whenever you modify the templates or static files in django_admin_js.

1. Set up the environment

Create a virtual environment and install the package in editable mode along with development requirements:

python3 -m venv .venv
source .venv/bin/activate
pip install -e . django-browser-reload

2. Run the Demo Project

Navigate to the example directory, apply migrations, and start the development server:

cd example
python manage.py migrate
python manage.py runserver

3. Log In to Admin

Open http://127.0.0.1:8000/admin/ in your browser and log in with the pre-created admin user:

• Username: admin
• Password: admin

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.