feat: paginated inlines (#1373)

Author: lukasvinclav

README.md

@@ -26,11 +26,11 @@ Unfold Studio is a theme customizer for Django admin that helps you create a bra
 
 ## Fresh Features & Enhancements
 
+- **Paginated inlines:** Break down large record sets into pages within inlines for better admin performance
 - **Conditional fields:** Show or hide fields dynamically based on the values of other fields in the form
 - **Infinite paginator:** Efficiently handle large datasets with seamless pagination that reduces server load
 - **Checkbox & radio filters:** Enhanced filter options with checkbox and radio interfaces for intuitive filtering
 - **Site dropdown:** Configurable dropdown menu in the header area for managing custom navigation links
-- **Dropdown actions:** Organize action items in customizable dropdown menus
 
 ## Core Features & Capabilities
 
@@ -50,6 +50,7 @@ Unfold Studio is a theme customizer for Django admin that helps you create a bra
 - **Sortable inlines:** Allow sorting inlines by dragging and dropping
 - **Environment label:** Distinguish between environments by displaying a label
 - **Nonrelated inlines:** Display nonrelated models as inlines in the change form
+- **Paginated inlines:** Break down large record sets into pages within inlines for better admin performance
 - **Favicons:** Built-in support for configuring various site favicons
 - **Themes:** Allow customization of color scheme, background color, border radius, and more
 - **Font colors:** Adjust font colors for better readability

docs/inlines/options.md

@@ -6,15 +6,17 @@ description: Customize Django Unfold inline options including title customizatio
 
 # Available options for Unfold inlines
 
-By default, each inline row's title is derived from the model's `__str__` implementation. However, Unfold provides the ability to customize this title specifically for inlines by implementing a `get_inline_title` method on the model, which can return a custom title that will only be used in inline contexts.
+## Custom inline title
+
+By default, each inline row's title is derived from the model's `__str__` implementation. However, Unfold provides the ability to customize this title specifically for inlines by implementing a `get_inline_title` method on the model. This method can return a custom title that will only be used in inline contexts, allowing for more descriptive and context-specific labels.
 
 ```python
 from django.contrib.auth.models import User
 from unfold.admin import TabularInline
 
 
 class User(models.Model):
-    # fiels, meta ...
+    # fields, meta ...
 
     def get_inline_title(self):
         return "Custom title"
@@ -26,7 +28,7 @@ class MyInline(TabularInline):
 
 ## Hide title row
 
-You can hide the title row for both `StackedInline` and `TabularInline` by setting the `hide_title` attribute to `True`. Note that for `StackedInline`, the delete permission (`can_delete`) must be disabled to hide the title row since the delete checkbox is contained within it.
+You can hide the title row for both `StackedInline` and `TabularInline` by setting the `hide_title` attribute to `True`. This feature is particularly useful when you want to create a more compact and streamlined interface. Please note that for `StackedInline`, the delete permission (`can_delete`) must be disabled to hide the title row, as the delete checkbox is contained within it.
 
 ```python
 # admin.py
@@ -39,3 +41,28 @@ class MyInline(TabularInline):
     model = User
     hide_title = True
 ```
+
+## Collapsible StackedInline
+
+Unfold enhances the `StackedInline` functionality by introducing a collapsible mode. When enabled, this feature allows you to display multiple records in a space-efficient manner by defaulting to a collapsed state. This is particularly useful when dealing with forms that contain numerous inline entries, as it helps maintain a clean and organized interface.
+
+Key features of collapsible StackedInlines:
+- Records are collapsed by default, saving vertical space
+- Users can expand individual records as needed
+- Records containing validation errors automatically expand to highlight the issues
+- The collapsed state is preserved during form submission
+- Each record can be independently expanded or collapsed
+
+To implement this feature, simply set the `collapsible` attribute to `True` in your StackedInline class:
+
+```python
+from django.contrib.auth.models import User
+from unfold.admin import StackedInline
+
+
+class User(models.Model):
+    inlines = [SomeInline]
+
+class SomeInline(StackedInline):
+    collapsible = True
+```

docs/inlines/paginated.md

@@ -0,0 +1,56 @@
+---
+title: Paginated inlines
+order: 4
+description: Implement paginated inlines in Django Unfold to efficiently manage large datasets by breaking down inline records into manageable pages, with customizable per-page settings and support for multiple paginated inlines.
+---
+
+Pagination on inlines can be enabled by providing the `per_page` property in the inline class. This feature is particularly useful when dealing with models that have a large number of related objects, as it helps improve page load times and provides a better user experience by breaking down the data into manageable chunks. The `per_page` property accepts an integer value that determines how many inline records will be displayed on each page.
+
+[![Paginated inlines](/static/docs/inlines/paginated-inlines.webp)](/static/docs/inlines/paginated-inlines.webp)
+
+It is possible to define multiple paginated inlines on the same page without any conflicts. This flexibility allows administrators to work with complex models that have multiple relationships, each potentially containing numerous records. Django Unfold handles the pagination state independently for each inline, ensuring that navigating through one inline's pages doesn't affect the pagination state of other inlines on the same admin page.
+
+Each inline has its own unique query parameter in the URL to maintain its pagination state. This implementation ensures that when users navigate between pages of different inlines, the system can track and maintain the current page for each inline separately. The unique query parameters are automatically generated and managed by Django Unfold, so developers don't need to worry about potential conflicts or parameter naming conventions.
+
+AJAX pagination is not currently supported for inlines. This means that when users click on pagination links, the entire admin page will reload to display the new set of records. While this approach may not be as seamless as AJAX-based pagination, it ensures compatibility with Django's existing admin infrastructure and maintains the reliability of the admin interface functionality.
+
+If inline records fit on only one page, no pagination controls will be displayed to keep the interface clean and uncluttered. Django Unfold automatically detects when the total number of records is less than or equal to the specified `per_page` value and hides the pagination controls accordingly. This intelligent behavior prevents unnecessary UI elements from appearing when they serve no functional purpose.
+
+```python
+from unfold.admin import StackedInline, TabularInline, GenericStackedInline, GenericTabularInline
+from unfold.contrib.inlines.admin import NonrelatedStackedInline, NonrelatedTabularInline
+
+
+############################################
+# Regular inlines
+############################################
+class SomeStackedInline(StackedInline):
+    model = YourModel
+    per_page = 10
+
+class SomeTabularInline(TabularInline):
+    model = YourModel
+    per_page = 10
+
+############################################
+# Generic inlines
+############################################
+class SomeGenericStackedInline(GenericStackedInline):
+    model = YourModel
+    per_page = 10
+
+class SomeGenericTabularInline(GenericTabularInline):
+    model = YourModel
+    per_page = 10
+
+############################################
+# Nonrelated inlines
+############################################
+class SomeNonrelatedStackedInline(NonrelatedStackedInline):
+    model = YourModel
+    per_page = 10
+
+class SomeNonrelatedTabularInline(NonrelatedTabularInline):
+    model = YourModel
+    per_page = 10
+```