feat: expandable changelist rows / related tables and templates (#1117)

Author: lukasvinclav

docs/sections/index.md

@@ -0,0 +1,96 @@
+---
+title: Sections (Expandable rows)
+order: 8
+description:
+---
+
+# Sections - expandable changelist rows
+
+Unfold implements special functionality for handling expandable rows in changelists called sections. Once the `list_sections` attribute is configured, rows in the changelist will display an arrow button at the beginning of the row which can be used to show additional content.
+
+The `list_sections` attribute consists of Python classes inheriting from `TableSection` or `TemplateSection` defined in `unfold.sections`. These classes are responsible for rendering the content in the expandable area.
+
+```python
+from unfold.admin import ModelAdmin
+from unfold.sections import TableSection, TemplateSection
+
+from .models import SomeModel
+
+# Table for related records
+class CustomTableSection(TableSection):
+    verbose_name = _("Table title")  # Displays custom table title
+    height = 300  # Force the table height. Ideal for large amount of records
+    related_name = "related_name_set"  # Related model field name
+    fields = ["pk", "title", "custom_field"]  # Fields from related model
+
+    # Custom field
+    def custom_field(self, instance):
+        return instance.pk
+
+# Simple template with custom content
+class CardSection(TemplateSection):
+    template_name = "your_app/some_template.html"
+
+
+@admin.register(SomeModel)
+class SomeAdmin(ModelAdmin):
+    list_sections = [
+        CardSection,
+        CustomTableSection,
+    ]
+```
+
+## Query optimisation
+
+When it comes to classes inheriting from `TableSection`, you may find a problem with an extraordinary amount of queries executed on changelist pages. This problem has two parts:
+
+1. `TableSection` works with related fields so another query is required to obtain data from the related table
+2. The default page size for changelist is configured to 100 - which is a pretty large number of records per page
+
+The easiest solution for this issue is to configure pagination to a smaller amount of records by setting `list_per_page = 20`. While this solution might work for you, it is not optimal.
+
+The optimal solution is using [`prefetch_related`](https://docs.djangoproject.com/en/5.1/ref/models/querysets/#prefetch-related):
+
+1. Install [django-debug-toolbar](https://github.com/django-commons/django-debug-toolbar) and check all SQL queries that are duplicating for each record in the changelist
+2. Override `get_queryset` and use `prefetch_related` on all related rows until you don't have any duplicated SQL queries in django-debug-toolbar output
+
+```python
+from unfold.admin import ModelAdmin
+
+from .models import SomeModel
+
+
+@admin.register(SomeModel)
+class SomeAdmin(ModelAdmin):
+    list_per_page = 20  # Quick solution
+    list_sections = [CustomTableSection]
+
+    # Custom queryset prefetching related records
+    def get_queryset(self, request):
+        return (
+            super()
+            .get_queryset(request)
+            .prefetch_related(
+                "related_field_set",
+                "related_field__another_related_field",
+                "related_field__another_related_field__even_more_related_field",
+            )
+        )
+```
+
+## Multiple related tables
+
+Unfold supports multiple related tables in expandable rows. Specify a section class for each related field and put them into `list_sections`. For each class, you can add a `verbose_name` to display a custom title right above the table to distinguish between different related fields.
+
+```python
+from unfold.admin import ModelAdmin
+
+from .models import SomeModel
+
+
+@admin.register(SomeModel)
+class SomeAdmin(ModelAdmin):
+    list_sections = [
+         CustomTableSection, OtherCustomTable
+    ]
+```

src/unfold/sections.py

@@ -0,0 +1,82 @@
+from django.contrib.admin.utils import label_for_field, lookup_field
+from django.db.models import Model
+from django.http import HttpRequest
+from django.template.loader import render_to_string
+
+from unfold.utils import display_for_field
+
+
+class BaseSection:
+    def __init__(self, request: HttpRequest, instance: Model) -> None:
+        self.request = request
+        self.instance = instance
+
+    def render(self) -> str:
+        raise NotImplementedError(
+            "Section subclasses must implement the render method."
+        )
+
+
+class TableSection(BaseSection):
+    fields = []
+    related_name = None
+    verbose_name = None
+    height = None
+
+    def render(self) -> str:
+        results = getattr(self.instance, self.related_name)
+        headers = []
+        rows = []
+
+        for field_name in self.fields:
+            if hasattr(self, field_name):
+                if hasattr(getattr(self, field_name), "short_description"):
+                    headers.append(getattr(self, field_name).short_description)
+                else:
+                    headers.append(field_name)
+            else:
+                headers.append(label_for_field(field_name, results.model))
+
+        for result in results.all():
+            row = []
+
+            for field_name in self.fields:
+                if hasattr(self, field_name):
+                    row.append(getattr(self, field_name)(result))
+                else:
+                    field, attr, value = lookup_field(field_name, result)
+                    row.append(display_for_field(value, field, "-"))
+
+            rows.append(row)
+
+        context = {
+            "request": self.request,
+            "table": {
+                "headers": headers,
+                "rows": rows,
+            },
+        }
+
+        if hasattr(self, "verbose_name") and self.verbose_name:
+            context["title"] = self.verbose_name
+
+        if hasattr(self, "height") and self.height:
+            context["height"] = self.height
+
+        return render_to_string(
+            "unfold/components/table.html",
+            context=context,
+        )
+
+
+class TemplateSection(BaseSection):
+    template_name = None
+
+    def render(self) -> str:
+        return render_to_string(
+            self.template_name,
+            context={
+                "request": self.request,
+                "instance": self.instance,
+            },
+        )

src/unfold/static/unfold/css/styles.css

@@ -1,4 +1,4 @@
-{% load admin_urls i18n %}
+{% load admin_urls i18n unfold %}
 
 {% if result_hidden_fields %}
     <div class="hiddenfields">
@@ -11,6 +11,10 @@
         <table id="result_list" class="block border-base-200 border-spacing-none border-separate w-full lg:table">
             <thead>
                 <tr>
+                    {% if cl.model_admin.list_sections|length > 0 %}
+                        <th></th>
+                    {% endif %}
+
                     {% for header in result_headers %}
                         <th class="align-middle font-semibold py-2 text-left text-font-important-light dark:text-font-important-dark whitespace-nowrap {{ header.class_attrib }} {% if "action-toggle" in header.text and forloop.counter == 1 %}lg:px-3 lg:w-10{% else %}hidden px-3 lg:table-cell{% endif %}" scope="col">
                             <div class="flex items-center">
@@ -65,8 +69,8 @@
                 </tr>
             </thead>
 
-            <tbody class="block lg:table-row-group">
-                {% for result in results %}
+            {% for result in results %}
+                <tbody class="block lg:table-row-group" x-data="{rowOpen: false}">
                     {% if result.form and result.form.non_field_errors %}
                         <tr>
                             <td class="text-left" colspan="{{ result|length }}">
@@ -76,13 +80,37 @@
                     {% endif %}
 
                     <tr class="{% cycle '' 'bg-base-50 dark:bg-white/[.02]' %} block border mb-3 rounded shadow-sm lg:table-row lg:border-none lg:mb-0 lg:shadow-none dark:border-base-800">
+                        {% if cl.model_admin.list_sections|length > 0 %}
+                            <td class="align-middle border-t border-base-200 cursor-pointer pl-3 relative select-none text-center dark:border-base-800 w-0" x-on:click="rowOpen = !rowOpen">
+                                <div class="absolute bg-primary-600 -bottom-px left-0 top-0 w-0.5 z-10" x-show="rowOpen"></div>
+                                <span class="material-symbols-outlined !block -rotate-90 transition-all" x-bind:class="rowOpen && 'rotate-0'">
+                                    expand_more
+                                </span>
+                            </td>
+                        {% endif %}
+
                         {% for item in result %}
                             {{ item }}
                         {% endfor %}
-                        {% include 'unfold/helpers/actions_row.html' with actions=actions_row instance_pk=result.instance_pk %}
+
+                        {% include 'unfold/helpers/actions_row.html' with actions=actions_row instance_pk=result.instance.pk %}
                     </tr>
-                {% endfor %}
-            </tbody>
+
+                    {% if cl.model_admin.list_sections|length > 0 %}
+                        <tr x-show="rowOpen">
+                            <td colspan="{{ result|length|add:1 }}" class="bg-base-200/10 border-t border-base-200 relative shadow-inner p-3 dark:border-base-800">
+                                <div class="absolute bg-primary-600 h-full left-0 top-0 w-0.5"></div>
+
+                                <div class="grid gap-3 {{ cl.model_admin.list_sections_classes }}">
+                                    {% for section in cl.model_admin.list_sections %}
+                                        {% render_section cl.model_admin.list_sections|index:forloop.counter0 result.instance %}
+                                    {% endfor %}
+                                </div>
+                            </td>
+                        </tr>
+                    {% endif %}
+                </tbody>
+            {% endfor %}
         </table>
     </div>
 {% else %}

src/unfold/templates/admin/change_list_results.html

@@ -1,4 +1,4 @@
-<div class="border flex flex-col flex-grow overflow-hidden p-6 relative rounded shadow-sm dark:border-base-800 {% if class %} {{ class }}{% endif %}">
+<div class="bg-white border flex flex-col flex-grow overflow-hidden p-6 relative rounded shadow-sm dark:bg-base-900 dark:border-base-800 {% if class %} {{ class }}{% endif %}">
     {% if title %}
         <h2 class="bg-base-50 border-b font-semibold mb-6 -mt-6 -mx-6 py-4 px-6 text-font-important-light dark:text-font-important-dark dark:border-base-800 dark:bg-white/[.02]">
             {{ title }}

src/unfold/templates/unfold/components/card.html

@@ -1,31 +1,47 @@
-{% load unfold %}
+{% load i18n unfold %}
 
-<div class="{% if card_included == 1 %}-m-6{% else %}lg:border lg:rounded lg:shadow-sm{% endif %} overflow-x-auto lg:dark:border-base-800">
-    <table class="block border-base-200 border-spacing-none border-separate w-full lg:table">
-        {% if table.headers %}
-            <thead class="text-base-900 dark:text-base-100">
-                <tr class="bg-base-50 dark:bg-white/[.02]">
-                    {% for  header in table.headers %}
-                        <th class="align-middle font-semibold py-2 text-left text-sm whitespace-nowrap sortable column-description hidden px-3 lg:table-cell {% if card_included == 1 %}first:pl-6 last:pr-6{% endif %}">
-                            {{ header }}
-                        </th>
-                    {% endfor %}
-                </tr>
-            </thead>
-        {% endif %}
+<div class="flex flex-col">
+    {% if title %}
+        <h3 class="font-semibold mb-1 text-font-important-light text-sm dark:text-font-important-dark">
+            {{ title }}
+        </h3>
+    {% endif %}
+
+    <div class="{% if card_included == 1 %}-m-6{% else %} bg-white flex flex-col grow lg:border lg:border-base-200 lg:overflow-hidden lg:rounded lg:shadow-sm{% endif %} lg:dark:border-base-800 dark:bg-base-900">
+        <div {% if height %} class="min-h-[37px]" style="max-height: {{ height }}px;" data-simplebar{% endif %}>
+            <table class="block border-spacing-none border-separate w-full lg:table">
+                {% if table.headers %}
+                    <thead class="text-base-900 dark:text-base-100 {% if height %}sticky top-0{% endif %}">
+                        <tr class="bg-base-50 dark:bg-white/[.02]">
+                            {% for  header in table.headers %}
+                                <th class="align-middle border-b border-base-200 font-semibold py-2 text-left text-sm whitespace-nowrap sortable column-description hidden px-3 lg:table-cell dark:border-base-800 {% if card_included == 1 %}first:pl-6 last:pr-6{% endif %}">
+                                    {{ header|capfirst }}
+                                </th>
+                            {% endfor %}
+                        </tr>
+                    </thead>
+                {% endif %}
 
-        {% if table.rows %}
-            <tbody class="block lg:table-row-group">
-                {% for row in table.rows %}
-                    <tr class="{% if striped == 1 %}{% cycle '' 'bg-base-50 dark:bg-white/[.02]' %}{% endif %} block {% if not card_included == 1 %}border mb-3 rounded shadow-sm{% else %}border-t{% endif %} lg:table-row lg:border-none lg:mb-0 lg:shadow-none dark:border-base-800">
-                        {% for cell in row %}
-                            <td class="px-3 py-2 align-middle flex border-t border-base-200 font-normal gap-4 min-w-0 overflow-hidden text-left before:flex before:capitalize before:content-[attr(data-label)] before:items-center before:mr-auto first:border-t-0 lg:before:hidden lg:first:border-t lg:py-3 lg:table-cell dark:border-base-800 {% if card_included == 1 %}lg:first:pl-6 lg:last:pr-6{% endif %}" {% if table.headers %}data-label="{{ table.headers|index:forloop.counter0 }}"{% endif %}>
-                                {{ cell }}
-                            </td>
+                {% if table.rows %}
+                    <tbody class="block lg:table-row-group">
+                        {% for row in table.rows %}
+                            <tr class="{% if striped == 1 %}{% cycle '' 'bg-base-50 dark:bg-white/[.02]' %}{% endif %} block group {% if forloop.first %}first-row{% endif %} {% if not card_included == 1 %}border mb-3 rounded shadow-sm{% else %}border-b{% endif %} lg:table-row lg:border-none lg:mb-0 lg:shadow-none dark:border-base-800">
+                                {% for cell in row %}
+                                    <td class="px-3 py-2 align-middle flex border-t group-[.first-row]:border-t-0 border-base-200 font-normal gap-4 min-w-0 overflow-hidden text-left before:flex before:capitalize before:content-[attr(data-label)] before:items-center before:mr-auto first:border-t-0 lg:before:hidden lg:first:border-t lg:py-3 lg:table-cell dark:border-base-800 {% if card_included == 1 %}lg:first:pl-6 lg:last:pr-6{% endif %}" {% if table.headers %}data-label="{{ table.headers|index:forloop.counter0 }}"{% endif %}>
+                                        {{ cell }}
+                                    </td>
+                                {% endfor %}
+                            </tr>
                         {% endfor %}
-                    </tr>
-                {% endfor %}
-            </tbody>
+                    </tbody>
+                {% endif %}
+            </table>
+        </div>
+
+        {% if not table.rows %}
+            <p class="bg-white flex grow items-center justify-center py-2 dark:bg-gray-900">
+                {% trans "No data" %}
+            </p>
         {% endif %}
-    </table>
+    </div>
 </div>

src/unfold/templates/unfold/components/table.html

@@ -4,6 +4,7 @@
 from django import template
 from django.contrib.admin.helpers import AdminForm, Fieldset
 from django.contrib.admin.views.main import ChangeList
+from django.db.models import Model
 from django.db.models.options import Options
 from django.forms import Field
 from django.http import HttpRequest
@@ -85,6 +86,11 @@ def tab_list(context: RequestContext, page: str, opts: Optional[Options] = None)
     )
 
 
+@register.simple_tag(name="render_section", takes_context=True)
+def render_section(context: Context, section_class, instance: Model) -> str:
+    return section_class(context.request, instance).render()
+
+
 @register.simple_tag(name="has_nav_item_active")
 def has_nav_item_active(items: list) -> bool:
     for item in items:
@@ -214,14 +220,17 @@ def render(self, context: RequestContext) -> str:
 
         if "component_class" in values:
             values = ComponentRegistry.create_instance(
-                values["component_class"], request=context.request
+                values["component_class"],
+                request=context.request if hasattr(context, "request") else None,
             ).get_context_data(**values)
 
         if self.include_context:
             values.update(context.flatten())
 
         return render_to_string(
-            self.template_name, request=context.request, context=values
+            self.template_name,
+            request=context.request if hasattr(context, "request") else None,
+            context=values,
         )