django-unfold-contrib 0.1.0rc5

Community contrib extensions for the Django Unfold admin theme

Django Unfold Contrib

Useful helpers to customize the Django Unfold theme and make it compatible with several other common Django packages.

Table Of Contents

• Overview
• Features
• Developer Setup

Overview

A collection of useful customization for Django Unfold:

• Improved admin list view tables on mobile
• Fix compatibility with:
  • django-object-actions
  • django-select2
• Templates in the Django Unfold style for:
  • django-allauth
  • Custom admin pages

Features

Improved Admin Mobile List Table

Unfold's admin list view converts the model list to a series of cards on mobile, which can be hard to read and navigate. This addon provides a CSS override that keeps the table layout on all screen sizes with horizontal scrolling support.

To use:

1. Include the unfold_contrib.mobile_table app in your INSTALLED_APPS, before the unfold app:

   INSTALLED_APPS = [
       # ...
       "unfold_contrib.mobile_table",  # Must come before unfold
       "unfold",
       # ...
   ]
   

   The app order is important because Django's template loader uses the first matching template it finds. If unfold_contrib.mobile_table is listed after unfold, the Unfold template will be used instead.

Compatibility Fixes

Django Object Actions

The django-object-actions package allows you to put Django admin actions on the change page of an individual model. Without this compatibility fix object actions are not correctly styled or positioned in the header.

Before:

After:

To use:

1. Import and use the @unfold_action decorator on your action functions (no INSTALLED_APPS entry needed):

   from unfold_contrib.actions import unfold_action
   
   class MyModelAdmin(DjangoObjectActions, admin.ModelAdmin):
       # ...
       change_actions = ["foobar"]
       
       @unfold_action(label="Foo Bar")
       def foobar(self, request, obj):
           # ...
   

Django Select2

The django-select2 package provides a nice multi-select widget. Without this compatibility fix the widget is not styled to match Unfold's dark theme.

Before:

After:

To use:

1. Include the unfold_contrib.select2_dark app in your INSTALLED_APPS

Templates

Django Allauth

The django-allauth package provides comprehensive user login and 3rd party login features. Included in Django Unfold Contrib are:

• Base themes for django-allauth which match the Django Unfold styling
  
• Inclusion of message displays on the login page (to see error messages about login info)
  
• Google branded login button above normal login form
  
• Logout view which clears messages

To use:

1. Include the unfold_contrib.allauth app in your INSTALLED_APPS
2. To show the Google Sign-In button on the admin login page, set the following in your settings.py (it is disabled by default):

   UNFOLD_CONTRIB_GOOGLE_AUTH_ENABLED = True
   

3. If you want the custom logout view also add the unfold_contrib.allauth.urls to your urls.py file (place it after allauth's URLs to override properly):

   from django.contrib import admin
   from django.urls import path, include
   
   urlpatterns = [
       path("admin/", admin.site.urls),
       path("accounts/", include("allauth.urls")), # required for allauth
       path("accounts/", include("unfold_contrib.allauth.urls")), # for clean logout
   ]
   

Custom Admin Pages

Provides a base template which you can use to make custom Django admin pages in the Unfold styling.

To use:

1. Include the unfold_contrib.custom_admin_pages app in your INSTALLED_APPS
2. Extend unfold_contrib/base_admin_page.html in your custom admin template, override the content block:

   {% extends 'unfold_contrib/base_admin_page.html' %}
   
   {% block content %}
       <h1>My Custom Admin Page</h1>
       <p>This is a custom page that uses the Unfold branding and includes jQuery.</p>
   {% endblock %}
   

Developer Setup

Instructions for developers of the Django Unfold Contrib package. See Features for how to use Django Contrib Actions in your own project.

SourceHut Builds

This project uses SourceHut for continuous integration and publishing. The .build.yml file defines the build process.

To give the build job permissions to push to PyPi setup a secret:

• Name: pypi-django-unfold-contrib
• Secret:

  [main]
    username = __token__
    password = <TOKEN HERE, UNQUOTED>
  

  In is important the section in the config file be named [main] for Hatch to work properly.
  Replace <TOKEN HERE, UNQUOTED> with the PyPi API token (not in quotes) authorized for the django-unfold-contrib package.
• Path: ~/.pypirc
• Mode: 600

Place the secret UUID in the build config file.