Documentation - modelAdmin - add form clean example

CHANGELOG.txt

@@ -23,6 +23,7 @@ Changelog
  * Remove most uppercased text styles from admin UI (Paarth Agarwal)
  * Convert all UI code to CSS logical properties for Right-to-Left (RTL) language support (Thibaud Colas)
  * Migrate multiple documentation pages from RST to MD (Vibhakar Solanki, LB (Ben Johnston))
+ * Add documentation for defining custom form validation on models used in Wagtail's `modelAdmin` (Serafeim Papastefanos)
  * Fix: When using `simple_translations` ensure that the user is redirected to the page edit view when submitting for a single locale (Mitchel Cabuloy)
  * Fix: When previewing unsaved changes to `Form` pages, ensure that all added fields are correctly shown in the preview (Joshua Munn)
  * Fix: When Documents (e.g. PDFs) have been configured to be served inline via `WAGTAILDOCS_CONTENT_TYPES` & `WAGTAILDOCS_INLINE_CONTENT_TYPES` ensure that the filename is correctly set in the `Content-Disposition` header so that saving the files will use the correct filename (John-Scott Atlakson)

docs/reference/contrib/modeladmin/tips_and_tricks/custom_clean.md

@@ -0,0 +1,46 @@
+(modeladmin_custom_clean)=
+
+# Adding a custom clean method to your ModelAdmin models
+
+The simplest way is to extend your ModelAdmin model and add a clean() model to it. For example:
+
+```python
+from django import forms
+from django.db import models
+
+class ModelAdminModel(models.Model):
+    def clean(self):
+        if self.image.width < 1920 or self.image.height < 1080:
+            raise forms.ValidationError("The image must be at least 1920x1080 pixels in size.")
+```
+
+This will run the clean and raise the `ValidationError` whenever you save the model and the check fails. The error will be displayed at the top of the wagtail admin.
+
+If you want more fine grained-control you can add a custom `clean()` method to the `WagtailAdminPageForm` of your model.
+You can override the form of your ModelAdmin in a similar matter as wagtail Pages.
+
+So, create a custom `WagtailAdminPageForm`:
+
+```python
+from wagtail.admin.forms import WagtailAdminPageForm
+
+class ModelAdminModelForm(WagtailAdminPageForm):
+    def clean(self):
+        cleaned_data = super().clean()
+        image = cleaned_data.get("image")
+        if image and image.width < 1920 or image.height < 1080:
+            self.add_error("image", "The image must be at least 1920x1080px")
+
+        return cleaned_data
+```
+
+And then set the `base_form_class` of your model:
+
+```python
+from django.db import models
+
+class ModelAdminModel(models.Model):
+    base_form_class = ModelAdminModelForm
+```
+
+Using `self.add_error` will display the error to the particular field that has the error.

docs/reference/contrib/modeladmin/tips_and_tricks/index.md

@@ -1,10 +1,11 @@
-==========================
-Additional tips and tricks
-==========================
+# Additional tips and tricks
 
 This section explores some of modeladmin's lesser-known features, and provides examples to help with modeladmin customisation. More pages will be added in future.
 
-.. toctree::
-    :maxdepth: 1
-
-    reversing_urls
+```{toctree}
+---
+maxdepth: 1
+---
+custom_clean
+reversing_urls
+```

docs/releases/2.17.md

@@ -43,6 +43,7 @@ The panel types `StreamFieldPanel`, `RichTextFieldPanel`, `ImageChooserPanel`, `
  * Remove core usage of jinjalint and migrate to curlylint to resolve dependency incompatibility issues (Thibaud Colas)
  * Switch focus outlines implementation to `:focus-visible` for cross-browser consistency (Paarth Agarwal)
  * Migrate multiple documentation pages from RST to MD (Vibhakar Solanki, LB (Ben Johnston))
+ * Add documentation for defining [custom form validation](modeladmin_custom_clean) on models used in Wagtail's `modelAdmin` (Serafeim Papastefanos)
 
 
 ### Bug fixes