From bf52a22b4132d5ef527bc6a002f20adaf634c9d4 Mon Sep 17 00:00:00 2001
From: Steve Boyd <emteknetnz@gmail.com>
Date: Fri, 6 Dec 2024 10:13:40 +1300
Subject: [PATCH] DOC RequiredFields allow_whitespace_only config

---
 .../03_Forms/01_Validation.md                 | 33 +++++++++++++++++++
 en/08_Changelogs/5.4.0.md                     |  1 +
 2 files changed, 34 insertions(+)

diff --git a/en/02_Developer_Guides/03_Forms/01_Validation.md b/en/02_Developer_Guides/03_Forms/01_Validation.md
index f9f972e0b..d42bf90c9 100644
--- a/en/02_Developer_Guides/03_Forms/01_Validation.md
+++ b/en/02_Developer_Guides/03_Forms/01_Validation.md
@@ -394,6 +394,39 @@ class MyPage extends Page
 > You can also update the `CompositeValidator` by creating an `Extension` and implementing the
 > `updateCMSCompositeValidator()` method.
 
+### `RequiredFields` and whitespace
+
+By default, `RequiredFields` will consider a field with only whitespace as a valid value. You an change this behavior with the [`allow_whitespace_only`](api:SilverStripe\Forms\RequiredFields->allow_whitespace_only) global configuration, or on a per-instance basis using [`setAllowWhitespaceOnly()`](api:SilverStripe\Forms\RequiredFields::setAllowWhitespaceOnly()).
+
+```yml
+# global configuration
+SilverStripe\Forms\RequiredFields:
+  allow_whitespace_only: false
+```
+
+```php
+namespace App\PageType;
+
+use Page;
+use SilverStripe\Forms\CompositeValidator;
+use SilverStripe\Forms\RequiredFields;
+
+class MyPage extends Page
+{
+    // ...
+
+    public function getCMSCompositeValidator(): CompositeValidator
+    {
+        $validator = parent::getCMSCompositeValidator();
+        $requiredFields = RequiredFields::create(['MyRequiredField']);
+        // per instance configuration, will override global configuration
+        $requiredFields->setAllowWhitespaceOnly(false);
+        $validator->addValidator($requiredFields);
+        return $validator;
+    }
+}
+```
+
 ## Related lessons
 
 - [Introduction to frontend forms](https://www.silverstripe.org/learn/lessons/v4/introduction-to-frontend-forms-1)
diff --git a/en/08_Changelogs/5.4.0.md b/en/08_Changelogs/5.4.0.md
index 6bb43bf6e..6345b094f 100644
--- a/en/08_Changelogs/5.4.0.md
+++ b/en/08_Changelogs/5.4.0.md
@@ -68,6 +68,7 @@ The `SilverStripe\CMS\Model\SiteTree.DESCRIPTION` localisation key (along with t
 - A new [`DBDatetime::getTimeBetween()`](api:SilverStripe\ORM\FieldType\DBDatetime::getTimeBetween()) method has been added. This method returns the amount of time that has passed between two `DBDateTime` objects as a human-readable string.
 - A new [`AbstractQueuedJob::getQueue()`](api:Symbiote\QueuedJobs\Services\AbstractQueuedJob::getQueue()) static method has been added to get the correct queue constant from a given string or int.
 - New [`GridFieldFilterHeader::setPlaceHolderText()`](api:SilverStripe\Forms\GridField::GridFieldFilterHeader::setPlaceHolderText()) and [`GridFieldFilterHeader::getPlaceHolderText()`](api:SilverStripe\Forms\GridField::GridFieldFilterHeader::getPlaceHolderText()) methods have been added which provide a way to override the `GridFieldFilterHeader` search field placeholder text if the dynamically generated text doesn't suit your use case.
+- [`RequiredFields`](api:SilverStripe\Forms\RequiredFields) can be to set to determine whether a whitespace only value, such as a single space character, is considered a valid value or not. This can be set globally via the [`RequiredFields.allow_whitespace_only`](api:SilverStripe\Forms\RequiredFields->allow_whitespace_only) config, which has a default value of `true` to retain backwards compatibility. This can also be set on a per-instance basis via [`RequiredFields::setAllowWhitespaceOnly()`](api:SilverStripe\Forms\RequiredFields::setAllowWhitespaceOnly()) which will override the global config. See [form validation docs](/developer_guides/forms/validation/#requiredfields-and-whitespace) for more details.
 
 ## API changes