From 02eb11f42ed85375b7d2076d19c4effaddcf63af Mon Sep 17 00:00:00 2001 From: Steve Boyd Date: Tue, 10 Dec 2024 10:58:07 +1300 Subject: [PATCH] DOC Rename validator classes --- .../03_Forms/00_Introduction.md | 10 +++--- .../03_Forms/01_Validation.md | 34 +++++++++---------- .../03_Forms/How_Tos/01_Encapsulate_Forms.md | 8 ++--- .../How_Tos/05_Simple_Contact_Form.md | 8 ++--- .../03_Forms/How_Tos/06_Handle_Nested_data.md | 12 +++---- en/08_Changelogs/6.0.0.md | 10 ++++++ 6 files changed, 46 insertions(+), 36 deletions(-) diff --git a/en/02_Developer_Guides/03_Forms/00_Introduction.md b/en/02_Developer_Guides/03_Forms/00_Introduction.md index 4c769ebfc..5270b8c08 100644 --- a/en/02_Developer_Guides/03_Forms/00_Introduction.md +++ b/en/02_Developer_Guides/03_Forms/00_Introduction.md @@ -40,8 +40,8 @@ use PageController; use SilverStripe\Forms\FieldList; use SilverStripe\Forms\Form; use SilverStripe\Forms\FormAction; -use SilverStripe\Forms\RequiredFields; use SilverStripe\Forms\TextField; +use SilverStripe\Forms\Validation\RequiredFieldsValidator; class MyFormPageController extends PageController { @@ -63,7 +63,7 @@ class MyFormPageController extends PageController FormAction::create('doSayHello')->setTitle('Say hello') ); - $required = RequiredFields::create('Name'); + $required = RequiredFieldsValidator::create('Name'); $form = Form::create($this, 'HelloForm', $fields, $actions, $required); @@ -403,7 +403,7 @@ See [how_tos/handle_nested_data](How to: Handle nested form data) for more advan ## Validation -Form validation is handled by the [Validator](api:SilverStripe\Forms\Validator) class and the `validator` property on the `Form` object. The validator +Form validation is handled by the [Validator](api:SilverStripe\Forms\Validation\Validator) class and the `validator` property on the `Form` object. The validator is provided with a name of each of the [FormField](api:SilverStripe\Forms\FormField)s to validate and each `FormField` instance is responsible for validating its' own data value. @@ -414,7 +414,7 @@ namespace App\PageType; use PageController; use SilverStripe\Forms\Form; -use SilverStripe\Forms\RequiredFields; +use SilverStripe\Forms\Validation\RequiredFieldsValidator; class MyFormPageController extends PageController { @@ -424,7 +424,7 @@ class MyFormPageController extends PageController { // ... - $validator = RequiredFields::create([ + $validator = RequiredFieldsValidator::create([ 'Name', 'Email', ]); diff --git a/en/02_Developer_Guides/03_Forms/01_Validation.md b/en/02_Developer_Guides/03_Forms/01_Validation.md index 15d43e8fd..31d5c3f41 100644 --- a/en/02_Developer_Guides/03_Forms/01_Validation.md +++ b/en/02_Developer_Guides/03_Forms/01_Validation.md @@ -10,7 +10,7 @@ icon: check-square > Before you start implementing custom validation logic, check out [validation using `symfony/validator` constraints](/developer_guides/model/validation/#validation-and-constraints) > and see if there's an existing constraint that can do the heavy lifting for you. -Silverstripe CMS provides server-side form validation out of the box through the [Validator](api:SilverStripe\Forms\Validator) abstract class and its' child classes +Silverstripe CMS provides server-side form validation out of the box through the [Validator](api:SilverStripe\Forms\Validation\Validator) abstract class and its' child classes (see [available validators](#available-validators) below). A single `Validator` instance is set on each `Form`. Validators are implemented as an argument to the [Form](api:SilverStripe\Forms\Form) constructor or through the function `setValidator`. @@ -21,8 +21,8 @@ use PageController; use SilverStripe\Forms\EmailField; use SilverStripe\Forms\Form; use SilverStripe\Forms\FormAction; -use SilverStripe\Forms\RequiredFields; use SilverStripe\Forms\TextField; +use SilverStripe\Forms\Validation\RequiredFieldsValidator; class MyFormPageController extends PageController { @@ -46,7 +46,7 @@ class MyFormPageController extends PageController ); // the fields 'Name' and 'Email' are required. - $required = RequiredFields::create([ + $required = RequiredFieldsValidator::create([ 'Name', 'Email', ]); @@ -166,7 +166,7 @@ class CustomEmailField extends EmailField ### `ValidationException` At times it's not possible for all validation or recoverable errors to be pre-determined in advance of form -submission, such as those generated by the form [Validator](api:SilverStripe\Forms\Validator). Sometimes errors may occur within form +submission, such as those generated by the form [Validator](api:SilverStripe\Forms\Validation\Validator). Sometimes errors may occur within form action methods, and it is necessary to display errors on the form after initial validation has been performed. In this case you may throw a [`ValidationException`](api:SilverStripe\Core\Validation\ValidationException) within your handler, optionally passing it an @@ -237,7 +237,7 @@ class MyFormPageController extends PageController public function doSubmitForm($data, $form) { - // At this point, RequiredFields->isValid() will have been called already, + // At this point, RequiredFieldsValidator->isValid() will have been called already, // so we can assume that the values exist. Say we want to make sure that email hasn't already been used. $check = Member::get()->filter('Email', $data['Email'])->first(); @@ -262,12 +262,12 @@ class MyFormPageController extends PageController The Silverstripe framework comes with the following built-in validators: -- [`CompositeValidator`](api:SilverStripe\Forms\CompositeValidator) +- [`CompositeValidator`](api:SilverStripe\Forms\Validation\CompositeValidator) A container for additional validators. You can implement discrete validation logic in multiple `Validator` subclasses and apply them *all* to a given form by putting them inside a `CompositeValidator`. The `CompositeValidator` doesn't have perform any validation by itself. - [`FieldsValidator`](api:SilverStripe\Forms\FieldsValidator) Simply calls [`validate()`](api:SilverStripe\Forms\FormField::validate()) on all data fields in the form, to ensure fields have valid values. -- [`RequiredFields`](api:SilverStripe\Forms\RequiredFields) +- [`RequiredFieldsValidator`](api:SilverStripe\Forms\Validation\RequiredFieldsValidator) Validates that fields you declare as "required" have a value. There are additional validators available in community modules, and you can implement your own validators by subclassing the abstract `Validator` class. @@ -383,10 +383,10 @@ respect the provided `Validator`/s and handle displaying error and success respo namespace App\PageType; use Page; -use SilverStripe\Forms\CompositeValidator; +use SilverStripe\Forms\Validation\CompositeValidator; use SilverStripe\Forms\FieldList; -use SilverStripe\Forms\RequiredFields; use SilverStripe\Forms\TextField; +use SilverStripe\Forms\Validation\RequiredFieldsValidator; class MyPage extends Page { @@ -408,7 +408,7 @@ class MyPage extends Page public function getCMSCompositeValidator(): CompositeValidator { $validator = parent::getCMSCompositeValidator(); - $validator->addValidator(RequiredFields::create([ + $validator->addValidator(RequiredFieldsValidator::create([ 'MyRequiredField', ])); return $validator; @@ -420,13 +420,13 @@ class MyPage extends Page > You can also update the `CompositeValidator` by creating an `Extension` and implementing the > `updateCMSCompositeValidator()` method. -### `RequiredFields` and whitespace +### `RequiredFieldsValidator` 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()). +By default, `RequiredFieldsValidator` will consider a field with only whitespace as a valid value. You an change this behavior with the [`allow_whitespace_only`](api:SilverStripe\Forms\Validation\RequiredFieldsValidator->allow_whitespace_only) global configuration, or on a per-instance basis using [`setAllowWhitespaceOnly()`](api:SilverStripe\Forms\Validation\RequiredFieldsValidator::setAllowWhitespaceOnly()). ```yml # global configuration -SilverStripe\Forms\RequiredFields: +SilverStripe\Forms\Validation\RequiredFieldsValidator: allow_whitespace_only: false ``` @@ -435,7 +435,7 @@ namespace App\PageType; use Page; use SilverStripe\Forms\CompositeValidator; -use SilverStripe\Forms\RequiredFields; +use SilverStripe\Forms\Validation\RequiredFieldsValidator; class MyPage extends Page { @@ -444,7 +444,7 @@ class MyPage extends Page public function getCMSCompositeValidator(): CompositeValidator { $validator = parent::getCMSCompositeValidator(); - $requiredFields = RequiredFields::create(['MyRequiredField']); + $requiredFields = RequiredFieldsValidator::create(['MyRequiredField']); // per instance configuration, will override global configuration $requiredFields->setAllowWhitespaceOnly(false); $validator->addValidator($requiredFields); @@ -459,5 +459,5 @@ class MyPage extends Page ## API documentation -- [RequiredFields](api:SilverStripe\Forms\RequiredFields) -- [Validator](api:SilverStripe\Forms\Validator) +- [RequiredFieldsValidator](api:SilverStripe\Forms\Validation\RequiredFieldsValidator) +- [Validator](api:SilverStripe\Forms\Validation\Validator) diff --git a/en/02_Developer_Guides/03_Forms/How_Tos/01_Encapsulate_Forms.md b/en/02_Developer_Guides/03_Forms/How_Tos/01_Encapsulate_Forms.md index fc63868b9..21604f112 100644 --- a/en/02_Developer_Guides/03_Forms/How_Tos/01_Encapsulate_Forms.md +++ b/en/02_Developer_Guides/03_Forms/How_Tos/01_Encapsulate_Forms.md @@ -24,7 +24,7 @@ use SilverStripe\Forms\FormAction; use SilverStripe\Forms\HeaderField; use SilverStripe\Forms\NumericField; use SilverStripe\Forms\OptionsetField; -use SilverStripe\Forms\RequiredFields; +use SilverStripe\Forms\Validation\RequiredFieldsValidator; class SearchPageController extends PageController { @@ -57,7 +57,7 @@ class SearchPageController extends PageController FormAction::create('doSearchForm', 'Search') ); - $required = RequiredFields::create([ + $required = RequiredFieldsValidator::create([ 'Type', ]); @@ -92,7 +92,7 @@ use SilverStripe\Forms\FormAction; use SilverStripe\Forms\HeaderField; use SilverStripe\Forms\NumericField; use SilverStripe\Forms\OptionsetField; -use SilverStripe\Forms\RequiredFields; +use SilverStripe\Forms\Validation\RequiredFieldsValidator; class SearchForm extends Form { @@ -127,7 +127,7 @@ class SearchForm extends Form FormAction::create('doSearchForm', 'Search') ); - $required = RequiredFields::create([ + $required = RequiredFieldsValidator::create([ 'Type', ]); diff --git a/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md b/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md index 017e82621..739919bc7 100644 --- a/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md +++ b/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md @@ -151,14 +151,14 @@ The final thing we do is return a 'thank you for your feedback' message to the u All forms have some basic validation built in – email fields will only let the user enter email addresses, number fields will only accept numbers, and so on. Sometimes you need more complicated validation, so you can define your own validation by extending the Validator class. -The framework comes with a predefined validator called [RequiredFields](api:SilverStripe\Forms\RequiredFields), which performs the common task of making sure particular fields are filled out. Below is the code to add validation to a contact form: +The framework comes with a predefined validator called [`RequiredFieldsValidator`](api:SilverStripe\Forms\Validation\RequiredFieldsValidator), which performs the common task of making sure particular fields are filled out. Below is the code to add validation to a contact form: ```php namespace App\PageType; use PageController; use SilverStripe\Forms\Form; -use SilverStripe\Forms\RequiredFields; +use SilverStripe\Forms\Validation\RequiredFieldsValidator; class ContactPageController extends PageController { @@ -167,10 +167,10 @@ class ContactPageController extends PageController public function getForm() { // ... - $validator = RequiredFields::create('Name', 'Message'); + $validator = RequiredFieldsValidator::create('Name', 'Message'); return Form::create($this, 'Form', $fields, $actions, $validator); } } ``` -We've created a RequiredFields object, passing the name of the fields we want to be required. The validator we have created is then passed as the fifth argument of the form constructor. If we now try to submit the form without filling out the required fields, JavaScript validation will kick in, and the user will be presented with a message about the missing fields. If the user has JavaScript disabled, PHP validation will kick in when the form is submitted, and the user will be redirected back to the Form with messages about their missing fields. +We've created a RequiredFieldsValidator object, passing the name of the fields we want to be required. The validator we have created is then passed as the fifth argument of the form constructor. If we now try to submit the form without filling out the required fields, JavaScript validation will kick in, and the user will be presented with a message about the missing fields. If the user has JavaScript disabled, PHP validation will kick in when the form is submitted, and the user will be redirected back to the Form with messages about their missing fields. diff --git a/en/02_Developer_Guides/03_Forms/How_Tos/06_Handle_Nested_data.md b/en/02_Developer_Guides/03_Forms/How_Tos/06_Handle_Nested_data.md index c43521d83..b47695ac2 100644 --- a/en/02_Developer_Guides/03_Forms/How_Tos/06_Handle_Nested_data.md +++ b/en/02_Developer_Guides/03_Forms/How_Tos/06_Handle_Nested_data.md @@ -69,8 +69,8 @@ use SilverStripe\Forms\FieldList; use SilverStripe\Forms\Form; use SilverStripe\Forms\FormAction; use SilverStripe\Forms\HiddenField; -use SilverStripe\Forms\RequiredFields; use SilverStripe\Forms\TextField; +use SilverStripe\Forms\Validation\RequiredFieldsValidator; class MyController extends Controller { @@ -99,7 +99,7 @@ class MyController extends Controller FieldList::create([ FormAction::create('doSubmitForm', 'Submit'), ]), - RequiredFields::create([ + RequiredFieldsValidator::create([ 'Name', 'Teams', 'ID', @@ -149,8 +149,8 @@ use SilverStripe\Forms\FieldList; use SilverStripe\Forms\Form; use SilverStripe\Forms\FormAction; use SilverStripe\Forms\HiddenField; -use SilverStripe\Forms\RequiredFields; use SilverStripe\Forms\TextField; +use SilverStripe\Forms\Validation\RequiredFieldsValidator; class MyController extends Controller { @@ -177,7 +177,7 @@ class MyController extends Controller FieldList::create([ FormAction::create('doSubmitForm', 'Submit'), ]), - RequiredFields::create([ + RequiredFieldsValidator::create([ 'Name', 'HometownTeam.Name', 'ID', @@ -232,8 +232,8 @@ use SilverStripe\Forms\FieldList; use SilverStripe\Forms\Form; use SilverStripe\Forms\FormAction; use SilverStripe\Forms\HiddenField; -use SilverStripe\Forms\RequiredFields; use SilverStripe\Forms\TextField; +use SilverStripe\Forms\Validation\RequiredFieldsValidator; class MyController extends Controller { @@ -262,7 +262,7 @@ class MyController extends Controller FieldList::create([ FormAction::create('doSubmitForm', 'Submit'), ]), - RequiredFields::create([ + RequiredFieldsValidator::create([ 'Name', 'MyTeams[]', 'ID', diff --git a/en/08_Changelogs/6.0.0.md b/en/08_Changelogs/6.0.0.md index 4486f12ac..013fd9ed3 100644 --- a/en/08_Changelogs/6.0.0.md +++ b/en/08_Changelogs/6.0.0.md @@ -898,6 +898,16 @@ The following classes have been changed when code was moved to the `silverstripe |`SilverStripe\ExternalLinks\Tasks\CurlLinkChecker`|[`SilverStripe\Reports\ExternalLinks\Tasks\CurlLinkChecker`](api:SilverStripe\Reports\ExternalLinks\Tasks\CurlLinkChecker)| |`SilverStripe\ExternalLinks\Tasks\LinkChecker`|[`SilverStripe\Reports\ExternalLinks\Tasks\LinkChecker`](api:SilverStripe\Reports\ExternalLinks\Tasks\LinkChecker)| +[`Validator`](api:SilverStripe\Forms\Validation\Validator) and its subclasses have been renamed: + +|Old FQCN|New FQCN| +|---|---| +|`SilverStripe\Forms\Validator`|[`SilverStripe\Forms\Validator`](api:SilverStripe\Forms\Validator)| +|`SilverStripe\Forms\RequiredFields`|[`SilverStripe\Forms\RequiredFieldsValidator`](api:SilverStripe\Forms\RequiredFieldsValidator)| +|`SilverStripe\Forms\CompositeValidator`|[`SilverStripe\Forms\Validation\CompositeValidator`](api:SilverStripe\Forms\Validation\CompositeValidator)| +|`SilverStripe\UserForms\Form\UserFormsRequiredFields`|[`SilverStripe\UserForms\Form\UserFormsRequiredFieldsValidator`](api:SilverStripe\UserForms\Form\UserFormsRequiredFieldsValidator)| +|`Symbiote\AdvancedWorkflow\Forms\AWRequiredFields`|[`Symbiote\AdvancedWorkflow\Forms\AWRequiredFieldsValidator`](api:Symbiote\AdvancedWorkflow\Forms\AWRequiredFieldsValidator)| + ### GraphQL removed from the CMS {#graphql-removed} > [!NOTE]