Browse Source

docs(skills): Expand unfold-admin with data formats and integration setup

- Add autocomplete field classes and custom inline title to widgets-inlines
- Add automatic widget mapping table (Django field → Unfold widget)
- Add cohort, tracker, progress, and table data format specs to dashboard
- Add crispy-forms template pack and constance setup to resources
- Expand community tips to 15 gotchas
- Add readonly field preprocessing reference

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
0xDarkMatter 2 months ago
parent
commit
a8525ea064

+ 67 - 0
skills/unfold-admin/references/dashboard.md

@@ -326,3 +326,70 @@ class MyAdmin(ModelAdmin):
 ```
 
 `InfinitePaginator` provides infinite scroll instead of page numbers.
+
+## Component Data Formats
+
+### Cohort Data
+
+```python
+cohort_data = {
+    "headers": [
+        {"title": "Week 1", "subtitle": "Jan 1-7"},
+        {"title": "Week 2", "subtitle": "Jan 8-14"},
+    ],
+    "rows": [
+        {
+            "header": {"title": "Cohort A", "subtitle": "100 users"},
+            "cols": [
+                {"value": "85%", "subtitle": "85 users"},
+                {"value": "72%", "subtitle": "72 users"},
+            ],
+        },
+    ],
+}
+```
+
+### Tracker Data
+
+```python
+tracker_data = [
+    {"color": "bg-primary-400 dark:bg-primary-700", "tooltip": "Jan 1: 5 events"},
+    {"color": "bg-primary-200 dark:bg-primary-900", "tooltip": "Jan 2: 2 events"},
+    {"color": "bg-danger-400 dark:bg-danger-700", "tooltip": "Jan 3: 0 events"},
+]
+```
+
+### Progress Data (Multi-Segment)
+
+```python
+# Single bar
+progress_single = {
+    "title": "Completion",
+    "description": "57.5%",
+    "value": 57.5,
+}
+
+# Multi-segment bar
+progress_multi = {
+    "title": "Distribution",
+    "description": "Total 100%",
+    "items": [
+        {"title": "Active", "value": 60.0, "progress-class": "bg-primary-500"},
+        {"title": "Pending", "value": 25.0, "progress-class": "bg-warning-500"},
+        {"title": "Inactive", "value": 15.0, "progress-class": "bg-danger-500"},
+    ],
+}
+```
+
+### Table Data
+
+```python
+table_data = {
+    "headers": ["Name", "Status", "Amount"],
+    "rows": [
+        ["John", "Active", "$500"],
+        ["Jane", "Inactive", "$300"],
+    ],
+    "collapsible": True,  # optional
+}
+```

+ 22 - 1
skills/unfold-admin/references/resources.md

@@ -59,7 +59,7 @@ Unfold provides styled wrappers for these packages. Use the multiple inheritance
 | django-money | `unfold.widgets` | `UnfoldAdminMoneyWidget` |
 | djangoql | Compatible | Mix `DjangoQLSearchMixin` with `ModelAdmin` |
 | django-json-widget | Compatible | Use Unfold form overrides |
-| django-crispy-forms | Compatible | Unfold template pack available |
+| django-crispy-forms | Compatible | Unfold template pack `unfold_crispy` |
 
 ### django-import-export Setup
 
@@ -127,6 +127,27 @@ class ClockedScheduleAdmin(BaseClockedScheduleAdmin, ModelAdmin):
     pass
 ```
 
+### django-crispy-forms Setup
+
+```python
+# settings.py
+CRISPY_TEMPLATE_PACK = "unfold_crispy"
+CRISPY_ALLOWED_TEMPLATE_PACKS = ["unfold_crispy"]
+```
+
+In templates: `{% crispy form "unfold_crispy" %}`. For formsets, use `"unfold_crispy/layout/table_inline_formset.html"` as the FormHelper template.
+
+### django-constance Setup
+
+```python
+INSTALLED_APPS = [
+    "unfold.contrib.constance",
+    "constance",
+]
+```
+
+Use `UNFOLD_CONSTANCE_ADDITIONAL_FIELDS` from `unfold.contrib.constance.settings` to define custom field widgets for constance config values.
+
 ### Multiple Inheritance Pattern
 
 Order matters - Unfold `ModelAdmin` should be last:

+ 26 - 0
skills/unfold-admin/references/widgets-inlines.md

@@ -97,6 +97,19 @@ All from `unfold.widgets`:
 | `UnfoldAdminMoneyWidget` | `django-money` |
 | `UnfoldAdminLocationWidget` | `django-location-field` |
 
+### Autocomplete Field Classes
+
+For custom autocomplete views (beyond Django's built-in `autocomplete_fields`):
+
+```python
+from unfold.fields import (
+    UnfoldAdminAutocompleteModelChoiceField,        # single select
+    UnfoldAdminMultipleAutocompleteModelChoiceField, # multi select
+)
+```
+
+These are form **fields** (not widgets) - use them in custom forms when you need autocomplete with a custom `BaseAutocompleteView` backend.
+
 ## Automatic Widget Mapping
 
 Unfold automatically applies styled widgets to all standard Django fields. You do NOT need `formfield_overrides` for basic field types - they're handled by default. This mapping shows what Unfold applies behind the scenes:
@@ -299,6 +312,19 @@ class StandingInline(StackedInline):
     hide_title = True
 ```
 
+### Custom Inline Title
+
+Override the default inline title by adding `get_inline_title()` to the model:
+
+```python
+# models.py
+class RelatedModel(models.Model):
+    name = models.CharField(max_length=100)
+
+    def get_inline_title(self):
+        return f"Custom: {self.name}"
+```
+
 ### Combined Example
 
 ```python