django-unfold-contrib 0.1.0rc6
Community contrib extensions for the Django Unfold admin theme
Requires Python: >=3.10
Keywords: admin, django, theme, unfold

# Django Unfold Contrib
Useful helpers to customize the [Django Unfold](https://unfoldadmin.com/) theme and make it compatible with several other common Django packages.

# Table Of Contents
- [Overview](#overview)
- [Features](#features)
- [Developer Setup](#developer-setup)

# Overview
A collection of useful customization for Django Unfold:

- [Improved admin list view tables on mobile](#improved-admin-mobile-list-table)
- Fix compatibility with: 
  - [django-object-actions](#django-object-actions)
  - [django-select2](#django-select2)
- Templates in the Django Unfold style for:
  - [django-allauth](#django-allauth)
  - [Custom admin pages](#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.


**Before:**  
![Unfold mobile tables by defailt](https://git.sr.ht/~catvec/django-unfold-contrib/blob/main/docs/mobile-table-before.png)

**After:**  
![Unfold mobile tables with this package's fix applied](https://git.sr.ht/~catvec/django-unfold-contrib/blob/main/docs/mobile-table-after.png)

To use:

1. Include the `unfold_contrib.mobile_table` app in your `INSTALLED_APPS`, **before** the `unfold` app:
   ```python
   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](https://github.com/crccheck/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:**  
![django-object-actions with unfold without the compatibility fix](https://git.sr.ht/~catvec/django-unfold-contrib/blob/main/docs/object-actions-before.png)

**After:**  
![django-object-actions with unfold and the compatibility fix](https://git.sr.ht/~catvec/django-unfold-contrib/blob/main/docs/object-actions-after.png)

To use:

1. Import and use the `@unfold_action` decorator on your action functions (no `INSTALLED_APPS` entry needed):
   ```python
   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](https://django-select2.readthedocs.io/en/latest/) package provides a nice multi-select widget. Without this compatibility fix the widget is not styled to match Unfold's dark theme.

**Before:**  
![django-select2 with unfold without the compatibility fix](https://git.sr.ht/~catvec/django-unfold-contrib/blob/main/docs/django-select2-before.png)

**After:**  
![django-select2 with unfold and the compatibility fix](https://git.sr.ht/~catvec/django-unfold-contrib/blob/main/docs/django-select2-after.png)

To use:

1. Include the `unfold_contrib.select2_dark` app in your `INSTALLED_APPS`

## Templates
### Django Allauth
The [django-allauth](https://docs.allauth.org/en/latest/) 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  
  ![django-allauth with unfold styled login page](https://git.sr.ht/~catvec/django-unfold-contrib/blob/main/docs/allauth-login-form.png)
- Inclusion of message displays on the login page (to see error messages about login info)  
  ![django-allauth login page with form error messages displayed](https://git.sr.ht/~catvec/django-unfold-contrib/blob/main/docs/allauth-login-form-messsages.png)
- Google branded login button above normal login form  
  ![django-allauth login page with Google branded login button](https://git.sr.ht/~catvec/django-unfold-contrib/blob/main/docs/allauth-login-google-button.png)
- 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):
   ```python
   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):
   ```python
   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: 
   ```html
   {% 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](#features) for how to use Django Contrib Actions in your own project.

## SourceHut Builds
This project uses [SourceHut](https://sourcehut.org/) 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:**  
  ```text
  [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.