django-unfold 0.12.0__tar.gz → 0.13.0__tar.gz

{django_unfold-0.12.0 → django_unfold-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-unfold
-Version: 0.12.0
+Version: 0.13.0
 Summary: Clean & minimal Django admin theme based on Tailwind CSS
 Home-page: https://unfoldadmin.com
 License: MIT
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: django (>=3.2)
 Requires-Dist: importlib-metadata (==6.7.0)
 Project-URL: Repository, https://github.com/unfoldadmin/django-unfold
@@ -24,7 +25,7 @@ Description-Content-Type: text/markdown
 
 ![screenshot](https://github.com/unfoldadmin/django-unfold/assets/10785882/daef6e7e-e8a1-4142-8e4c-fa2a287978d2)
 
-## Unfold Django Admin Theme
+## Unfold Django Admin Theme <!-- omit from toc -->
 
 [![Build](https://img.shields.io/github/actions/workflow/status/unfoldadmin/django-unfold/release.yml?style=for-the-badge)](https://github.com/unfoldadmin/django-unfold/actions?query=workflow%3Arelease)
 [![PyPI - Version](https://img.shields.io/pypi/v/django-unfold.svg?style=for-the-badge)](https://pypi.org/project/django-unfold/)
@@ -33,11 +34,11 @@ Description-Content-Type: text/markdown
 
 Unfold is theme for Django admin incorporating most common practises for building full-fledged admin areas. It is designed to work at the top of default administration provided by Django.
 
-- demo site is available at [unfoldadmin.com](https://unfoldadmin.com)
-- repository with demo implementation at [github.com/unfoldadmin/formula](https://github.com/unfoldadmin/formula)
-- Django & Next.js boilerplate implementing Unfold at [github.com/unfoldadmin/turbo](https://github.com/unfoldadmin/turbo)
+- **Unfold:** demo site is available at [unfoldadmin.com](https://unfoldadmin.com)
+- **Formula:** repository with demo implementation at [github.com/unfoldadmin/formula](https://github.com/unfoldadmin/formula)
+- **Turbo:** Django & Next.js boilerplate implementing Unfold at [github.com/unfoldadmin/turbo](https://github.com/unfoldadmin/turbo)
 
-## Features
+## Features <!-- omit from toc -->
 
 - **Visual**: provides new user interface based on Tailwind CSS framework
 - **Sidebar:** simplifies definition of custom sidebar navigation with icons
@@ -46,38 +47,41 @@ Unfold is theme for Django admin incorporating most common practises for buildin
 - **Dependencies:** completely based only on `django.contrib.admin`
 - **Actions:** multiple ways how to define actions within different parts of admin
 - **WYSIWYG:** built-in support for WYSIWYG (Trix)
-- **Numeric filters:** widgets for filtering number values
-- **Datetime filters:** widgets for filtering datetime values
+- **Custom filters:** widgets for filtering number & datetime values
 - **Dashboard:** helpers to bootstrap custom dashboard
 - **Tabs:** define custom tab navigations for models
 - **Colors:** possibility to override default color scheme
-- **Django import / export:** default support for this popular application
+- **Third party packages:** default support for multiple popular applications
 
-## Table of Contents
+## Table of contents <!-- omit from toc -->
 
 - [Installation](#installation)
 - [Configuration](#configuration)
   - [Available settings.py options](#available-settingspy-options)
   - [Available unfold.admin.ModelAdmin options](#available-unfoldadminmodeladmin-options)
-- [Decorators](#decorators)
-  - [@display](#display)
 - [Actions](#actions)
   - [Actions overview](#actions-overview)
   - [Custom unfold @action decorator](#custom-unfold-action-decorator)
   - [Action handler functions](#action-handler-functions)
-    - [For submit row action](#for-submit-row-action)
-    - [For global, row and detail action](#for-global-row-and-detail-action)
   - [Action examples](#action-examples)
 - [Filters](#filters)
+  - [Numeric filters](#numeric-filters)
+  - [Date/time filters](#datetime-filters)
+- [Display decorator](#display-decorator)
 - [Third party packages](#third-party-packages)
+  - [django-celery-beat](#django-celery-beat)
+  - [django-guardian](#django-guardian)
   - [django-import-export](#django-import-export)
+  - [django-modeltranslation](#django-modeltranslation)
+  - [django-money](#django-money)
+  - [django-simple-history](#django-simple-history)
 - [User Admin Form](#user-admin-form)
-- [Adding Custom Styles and Scripts](#adding-custom-styles-and-scripts)
-- [Project Level Tailwind Stylesheet](#project-level-tailwind-stylesheet)
-- [Custom Admin Dashboard](#custom-admin-dashboard)
-- [Unfold Development](#unfold-development)
+- [Adding custom styles and scripts](#adding-custom-styles-and-scripts)
+- [Project level Tailwind stylesheet](#project-level-tailwind-stylesheet)
+- [Custom admin dashboard](#custom-admin-dashboard)
+- [Unfold development](#unfold-development)
   - [Pre-commit](#pre-commit)
-  - [Poetry Configuration](#poetry-configuration)
+  - [Poetry configuration](#poetry-configuration)
   - [Compiling Tailwind](#compiling-tailwind)
 - [Credits](#credits)
 
@@ -93,6 +97,8 @@ INSTALLED_APPS = [
     "unfold.contrib.filters",  # optional, if special filters are needed
     "unfold.contrib.forms",  # optional, if special form elements are needed
     "unfold.contrib.import_export",  # optional, if django-import-export package is used
+    "unfold.contrib.guardian",  # optional, if django-guardian package is used
+    "unfold.contrib.simple_history",  # optional, if django-simple-history package is used
     "django.contrib.admin",  # required
 ]
 ```
@@ -192,6 +198,7 @@ UNFOLD = {
             "700": "126 34 206",
             "800": "107 33 168",
             "900": "88 28 135",
+            "950": "59 7 100",
         },
     },
     "EXTENSIONS": {
@@ -301,73 +308,6 @@ class CustomAdminClass(ModelAdmin):
     }
 ```
 
-## Decorators
-
-### @display
-
-Unfold introduces it's own `unfold.decorators.display` decorator. By default it has exactly same behavior as native `django.contrib.admin.decorators.display` but it adds same customizations which helps to extends default logic.
-
-`@display(label=True)`, `@display(label={"value1": "success"})` displays a result as a label. This option fits for different types of statuses. Label can be either boolean indicating we want to use label with default color or dict where the dict is responsible for displaying labels in different colors. At the moment these color combinations are supported: success(green), info(blue), danger(red) and warning(orange).
-
-`@display(header=True)` displays in results list two information in one table cell. Good example is when we want to display customer information, first line is going to be customer's name and right below the name display corresponding email address. Method with such a decorator is supposed to return a list with two elements `return "Full name", "E-mail address"`.
-
-```python
-# admin.py
-
-from django.db.models import TextChoices
-from django.utils.translation import gettext_lazy as _
-
-from unfold.admin import ModelAdmin
-from unfold.decorators import display
-
-
-class UserStatus(TextChoices):
-    ACTIVE = "ACTIVE", _("Active")
-    PENDING = "PENDING", _("Pending")
-    INACTIVE = "INACTIVE", _("Inactive")
-    CANCELLED = "CANCELLED", _("Cancelled")
-
-
-class UserAdmin(ModelAdmin):
-    list_display = [
-        "display_as_two_line_heading",
-        "show_status",
-        "show_status_with_custom_label",
-    ]
-
-    @display(
-        description=_("Status"),
-        ordering="status",
-        label=True
-    )
-    def show_status_default_color(self, obj):
-        return obj.status
-
-    @display(
-        description=_("Status"),
-        ordering="status",
-        label={
-            UserStatus.ACTIVE: "success",  # green
-            UserStatus.PENDING: "info",  # blue
-            UserStatus.INACTIVE: "warning",  # orange
-            UserStatus.CANCELLED: "danger",  # red
-        },
-    )
-    def show_status_customized_color(self, obj)
-        return obj.status
-
-    @display(description=_("Status with label"), ordering="status", label=True)
-    def show_status_with_custom_label(self, obj):
-        return obj.status, obj.get_status_display()
-
-    @display(header=True)
-    def display_as_two_line_heading(self, obj):
-        """
-        Third argument is short text which will appear as prefix in circle
-        """
-        return "First main heading", "Smaller additional description", "AB"
-```
-
 ## Actions
 
 It is highly recommended to read the base [Django actions documentation](https://docs.djangoproject.com/en/4.2/ref/contrib/admin/actions/) before reading this section, since Unfold actions are derived from Django actions.
@@ -398,13 +338,13 @@ Unfold also uses custom `@action` decorator, supporting 2 more parameters in com
 This section provides explanation of how the action handler functions should be constructed for Unfold actions.
 For default actions, follow official Django admin documentation.
 
-#### For submit row action
+#### For submit row action <!-- omit from toc -->
 
 Submit row actions work a bit differently when compared to other custom Unfold actions.
 These actions first invoke form save (same as if you hit `Save` button) and then lets you
 perform additional logic on already saved instance.
 
-#### For global, row and detail action
+#### For global, row and detail action <!-- omit from toc -->
 
 All these actions are based on custom URLs generated for each of them. Handler function for these views is
 basically function based view.
@@ -502,6 +442,10 @@ class UserAdmin(ModelAdmin):
 
 By default, Django admin handles all filters as regular HTML links pointing at the same URL with different query parameters. This approach is for basic filtering more than enough. In the case of more advanced filtering by incorporating input fields, it is not going to work.
 
+**Note:** when implementing a filter which contains input fields, there is a no way that user can submit the values, because default filters does not contain submit button. To implement submit button, `unfold.admin.ModelAdmin` contains boolean `list_filter_submit` flag which enables submit button in filter form.
+
+### Numeric filters
+
 Currently, Unfold implements numeric filters inside `unfold.contrib.filters` application. In order to use these filters, it is required to add this application into `INSTALLED_APPS` in `settings.py` right after `unfold` application.
 
 ```python
@@ -516,8 +460,6 @@ from unfold.contrib.filters.admin import (
     RangeNumericFilter,
     SingleNumericFilter,
     SliderNumericFilter,
-    RangeDateFilter,
-    RangeDateTimeFilter,
 )
 
 
@@ -539,8 +481,6 @@ class YourModelAdmin(ModelAdmin):
         ("field_B", RangeNumericFilter),  # Numeric range search, __gte and __lte lookup
         ("field_C", SliderNumericFilter),  # Numeric range filter but with slider
         ("field_D", CustomSliderNumericFilter),  # Numeric filter with custom attributes
-        ("field_E", RangeDateFilter),  # Date filter
-        ("field_F", RangeDateTimeFilter),  # Datetime filter
         CustomRangeNumericListFilter,  # Numeric range search not restricted to a model field
     )
 
@@ -548,13 +488,150 @@ class YourModelAdmin(ModelAdmin):
         return super().get_queryset().annotate(items_count=Count("item", distinct=True))
 ```
 
+### Date/time filters
+
+```python
+# admin.py
+
+from django.contrib import admin
+from django.contrib.auth.models import User
+
+from unfold.admin import ModelAdmin
+from unfold.contrib.filters.admin import (
+    RangeDateFilter,
+    RangeDateTimeFilter,
+)
+
+
+@admin.register(User)
+class YourModelAdmin(ModelAdmin):
+    list_filter_submit = True  # Submit button at the bottom of the filter
+    list_filter = (
+        ("field_E", RangeDateFilter),  # Date filter
+        ("field_F", RangeDateTimeFilter),  # Datetime filter
+    )
+```
+
+## Display decorator
+
+Unfold introduces it's own `unfold.decorators.display` decorator. By default it has exactly same behavior as native `django.contrib.admin.decorators.display` but it adds same customizations which helps to extends default logic.
+
+`@display(label=True)`, `@display(label={"value1": "success"})` displays a result as a label. This option fits for different types of statuses. Label can be either boolean indicating we want to use label with default color or dict where the dict is responsible for displaying labels in different colors. At the moment these color combinations are supported: success(green), info(blue), danger(red) and warning(orange).
+
+`@display(header=True)` displays in results list two information in one table cell. Good example is when we want to display customer information, first line is going to be customer's name and right below the name display corresponding email address. Method with such a decorator is supposed to return a list with two elements `return "Full name", "E-mail address"`. There is a third optional argument, which is type of the string and its value is displayed in a circle before first two values on the front end. Its optimal usage is for displaying initials.
+
+```python
+# admin.py
+
+from django.db.models import TextChoices
+from django.utils.translation import gettext_lazy as _
+
+from unfold.admin import ModelAdmin
+from unfold.decorators import display
+
+
+class UserStatus(TextChoices):
+    ACTIVE = "ACTIVE", _("Active")
+    PENDING = "PENDING", _("Pending")
+    INACTIVE = "INACTIVE", _("Inactive")
+    CANCELLED = "CANCELLED", _("Cancelled")
+
+
+class UserAdmin(ModelAdmin):
+    list_display = [
+        "display_as_two_line_heading",
+        "show_status",
+        "show_status_with_custom_label",
+    ]
+
+    @display(
+        description=_("Status"),
+        ordering="status",
+        label=True
+    )
+    def show_status_default_color(self, obj):
+        return obj.status
+
+    @display(
+        description=_("Status"),
+        ordering="status",
+        label={
+            UserStatus.ACTIVE: "success",  # green
+            UserStatus.PENDING: "info",  # blue
+            UserStatus.INACTIVE: "warning",  # orange
+            UserStatus.CANCELLED: "danger",  # red
+        },
+    )
+    def show_status_customized_color(self, obj)
+        return obj.status
+
+    @display(description=_("Status with label"), ordering="status", label=True)
+    def show_status_with_custom_label(self, obj):
+        return obj.status, obj.get_status_display()
+
+    @display(header=True)
+    def display_as_two_line_heading(self, obj):
+        """
+        Third argument is short text which will appear as prefix in circle
+        """
+        return "First main heading", "Smaller additional description", "AB"
+```
+
 ## Third party packages
 
-### django-import-export
+### django-celery-beat
+
+In general, django-celery-beat does not have any components that require special styling. The default changelist templates are not inheriting from Unfold's `ModelAdmin` but they are using default `ModelAdmin` coming from `django.contrib.admin` which is causing some design discrepancies in the changelist.
+
+In the source code below you can find a short code snippet to unregister all `django-celery-beat` admin classes and register them with the proper parent `ModelAdmin` class.
+
+```python
+# admin.py
+from django.contrib import admin
+from unfold.admin import ModelAdmin
+
+from django_celery_beat.models import (
+    ClockedSchedule,
+    CrontabSchedule,
+    IntervalSchedule,
+    PeriodicTask,
+    SolarSchedule,
+)
+
+
+admin.site.unregister(PeriodicTask)
+admin.site.unregister(IntervalSchedule)
+admin.site.unregister(CrontabSchedule)
+admin.site.unregister(SolarSchedule)
+admin.site.unregister(ClockedSchedule)
+
+@admin.register(PeriodicTask)
+class PeriodicTaskAdmin(ModelAdmin):
+    pass
+
+
+@admin.register(IntervalSchedule)
+class IntervalScheduleAdmin(ModelAdmin):
+    pass
+
+
+@admin.register(CrontabSchedule)
+class CrontabScheduleAdmin(ModelAdmin):
+    pass
+
+
+@admin.register(SolarSchedule)
+class SolarScheduleAdmin(ModelAdmin):
+    pass
+```
+
+### django-guardian
 
-To get proper visual appearance for django-import-export, two things are needed
+Adding support for django-guardian is quote straightforward in Unfold, just add `unfold.contrib.guardian` to `INSTALLED_APPS` at the beggining of the file. This action will override all templates coming from the django-guardian. Please note that **Object permissions** link is available in top right dropdown navigation.
 
-1. Add `unfold.contrib.import_export` to `INSTALLED_APPS` at the begging of the file. This action will override all templates coming from the plugin.
+### django-import-export
+
+1. Add `unfold.contrib.import_export` to `INSTALLED_APPS` at the beggining of the file. This action will override all templates coming from the application.
 2. Change `import_form_class` and `export_form_class` in ModelAdmin which is inheriting from `ImportExportModelAdmin`. This chunk of code is responsible for adding proper styling to form elements.
 
 ```python
@@ -568,6 +645,36 @@ class ExampleAdmin(ModelAdmin, ImportExportModelAdmin):
     export_form_class = ExportForm
 ```
 
+### django-modeltranslation
+
+By default Unfold does not contain any specific implementation for django-modeltranslation and the application is partially supported. Basic behavior is supported except of tab navigation provided by django-modeltranslation. At the moment there are no plans in supporting this behavior.
+
+For django-modeltranslation fields for spefic languages, it is possible to define custom flags which will appear as a suffix in field's label. It is recommended to use emojis as suffix.
+
+```python
+# settings.py
+
+UNFOLD = {
+    "EXTENSIONS": {
+        "modeltranslation": {
+            "flags": {
+                "en": "🇬🇧",
+                "fr": "🇫🇷",
+                "nl": "🇧🇪",
+            },
+        },
+    },
+}
+```
+
+### django-money
+
+This application is supported in Unfold by default. It is not needed to add any other applications into `INSTALLED_APPS`. Unfold is recognizing special form widget coming from django-money and applying specific styling.
+
+### django-simple-history
+
+To make this application work, add `unfold.contrib.simple_history` into `settings.py` in `INSTALLED_APPS` variable before right after `unfold`. This app should ensure that templates coming from django-simple-history are overriden by Unfold.
+
 ## User Admin Form
 
 User's admin in Django is specific as it contains several forms which are requiring custom styling. All of these forms has been inherited and accordingly adjusted. In user admin class it is needed to use these inherited form classes to enable custom styling matching rest of the website.
@@ -590,7 +697,7 @@ class UserAdmin(BaseUserAdmin, ModelAdmin):
     change_password_form = AdminPasswordChangeForm
 ```
 
-## Adding Custom Styles and Scripts
+## Adding custom styles and scripts
 
 To add new custom styles, for example for custom dashboard, it is possible to load them via **STYLES** key in **UNFOLD** dict. This key accepts a list of strings or lambda functions which will be loaded on all pages. JavaScript files can be loaded by using similar apprach, but **SCRIPTS** is used.
 
@@ -609,7 +716,7 @@ UNFOLD = {
 }
 ```
 
-## Project Level Tailwind Stylesheet
+## Project level Tailwind stylesheet
 
 When creating custom dashboard or adding custom components, it is needed to add own styles. Adding custom styles is described above. Most of the time, it is supposed that new elements are going to match with the rest of the administration panel. First of all, create tailwind.config.js in your application. Below is located minimal configuration for this file.
 
@@ -642,7 +749,7 @@ Once the configuration file is set, it is possible to compile new styles which c
 npx tailwindcss -o your_project/static/css/styles.css --watch --minify
 ```
 
-## Custom Admin Dashboard
+## Custom admin dashboard
 
 The most common thing which needs to be adjusted for each project in admin is the dashboard. By default Unfold does not provide any dashboard components. The default dashboard experience with list of all applications and models is kept with proper styling matching rest of the components but thats it. Anyway, Unfold was created that creation of custom dashboard will be streamlined.
 
@@ -668,7 +775,7 @@ Create `templates/admin/index.html` in your project and paste the base template
 
 Note: In case that it is needed to pass custom variables into dashboard tamplate, check **DASHOARD_CALLBACK** in **UNFOLD** dict.
 
-## Unfold Development
+## Unfold development
 
 ### Pre-commit
 
@@ -680,7 +787,7 @@ pre-commit install
 pre-commit install --hook-type commit-msg
 ```
 
-### Poetry Configuration
+### Poetry configuration
 
 To add a new feature or fix the easiest approach is to use django-unfold in combination with Poetry. The process looks like:
 
@@ -703,9 +810,9 @@ npm run tailwind:build # run once
 
 Some components like datepickers, calendars or selectors in admin was not possible to style by overriding html templates so their default styles are overriden in **styles.css**.
 
-None: most of the custom styles localted in style.css are created via `@apply some-tailwind-class;`.
+**Note:** most of the custom styles located in style.css are created via `@apply some-tailwind-class;` as is not possible to manually add CSS class to element which are for example created via jQuery.
 
-# Credits
+## Credits
 
 - [TailwindCSS](https://tailwindcss.com/) - CSS framework
 - [HTMX](https://htmx.org/) - AJAX communication with backend