You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `AjaxCompositeValidator` adds a submit handler to your form. This doesn't always interact well with other submit handlers, and can result in either front-end validation being skipped or the form not submitting the way you expect it to, depending on which submit handler gets the event first. For best results, don't add additional submit handlers to the form.
24
24
25
-
If you're using the `AjaxCompositeValidator` on a form that uses [undefinedoffset/silverstripe-nocaptcha][3] 2.3.0 or higher, you should disable form submission handling for the `NocaptchaField` in that form (see instructions in the nocaptcha docs).
25
+
If you're using the `AjaxCompositeValidator` on a form that uses [undefinedoffset/silverstripe-nocaptcha][3], you should disable form submission handling for the `NocaptchaField` in that form (see instructions in the nocaptcha docs).
26
26
27
27
## [Available Validators][4]
28
28
29
29
-**[`AjaxCompositeValidator`][5]**
30
30
Subclass of [`CompositeValidator`][6] that provides AJAX validation. Resolves [an issue with losing data][7], faster turn-around for fixing validation problems, and provides a way to use the same validation for 'client-side' validation of frontend forms.
31
-
-**[`SimpleFieldsValidator`][8]**
32
-
Ensures the internal validation of form fields by calling `validate()` on them.
33
-
-**[`RequiredFieldsValidator`][9]**
34
-
Like Silverstripe's [`RequiredFields`][10] validator, but more convenient for use in a `CompositeValidator`.
35
31
-**[`WarningFieldsValidator`][11]**
36
32
Displays a warning if some field(s) doesn't have a value. Useful for alerting users about data that is technically valid but may not provide the results they expect
37
33
-**[`DependentRequiredFieldsValidator`][12]**
@@ -40,8 +36,6 @@ Uses [`SearchFilter`s][13] to define fields as required conditionally, based on
40
36
Require a specific [elemental block(s)][15] to exist in the `ElementalArea`, with optional minimum and maximum numbers of blocks and optional positional validation.
41
37
-**[`ConstraintsValidator`][16]**
42
38
Validate values against [`symfony/validation` constraints](https://symfony.com/doc/current/reference/constraints.html). This is super powerful - definitely check it out.
43
-
-**[`RegexFieldsValidator`][17]** (deprecated)
44
-
Ensure some field(s) matches a specified regex pattern.
45
39
46
40
### [Abstract Validators][18]
47
41
@@ -63,18 +57,14 @@ Like `ValidatesMultipleFields` but requires a configuration array for each field
Copy file name to clipboardExpand all lines: docs/en/01-validators.md
+18-85Lines changed: 18 additions & 85 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,27 +6,28 @@ All of these validators can be used in the CMS _and_ in the front-end.
6
6
7
7
## AjaxCompositeValidator
8
8
9
-
**Important:** See the [extensions docs](./02-extensions.md) for extensions that are highly recommended if you intend to use this validator.
9
+
> [!IMPORTANT]
10
+
> See the [extensions docs](./02-extensions.md) for extensions that are highly recommended if you intend to use this validator.
10
11
11
12
Note that to use this validator on the frontend, you will need to expose `jQuery` as a global variable. To avoid providing outdated or redundant copies of jQuery this module doesn't come packaged with it.
12
13
13
-
As of Silverstripe 4.7.0, all `DataObject`s have a [`CompositeValidator`](https://api.silverstripe.org/4/SilverStripe/Forms/CompositeValidator.html) automatically for CMS forms. The `AjaxCompositeValidator` is a subclass of that validator and provides AJAX validation that takes affect prior to form submission. When you click a form action that isn't validation exempt, an AJAX request is made to validate the form _prior_ to form submission. If there are any validation errors, form submission will be blocked and validation messages displayed.
14
+
All `DataObject`s have a [`CompositeValidator`](https://api.silverstripe.org/6/SilverStripe/Forms/Validation/CompositeValidator.html) automatically for CMS forms. The `AjaxCompositeValidator` is a subclass of that validator and provides AJAX validation that takes affect prior to form submission. When you click a form action that isn't validation exempt, an AJAX request is made to validate the form _prior_ to form submission. If there are any validation errors, form submission will be blocked and validation messages displayed.
14
15
15
-
This is useful for situations where data can be lost with the normal Silverstripe validation pipeline (e.g. validating fields on a page that has an [elemental area](https://github.com/silverstripe/silverstripe-elemental) - see [this issue](https://github.com/silverstripe/silverstripe-elemental/issues/764)), and is also faster as it doesn't need to reload the form after validating to display the error messages.
16
+
This is typically faster as it doesn't need to reload and re-render the form after validating to display the error messages.
16
17
17
18
This validator is also extremely useful for front-end forms, as it provides client-side-esque validation without having to re-write all of your validation logic. It even checks for Google Recaptcha v2, and will produce an error if it identifies that a Recaptcha v2 exists for the form but was not completed.
18
19
19
20
### Usage
20
21
21
-
If the [`DataObjectDefaultAjaxExtension`](./02-extensions.md#dataobjectdefaultajaxextension) extension has been applied, calling `parent::getCMSCompositeValidator()` inside the `getCMSCompositeValidator()` method will return an `AjaxCompositeValidator`, which can then be manipulated.
22
+
> [!HINT]
23
+
> See the [optional configuration](./02-extensions.md) for information about replacing the default `CompositeValidator` with `AjaxCompositeValidator`.
22
24
23
-
You can also opt to just return a new `AjaxCompositeValidator` from that method - and in front-end situations, you can instantiate a new `AjaxCompositeValidator` (preferably [via injection](https://docs.silverstripe.org/en/developer_guides/extending/injector/) i.e. `AjaxCompositeValidator::create()`).
25
+
You can also opt to just return a new `AjaxCompositeValidator` from `getCMSCompositeValidator()` - and in front-end situations, you can instantiate a new `AjaxCompositeValidator` (preferably [via injection](https://docs.silverstripe.org/en/developer_guides/extending/injector/) i.e. `AjaxCompositeValidator::create()`).
24
26
25
27
Ajax validation can also be disabled at any stage, if there is a cause for doing so.
26
28
27
29
```PHP
28
-
// This example assumes use of the validator in the CMS, with the DataObjectDefaultAjaxExtension extension applied.
29
-
// If this was for frontend use, you would be well-advised to explicitly include a SimpleFieldsValidator.
30
+
// This example assumes use of the validator in the CMS, with the optional configuration applied.
30
31
public function getCMSCompositeValidator(): CompositeValidator
31
32
{
32
33
$validator = parent::getCMSCompositeValidator();
@@ -48,74 +49,29 @@ public function getCMSCompositeValidator(): CompositeValidator
48
49
}
49
50
```
50
51
51
-
### Known Issues
52
-
53
-
Some actions (such as delete, archive, and restore) should be allowed even if the data is not valid (we should be allowed to delete an object _especially_ if its data is invalid), but those actions are not validation exempt by default. [Two extensions](./02-extensions.md#dataobjectvalidationexemptionextension-and-gridfielditemrequestvalidationexemptionextension) are provided with this module to remedy this and we strongly recommend applying them.
52
+
### Exclude fields from AJAX validation
54
53
55
-
## SimpleFieldsValidator
54
+
You may also want to omit certain `FormField` subclasses from validation during AJAX validation calls, and only validate them during the final form submission.
56
55
57
-
This validator simply calls validate on all fields in the form, ensuring the internal validation of form fields. It should _always_ be included in an `AjaxCompositeValidator` unless some other validator being used also performs that function (such as Silverstripe's own `RequiredFields` validator - though you should generally use this module's `RequiredFieldsValidator` instead).
58
-
59
-
### Usage
56
+
This can be useful if (as in the case of the [undefinedoffset/silverstripe-nocaptcha](https://github.com/UndefinedOffset/silverstripe-nocaptcha) module's `NocaptchaField`) the field cannot be validated more than once with the same value.
60
57
61
-
In most situations this validator will require no configuration at all.
62
-
63
-
However, this validator comes with [an extension](02-extensions.md#formfieldextension) which adds `setOmitFieldValidation()` and `getOmitFieldValidation()` methods to all `FormField`s. This can be used if, for specific use cases, internal field validation should be conditional. In that case you can set `OmitFieldValidation` to true, and handle the conditional validation of the field in a separate validator.
64
-
65
-
```PHP
66
-
// In the DataObject which needs the custom validation
You may also want to omit certain `FormField` subclasses from validation during AJAX validation calls (assuming you're using the `AjaxCompositeValidator`), and only validate them during the final form submission. This can be useful if (as in the case of the [undefinedoffset/silverstripe-nocaptcha](https://github.com/UndefinedOffset/silverstripe-nocaptcha) module's `NocaptchaField`) the field cannot be validated more than once with the same value.
94
-
95
-
You can do this by setting the class name for that `FormField` in the `SimpleFieldsValidator`'s `ignore_field_classes_on_ajax` config array.
58
+
You can do this by setting the class name for that `FormField` in the `AjaxCompositeValidator`'s `remove_before_ajax_validation` config array.
That specific class is already added by default, but you can add others if you find similar situations.
104
67
105
-
## RequiredFieldsValidator
106
-
107
-
This is a composable replacement for [`RequiredFields`](https://api.silverstripe.org/4/SilverStripe/Forms/RequiredFields.html). It doesn't perform the internal field validation that validator does, with the assumption that it will be paired with a `SimpleFieldsValidator`. It uses (so has all of the functionality and methods of) the [`ValidatesMultipleFields`](#validatesmultiplefields) trait.
108
-
109
-
Displays a validation error if the field(s) has no value.
110
-
111
68
### Known Issues
112
69
113
-
While this validator can be used to require data in `GridField`s, as of writing this documentation GridFields don't display validation errors. This [was resolved](https://github.com/silverstripe/silverstripe-framework/pull/10015) in Silverstripe 4.10.0, but for anyone using an older version in the meantime [an extension](./02-extensions.md#gridfieldmessagesextension) is included with this module to fix this problem. The `AjaxCompositeValidator` will display validation error messages against GridFields even without that extension.
114
-
This applies to the `WarningFieldsValidator` as well.
70
+
Some actions (such as delete, archive, and restore) should be allowed even if the data is not valid (we should be allowed to delete an object _especially_ if its data is invalid), but those actions are not validation exempt by default. [Two extensions](./02-extensions.md#dataobjectvalidationexemptionextension-and-gridfielditemrequestvalidationexemptionextension) are provided with this module to remedy this and we strongly recommend applying them.
115
71
116
72
## WarningFieldsValidator
117
73
118
-
Similar to `RequiredFieldsValidator` except instead of blocking the item from saving, this allows the item to save and displays a warning rather than a full validation error. It uses (so has all of the functionality and methods of) the [`ValidatesMultipleFields`](#validatesmultiplefields) trait.
74
+
Similar to [`RequiredFieldsValidator`](https://api.silverstripe.org/6/SilverStripe/Forms/Validation/RequiredFields.html) except instead of blocking the item from saving, this allows the item to save and displays a warning rather than a full validation error. It uses (so has all of the functionality and methods of) the [`ValidatesMultipleFields`](#validatesmultiplefields) trait.
119
75
120
76
This can be very useful for alerting users about data that is technically valid but may not provide the results they expect.
121
77
@@ -240,29 +196,6 @@ See the Symfony [validation constraints reference](https://symfony.com/doc/curre
240
196
241
197
See [validation using `symfony/validator` constraints](https://docs.silverstripe.org/en/developer_guides/model/validation/#symfony-validator) in the Silverstripe CMS documentation for any limitations imposed by Silverstripe CMS itself on this kind of validation.
242
198
243
-
## RegexFieldsValidator
244
-
245
-
> [!WARNING]
246
-
> Deprecated! Use `ConstraintsValidator` with a [`Regex` constraint](https://symfony.com/doc/current/reference/constraints/Regex.html) instead.
247
-
248
-
This validator is used to require field values to match a specific regex pattern. Often it will make sense to have this validation inside a custom `FormField` implementation, but for one-off specific pattern validation of fields that don't warrant their own `FormField` this validator is perfect. It uses (so has all of the functionality and methods of) the [`ValidatesMultipleFieldsWithConfig`](#validatesmultiplefieldswithconfig) trait.
249
-
250
-
Any value that cannot be converted to a string cannot be checked against regex and so is ignored, and therefore implicitly passes validation.
251
-
252
-
In the below example, the `NotOnlyNumbersField` field must match one of the specified regex patterns.
253
-
254
-
```php
255
-
RegexFieldsValidator::create([
256
-
'NotOnlyNumbersField' => [
257
-
'/(?!^\d+$)^.*?$/' => 'must not consist entirely of numbers',
258
-
'/^[\d]$/' => 'must have only one digit',
259
-
]
260
-
]);
261
-
```
262
-
263
-
**Note:** If any one of the patterns is matched, it passes validation. If none of the patterns match, all of the corresponding messages are displayed, including a generic prefix. So in the above example, if none of the patterns match the value of `NotOnlyNumbersField`, the following validation error message will display:
264
-
`The value for "NotOnlyNumbersField" must not consist entirely of numbers or must have only one digit`
265
-
266
199
## Abstract Validators
267
200
268
201
### BaseValidator
@@ -283,7 +216,7 @@ It also has an abstract method `getValidationHints()` which has implications for
283
216
284
217
### FieldHasValueValidator
285
218
286
-
This abstract class is itself a subclass of `BaseValidator`, and is useful as a superclass for any validator that needs to check if fields have a value. This functionality is used in the [`RequiredFieldsValidator`](#requiredfieldsvalidator), [`WarningFieldsValidator`](#warningfieldsvalidator), and [`DependentRequiredFieldsValidator`](#dependentrequiredfieldsvalidator).
219
+
This abstract class is itself a subclass of `BaseValidator`, and is useful as a superclass for any validator that needs to check if fields have a value. This functionality is used in the [`WarningFieldsValidator`](#warningfieldsvalidator) and [`DependentRequiredFieldsValidator`](#dependentrequiredfieldsvalidator).
287
220
288
221
```php
289
222
// Get the actual FormField for the named field.
@@ -331,7 +264,7 @@ class MyFieldValueExtension extends Extension
331
264
332
265
## ValidatesMultipleFields
333
266
334
-
This trait is used in both the [`RequiredFieldsValidator`](#requiredfieldsvalidator) and [`WarningFieldsValidator`](#warningfieldsvalidator). It is useful for any validator that can be fed an array of field names that need to be validated.
267
+
This trait is used in the [`WarningFieldsValidator`](#warningfieldsvalidator). It is useful for any validator that can be fed an array of field names that need to be validated.
0 commit comments