django-lucus

Русский

django-lucus is a custom theme for Django’s built-in admin (django.contrib.admin): refreshed layout, bundled color schemes, and a multi-column dashboard on /admin/ by default (not the stock flat app list). You shape columns and links with LUCUS_DASHBOARD; leave it unset and Lucus builds columns from your registered apps. Install the lucus app. Admin URLs stay the same as in your project (often /admin/, from urls.py).

• Appearance: Lucus replaces the admin “chrome” templates and loads CSS in order: lucus/css/style.css → lucus-admin.css → the selected palette file lucus/css/schemes/<slug>.css.
• Navigation: Django’s default admin app sidebar is turned off (AdminSite.enable_nav_sidebar = False).
• Per signed-in user: chosen palette and light / dark / system appearance are stored in LucusAdminUiPreference.
• Nav inside the admin: with LUCUS_SIDE_DASHBOARD_NAV (on by default), pages other than the index get a side or off-canvas menu in the same spirit as the home dashboard.
• Lists and edit forms: bulk-action bars default to both above and below the changelist; save / delete controls on object forms can sit in a fixed bar at the bottom of the viewport. Project-wide toggles are LUCUS_ACTIONS_ON_TOP and LUCUS_ACTIONS_ON_BOTTOM in the settings table below; each ModelAdmin subclass can still override behavior the usual Django way.

Index: multi-column LUCUS_DASHBOARD cards; header — palette, appearance, optional site / language selectors, user menu.

Changelist: breadcrumbs, toolbar (pagination + search), bulk actions, results table, filter aside.

Change form: fieldsets; fixed bottom action bar (save / delete). Palette and appearance are per-user (LucusAdminUiPreference).

Requirements

• Python ≥ 3.10
• Django: >=5.2,<7 (pyproject.toml)

Install

pip install django-lucus

Setup

Add lucus to INSTALLED_APPS and place it above django.contrib.admin:

INSTALLED_APPS = [
    # ...
    "lucus",
    "django.contrib.admin",
]

If another installed app defines the same template path as Lucus, lucus must come before it in the list; otherwise Django will load the wrong template. A common case is Rosetta: Lucus ships lucus/templates/rosetta/…. If rosetta appears earlier, those pages won’t use Lucus’s wrappers.

Then:

python manage.py migrate lucus

In production, run collectstatic so lucus/static/ is served.

Settings

Palette / appearance: not in settings; stored per user. Slugs → lucus/static/lucus/css/schemes/<slug>.css. Context: lucus.theme.lucus_admin_extra_context via admin.site.each_context.

LUCUS_UI

LUCUS_UI = {
    "help_as_icon": True,
    "high_contrast_toggle": False,
    "clean_input_types": False,
}

With help_as_icon: True, inline ? help closes when you click outside the popover (Lucus JS on all admin pages).

Changelist pagehead actions

Lucus renders the changelist title row in admin/change_list.html (.lucus-changelist__pagehead). Extra controls belong there, not in the stock object-tools block (which Lucus leaves empty by default).

Without overriding templates: set a class attribute on your ModelAdmin:

POST actions render a small form with {% csrf_token %}. For layout next to links, you may add CSS class lucus-changelist__pagehead-form--contents on <form> (display: contents) when you inject markup via {% block object-tools-items %}.

Template hook: override {% block object-tools-items %} in admin/change_list.html (same row as “Add”, inside .lucus-changelist__pagehead-actions). Use class lucus-changelist__addlink on <a> / <button> for matching chrome.

class MyModelAdmin(admin.ModelAdmin):
    lucus_changelist_pagehead_actions = (
        {"label": "Export CSV", "method": "get", "urlname": "admin:myapp_mymodel_export"},
        {"label": "Rebuild", "method": "post", "urlname": "admin:myapp_mymodel_rebuild"},
        {"label": "Client action", "js_handler": "myPageheadHandler"},
    )

Run python manage.py migrate lucus so LucusAdminUiPreference exists; if the table is missing, Lucus still saves palette / appearance via cookies for POST /admin/lucus/save-ui/, but DB persistence needs the migration applied.

Sortable tabular inlines & placeholder inlines

1. Drag-sort rows — lucus.inlines.LucusSortableTabularInline or LucusSortableTabularInlineMixin + admin.TabularInline. sortable_field_name, optional sortable_excludes. Docstring: lucus/inlines.py.
2. Inline between fieldsets — fieldsets entry with fields: (), classes containing "placeholder" and inline wrapper id (<formset.prefix>-group, e.g. items_set-group).

Third-party CSS (lucus/static/lucus/css/third_party/)

No extra Python deps. Non-admin/base.html staff views: LUCUS_STAFF_THEME_PATH_PREFIXES + lucus.context_processors.staff_integrations_theme.

LUCUS_DASHBOARD

Context: lucus_dashboard_columns from get_dashboard_for_request. Section link: {"label", "url"} or {"label", "admin_urlname"}. Section omitted if no link resolves.

Layout: [{ "column"?: 1–4, "classes"?: str, "sections": [{ "title", "links": [...] }] }, …]. Same column merges sections; classes from first dict.

Groups: [{ "column", "title", "links"?: [...], "app_labels"?: set|list|tuple|frozenset }, …]. links then models from app_labels; duplicate URLs dropped. list/tuple app_labels preserves order; set uses get_app_list order.

LUCUS_DASHBOARD_APPEND_UNCOVERED: True → unreferenced apps to last column; False → configured only.

LUCUS_DASHBOARD = [
    {
        "column": 1,
        "classes": "lucus-dashboard__col lucus-grid__col lucus-grid__col--3 lucus-grid__col--md-6 lucus-grid__col--sm-12 lucus-grid__col--xs-12",
        "sections": [
            {
                "title": "Education",
                "links": [
                    {"label": "Instructors", "admin_urlname": "admin:academy_instructor_changelist"},
                    {"label": "Courses", "url": "/admin/academy/course/"},
                ],
            },
        ],
    },
]

LUCUS_DASHBOARD = [
    {"column": 1, "title": "Authorization", "app_labels": {"auth"}},
]

LUCUS_DASHBOARD = [
    {
        "column": 2,
        "title": "Auth",
        "links": [{"label": "Users", "admin_urlname": "admin:auth_user_changelist"}],
        "app_labels": ("auth",),
    },
]

Stylesheet order

lucus/css/style.css → lucus/css/lucus-admin.css → lucus/css/schemes/<slug>.css → LUCUS_EXTRA_STATIC_CSS. Admin widget/inline/action JS: django.contrib.admin.

Custom palette: static lucus/css/<slug>.css + extend lucus.theme.BUNDLED_COLOR_SCHEMES.

admin/change_list_results.html overridden: .text before .sortoptions inside .lucus-th-heading-inner (replaces stock float sort icon layout).

Tests

pip install -r requirements-dev.txt
pytest

Python modules

If you use the header site switcher and want request.site on each request to match that choice, register lucus.sites_panel.LucusAdminSiteMiddleware immediately after SessionMiddleware. Setup details are in the lucus.sites_panel module.

This repo includes an integration/ demo app and requirements-integration.txt; optional pip install -e ".[integration]". Use the root manage.py with core.settings; some demos expect sorl.thumbnail to be installed.