SilverWare Validator
, (*1)
A form validation module for SilverStripe v4 which supports alternative
client-side backends and customisable validation rules. Ships with Parsley.js as the
default validation backend. Configured out-of-the-box for use with Bootstrap v4 forms., (*2)
Contents
Requirements
Installation
Installation is via Composer:, (*3)
$ composer require silverware/validator
Configuration
As with all SilverStripe modules, configuration is via YAML. The SilverStripe dependency injector is
used to configure the validator backend. The module ships with a backend that uses Parsley.js:, (*4)
SilverStripe\Core\Injector\Injector:
ValidatorBackend:
class: SilverWare\Validator\Backends\ParsleyBackend
The module has been designed to be as "backend agnostic" as possible. While Parsley.js is very powerful and
should cater for most validation needs, you could certainly roll your own backend implementation and integrate
it into the validator frontend using configuration., (*5)
Usage
To make use of the validator in your app, simply use the validator class in the header of your code:, (*6)
use SilverWare\Validator\Validator;
You will also need to use the validator rule classes you wish to apply to your form,
for example:, (*7)
use SilverWare\Validator\Rules\LengthRule;
use SilverWare\Validator\Rules\PatternRule;
use SilverWare\Validator\Rules\RequiredRule;
Create a validator instance in your controller method that returns the Form,
for example:, (*8)
public function Form()
{
$fields = FieldList::create([
...
]);
$actions = FieldList::create([
...
]);
$validator = Validator::create();
// define validator rules here!
$form = Form::create($this, 'Form', $fields, $actions, $validator);
return $form;
}
Now you can define your validator rules using the methods shown below., (*9)
Validator Rules
SilverWare Validator ships with many pre-built rules which you can use
straight away to validate your forms. These rules support both client-side
and server-side validation. Included with SilverWare Validator are the
following rule classes:, (*10)
Each of these rules will be covered in greater detail below., (*11)
Setting Rules
To set a rule for a particular form field, use the setRule method,
and pass the field name and the rule instance. For example:, (*12)
$validator->setRule(
'MyFieldName',
LengthRule::create(10, 20) // this field's value must be 10-20 characters in length
);
To set more than one rule for a field, you can use the setRules method and pass an
array of rule instances:, (*13)
$validator->setRules(
'MyDomainName',
[
RequiredRule::create(), // this field is required
DomainRule::create() // this field must be a valid domain name
]
);
Required Fields
Since fields are often required for almost any form, shortcut methods
have been provided to define required fields. Use addRequiredField with the
field name and optional custom message parameter:, (*14)
$validator->addRequiredField('MyRequiredField');
$validator->addRequiredField('MyOtherRequiredField', 'Dis field be mandatory, yo!');
To add required fields in bulk, use addRequiredFields with an
array of field names:, (*15)
$validator->addRequiredFields([
'ThisFieldIsRequired',
'SoIsThisField',
'AndThisField'
]);
Custom Messages
All rule classes come with a default message which is shown to the
user when the rule validation fails. You can define your own custom
messages by using the setMessage method on a rule, for example:, (*16)
$validator->setRule(
'MyAge',
MaxRule::create(130)->setMessage(
'I find it hard to believe you are over 130 years old!'
)
)
Disabling Validation
By default, SilverWare Validator performs both client-side and
server-side validation. While it's recommended to leave both
methods of validation enabled, if you need to disable either, you can
use the following methods:, (*17)
$validator->setClientSide(false); // disables client-side validation
$validator->setServerSide(false); // disables server-side validation
Trigger Events
The out-of-the-box validator Parsley.js is set to trigger form validation
upon field change by default. You can customise when you'd like validation to
be triggered by using the setTriggerOn method on the backend, for example:, (*18)
$validator->getBackend()->setTriggerOn([
'focusin',
'focusout'
]);
You can also simply pass the trigger events as a string:, (*19)
$validator->getBackend()->setTriggerOn('focusin focusout');
Parsley.js supports triggering by any of the standard jQuery events., (*20)
Rules
AlphaNumRule
use SilverWare\Validator\Rules\AlphaNumRule;
Tests that the value is an alphanumeric string, containing only basic letters, numbers,
and the underscore character., (*21)
$validator->setRule(
'MyFieldName',
AlphaNumRule::create()
);
CheckRule
use SilverWare\Validator\Rules\CheckRule;
Used for a OptionsetField such as CheckboxSetField. Ensures that
the user chooses a certain number of options, between the given
$min and $max parameters., (*22)
$validator->setRule(
'MyCheckboxSet',
CheckRule::create(2, 4) // user must select between 2 and 4 options
);
ComparisonRule
use SilverWare\Validator\Rules\ComparisonRule;
Compares the value of one field to another, using the specified comparison type:, (*23)
ComparisonRule::LESS_THANComparisonRule::LESS_THAN_OR_EQUALComparisonRule::GREATER_THANComparisonRule::GREATER_THAN_OR_EQUAL
$validator->setRule(
'MyLesserValue',
ComparisonRule::create(
ComparisonRule::GREATER_THAN,
'MyGreaterValue'
)
);
DateRule
use SilverWare\Validator\Rules\DateRule;
Ensures that the entered value is a date of the specified format.
The rule constructor supports two arguments. The first is the
required date format using the client-side Moment.js specification., (*24)
The optional second argument specifies the server-side PHP date format,
however the rule will convert the client-side format appropriately if
you omit the second argument., (*25)
$validator->setRule(
'MyDateField',
DateRule::create('YYYY-MM-DD') // ensures an ISO standard date, e.g. 2017-05-12
);
DigitsRule
use SilverWare\Validator\Rules\DigitsRule;
Ensures only digits are entered, i.e. the numbers 0-9 only., (*26)
$validator->setRule(
'MyDigitsField',
DigitsRule::create()
);
DomainRule
use SilverWare\Validator\Rules\DomainRule;
Tests that the entered value is a valid domain name. Supports the
new TLD domains and also localhost., (*27)
$validator->setRule(
'MyDomainName',
DomainRule::create()
);
EmailRule
use SilverWare\Validator\Rules\EmailRule;
Ensures that the value is a valid email address., (*28)
$validator->setRule(
'MyEmailField',
EmailRule::create()
);
EqualToRule
use SilverWare\Validator\Rules\EqualToRule;
Ensures that the value of one field is equal to the value of another., (*29)
$validator->setRule(
'MyFirstValue',
EqualToRule::create('MySecondValue')
);
IntegerRule
use SilverWare\Validator\Rules\IntegerRule;
Tests that the entered value is a valid positive or negative integer., (*30)
$validator->setRule(
'MyIntField',
IntegerRule::create()
);
LengthRule
use SilverWare\Validator\Rules\LengthRule;
Ensures that the length of the entered value is between the specified $min and $max range., (*31)
$validator->setRule(
'MyFieldName',
LengthRule::create(20, 40) // value must be between 20-40 characters in length
);
MaxCheckRule
use SilverWare\Validator\Rules\MaxCheckRule;
Used for a OptionsetField such as CheckboxSetField. Specifies that
the user may only select a maximum number of options., (*32)
$validator->setRule(
'MyCheckboxSet',
MaxCheckRule::create(4) // user can select a maximum of 4 options
);
MaxLengthRule
use SilverWare\Validator\Rules\MaxLengthRule;
Ensures that the entered value is of a maximum length., (*33)
$validator->setRule(
'MyFieldName',
MaxLengthRule::create(40) // value must be 40 characters in length or less
);
MaxRule
use SilverWare\Validator\Rules\MaxRule;
Tests that a numeric value is less than or equal to the specified amount., (*34)
$validator->setRule(
'MyNumberField',
MaxRule::create(255) // number value must be 255 or less
);
MaxWordsRule
use SilverWare\Validator\Rules\MaxWordsRule;
Ensures that the value is of the specified number of words or less., (*35)
$validator->setRule(
'MyTextArea',
MaxWordsRule::create(50) // value must be 50 words or less
);
MinCheckRule
use SilverWare\Validator\Rules\MinCheckRule;
Used for a OptionsetField such as CheckboxSetField. Ensures that
the user selects a minimum number of options., (*36)
$validator->setRule(
'MyCheckboxSet',
MinCheckRule::create(2) // user must select at least 2 options
);
MinLengthRule
use SilverWare\Validator\Rules\MinLengthRule;
Ensures that the entered value is of a minimum length., (*37)
$validator->setRule(
'MyFieldName',
MinLengthRule::create(20) // value must be at least 20 characters in length
);
MinRule
use SilverWare\Validator\Rules\MinRule;
Tests that the numeric value is greater than or equal to the specified amount., (*38)
$validator->setRule(
'MyNumberField',
MinRule::create(42) // the entered value must be 42 or greater
);
MinWordsRule
use SilverWare\Validator\Rules\MinWordsRule;
Ensures that the entered value is of the specified number of words or greater., (*39)
$validator->setRule(
'MyTextArea',
MinWordsRule::create(20) // value must contain at least 20 words
);
NotEqualToRule
use SilverWare\Validator\Rules\NotEqualToRule;
Ensures that the value of one field is NOT equal to the value of another., (*40)
$validator->setRule(
'MyFirstValue',
NotEqualToRule::create('MySecondValue')
);
NumberRule
use SilverWare\Validator\Rules\NumberRule;
Tests that the entered value is numeric, i.e. an integer or a
floating-point number., (*41)
$validator->setRule(
'MyNumericValue',
NumberRule::create() // value must be numeric
);
PatternRule
use SilverWare\Validator\Rules\PatternRule;
Uses a regular expression to test the entered value. Ensure that the
format of your regular expression works in both JavaScript, and also
PHP preg_match so that both client and server validation functions correctly., (*42)
$validator->setRule(
'MyFieldName',
PatternRule::create('/ware$/') // ensures the entered string ends with 'ware'
);
RangeRule
use SilverWare\Validator\Rules\RangeRule;
Specifies a number range that the entered value must be between., (*43)
$validator->setRule(
'MyNumericValue',
RangeRule::create(1, 5) // value must be between 1 and 5
);
RemoteRule
use SilverWare\Validator\Rules\RemoteRule;
Tests the value on the client-side using an Ajax request, and uses
Guzzle to test the value when submitted to the server., (*44)
The following arguments are permitted for the rule constructor:, (*45)
$rule = RemoteRule::create(
$url, // url to call
$params, // request parameters, e.g. ['myVar' => 123]
$options, // options for request, e.g. ['type' => 'POST']
$remoteValidator // remote validator to use, 'default' or 'reverse'
);
For example, you might use the RemoteRule to check if a
username is available:, (*46)
$validator->setRule(
'MyUserName',
RemoteRule::create(
$this->Link('checkusername') // controller method
)->setMessage('That username is unavailable')
);
The server will receive the name of the field and it's value
as parameters, i.e. ?MyUserName=sallybloggs.
By default, if the RemoteRule receives an HTTP status code of
between 200-299, it is considered to be valid. Anything else will
return an invalid result., (*47)
If you'd like to reverse this behavior, i.e. 200-299 is considered
to be invalid, you can use "reverse" mode:, (*48)
$validator->setRule(
'MyUserName',
RemoteRule::create(
$this->Link('checkusername')
)->setRemoteValidator('reverse')
);
For more information on using remote validation, see the
Parsley.js documentation., (*49)
RequiredRule
use SilverWare\Validator\Rules\RequiredRule;
Defines the specified field as a required (mandatory) field that
must be completed by the user., (*50)
$validator->setRule(
'MyRequiredField',
RequiredRule::create()
);
URLRule
use SilverWare\Validator\Rules\URLRule;
Ensures that the entered value is a valid URL., (*51)
$validator->setRule(
'MyURL',
URLRule::create()
);
WordsRule
use SilverWare\Validator\Rules\WordsRule;
Ensures that the entered value is between $min and $max words., (*52)
$validator->setRule(
'MyTextArea',
WordsRule::create(10, 25) // user must enter between 10 and 25 words
);
Issues
Please use the GitHub issue tracker for bug reports and feature requests., (*53)
To-Do
Contribution
Your contributions are gladly welcomed to help make this project better.
Please see contributing for more information., (*54)
Attribution
Maintainers
License
BSD-3-Clause © Praxis Interactive, (*55)
Wallogit.com
