innoweb / silverstripe-form-validation
Adds Bouncer.js form validation to frontend forms.
Installs: 454
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 3
Forks: 1
Open Issues: 0
Language:JavaScript
Type:silverstripe-vendormodule
Requires
README
Introduction
Adds automatic form validation for frontend forms using the Bouncer.js library. This replaces the default HTML5 field validation to improve and unify the layout of error messages accross browsers.
This doesn't replace backend form validation. Backend validation should still be done using the default SS validator (e.g. RequiredFields).
It leaves UserForms forms alone as they are too heavily dependant on jQuery.
Requirements
- SilverStripe ^5
Note: this version is compatible with Silverstripe 5. For Silverstripe 4, please see the 1 release line.
Installation
Install the module using composer:
composer require innoweb/silverstripe-form-validation dev-master
Then run dev/build.
Configuration
No configuration required. By default, all frontend forms are being validated based on their HTML5 properties.
Disable validation
If you want to exclude a form from validation, you can disable it in code:
$form = Form::create($controller, 'MyForm', $fields, $actions, $validator); $form->disableFrontendValidation();
This add the class js-no-validation
to the form tag.
To skip validation for specific buttons, you can add the class skip-validation
to the button.
Disable form submission
To disable the default form submission, you can disable it in code:
$form = Form::create($controller, 'MyForm', $fields, $actions, $validator); $form->disableFormSubmission();
This adds the class js-disable-submit
to the form tag.
This is useful if you want to submit the form via AJAX. To submit the form, you can listen to the bouncerFormValid
event in JavaScript:
form.addEventListener('bouncerFormValid', function (event) { ... }, false);
Add Custom Validators
You can inject custom JavaScript validators for certain fields. To do so, you need to extend FormField
as follows:
SilverStripe\Forms\FormField: extensions: - Your\Custom\ValidationExtension
Use the addCustomValidatorScripts
extension hook to inject your JavaScript validator:
class ValidationExtension extends Extension { // needs to be run on base FormField class, otherwise it's not going to be loaded on time public function addCustomValidatorScripts() { Requirements::javascript( 'your/custom/field-validation.js' ); } }
In your field-validation.js
you need to add your validator definition to the global bouncerValidators
variable:
window.bouncerValidators = window.bouncerValidators || {}; window.bouncerValidators.yourCustomValidator = { validator: function(field) { if (field.classList.contains('YourCustomField')) { // limit validator to your custom field type if (...) { // return true if field is NOT valid return true; } } // return false if field is valid! return false; }, message: 'Please enter a valid value' };
License
BSD 3-Clause License, see License