diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 450f038f0b..2ce6464119 100644 --- a/CHANGELOG.txt +++ b/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) diff --git a/docs/reference/contrib/modeladmin/tips_and_tricks/custom_clean.md b/docs/reference/contrib/modeladmin/tips_and_tricks/custom_clean.md new file mode 100644 index 0000000000..2a4788ae00 --- /dev/null +++ b/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. diff --git a/docs/reference/contrib/modeladmin/tips_and_tricks/index.rst b/docs/reference/contrib/modeladmin/tips_and_tricks/index.md similarity index 55% rename from docs/reference/contrib/modeladmin/tips_and_tricks/index.rst rename to docs/reference/contrib/modeladmin/tips_and_tricks/index.md index d17791ce8c..2b53f3d31c 100644 --- a/docs/reference/contrib/modeladmin/tips_and_tricks/index.rst +++ b/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 +``` diff --git a/docs/releases/2.17.md b/docs/releases/2.17.md index 71bf53310a..d7bb43827b 100644 --- a/docs/releases/2.17.md +++ b/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