guysartorelli/silverstripe-composable-validators

Adds composable form validators with reusable validation logic.

2.3.0 2024-03-19 22:38 UTC

Requires

• php: ^8.1
• silverstripe/framework: ^5.2

Requires (Dev)

• dnadesign/silverstripe-elemental: ^5
• silverstripe/asset-admin: ^2
• silverstripe/cms: ^5
• silverstripe/frameworktest: ^1
• silverstripe/recipe-testing: ^3

BSD-3-Clause

• Signify Ltd
• Guy Sartorelli

• form
• validator
• cms
• validation
• ajax
• validators
• Forms
• silverstripe
• frontend
• regex
• composite
• warning
• dependent
• composable
• required
• elemental
• CompositeValidator

README

Thank you to Signify for making this module possible.

This module provides a number of reusable composable validators (including AJAX validation) for use both in the CMS and in frontend forms.

Make sure you check out the extensions documentation at a minimum - some of these should be applied in almost all projects using this module.

If your project has any automated client-side tests, or you are implementing a validator to be compatible with this module, please make sure you read the client side tests documentation.

Install

Install via composer:

composer require guysartorelli/silverstripe-composable-validators

Gotchas

Form submission with an AjaxCompositeValidator

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.

If you're using the AjaxCompositeValidator on a form that uses undefinedoffset/silverstripe-nocaptcha 2.3.0 or higher, you should disable form submission handling for the NocaptchaField in that form (see instructions in the nocaptcha docs).

Available Validators

• AjaxCompositeValidator
  Subclass of CompositeValidator that provides AJAX validation. Resolves an issue with losing data, faster turn-around for fixing validation problems, and provides a way to use the same validation for 'client-side' validation of frontend forms.
• SimpleFieldsValidator
  Ensures the internal validation of form fields by calling validate() on them.
• RequiredFieldsValidator
  Like Silverstripe's RequiredFields validator, but more convenient for use in a CompositeValidator.
• WarningFieldsValidator
  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
• DependentRequiredFieldsValidator
  Uses SearchFilters to define fields as required conditionally, based on the values of other fields (e.g. only required if OtherField has a value greater than 25).
• RequiredBlocksValidator
  Require a specific elemental block(s) to exist in the ElementalArea, with optional minimum and maximum numbers of blocks and optional positional validation.
• ConstraintsValidator
  Validate values against symfony/validation constraints. This is super powerful - definitely check it out.
• RegexFieldsValidator (deprecated)
  Ensure some field(s) matches a specified regex pattern.

Abstract Validators

• BaseValidator
  Includes methods useful for getting the actual FormField and its label.
• FieldHasValueValidator
  Subclass of BaseValidator. Useful for validators that require logic to check if a field has any value or not.

Traits

• ValidatesMultipleFields
  Useful for validators that can be fed an array of field names to be validated.
• ValidatesMultipleFieldsWithConfig
  Like ValidatesMultipleFields but requires a configuration array for each field to be validated.