unfold-admin_skill

Overview

This skill packages guidance and commands for building, configuring, and enhancing Django admin interfaces with the Unfold theme. It documents site-level configuration, ModelAdmin extensions, widgets, filters, inlines, dashboard components, and third-party integrations. Use it to replace the default Django admin with a modern Tailwind/HTMX/Alpine.js driven experience.

How this skill works

The skill inspects and guides configuration of the UNFOLD settings dict, replacement AdminSite usage, and registration of models using unfold.admin.ModelAdmin. It explains Unfold-specific ModelAdmin attributes, decorators (display/action), filter classes, widget overrides, inline variants, dataset and section patterns, dashboard components, and integration points for popular Django packages. It also covers template injection points and UI behaviors like conditional fields and paginated/tabs inlines.

When to use it

• You want a modern, responsive admin UI based on Tailwind CSS, HTMX, and Alpine.js.
• Customizing ModelAdmin behavior: list layout, actions, conditional fields, or reorderable rows.
• Replacing default filters/widgets with advanced Unfold filter and widget classes.
• Building admin dashboards with KPI cards, charts, or embedded datasets.
• Integrating styled wrappers for django-import-export, django-guardian, simple-history, or other packages.

Best practices

• Put 'unfold' before 'django.contrib.admin' in INSTALLED_APPS so Unfold overrides load first.
• Extend unfold.admin.ModelAdmin as a base to inherit Unfold styling and features.
• Use the UNFOLD settings dict for global branding, sidebar navigation, and dashboard callbacks.
• Prefer Unfold-provided filters and widgets for consistent UX; use list_filter_submit for input-based filters.
• Group complex forms into tabbed fieldsets and use conditional_fields for dynamic visibility.
• Register reusable dashboard components with register_component and keep heavy data ops in background tasks.

Example use cases

• Create a full-width changelist with KPI panels and right-side sections using list_sections and list_fullwidth.
• Add row and detail actions with @action decorators for approve/reject workflows and custom submit-line actions.
• Replace TextField widgets with a WYSIWYG and use UnfoldAdminImageFieldWidget for inline image previews.
• Embed related item listings inside change forms via BaseDataset subclasses and change_form_datasets.
• Build paginated, tabbed inlines for large collections using per_page, tab, and ordering_field on inline classes.