Form Validation
- PIPEFORCE
What is Form Validation?
Every time a form data is entered into a form widget, it must be checked whether this form data complies with a given set of rules. If not, the user must be informed that his input value is not valid. This is called Form Validation in PIPEFORCE Forms.
Basic validations regarding data types will be specified by the underlying Form Schema of the form like the data type of a form or number ranges for example.
In order to create more specific custom validation rules for form fields, you can add the validation attribute to each field in the Form Config. For example:
{
"title": "Person",
"description": "A person form",
...
"layout": {
"items": [
{
"field": "firstName",
"validation":[
{ "type":"js", "rule":"!!val", "message": "Field is required!" },
{ "type":"js", "rule":"val.length > 2", "message": "Must be longer than 2 chars!" }
]
},
...
]
}
}
You can define as many validation rules inside the validation array as you want. All of them will be executed in case the focus on the widget has been lost. They will then be executed in the order they are specified in the list from top to down. The first one, which fails, will be shown to the user as a validation message. Such a message could look like this:
Each validation rule entry is of this format:
{ "type":"TYPE", "rule":"EXPRESSION", "message": "MESSAGE" }The optional type attribute defines the type of the validation engine. If not defined, this is by default set tojs which validates using a JavaScript expression. In future, there will be different validation engines available here.
rule defines the rule expression to be applied. The return value of this rule must be true in order to have a valid field value.
message defines the message to be displayed in case this validation has failed. This can be a fixed text message or a i18n URI. See TODO.
Validation Rules (JavaScript)
By default, the js validation engine is used which is using JavaScript expressions for validation checks. This engine is used in case no specific type was defined.
The engine takes a JavaScript expression using the rule attribute and evaluates it on the input value of a widget. In case it evaluates to false, the message given by attribute message is shown.
The input value of the widget can be accessed using the val variable. It can then be used inside the rule expression.
For some examples see below.
Since js is the default validation rule, "type": "js" is omitted in the examples below.
See here for a full JavaScript language reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference
Example: Field is required
The given widget is a required one. Therefore, make sure this widget has a value. In case it has not value, !val will return true. So we have to negate it with an additional ! in order to activate the validation rule and show the message:
{
"rule":"!!val",
"message": "Field is required!"
}This will produce the Field is required! message if the respective field is not given.
The expression !!val is just a shorter form of !(val == null)
Example: Number ranges (min / max)
In order to ensure that the given number input is below a given maximum:
{
"rule": "val < 1000",
"message": "Number cannot be or exceed 1000"
}Make sure that the given string input has not more than 150 characters:
{
"rule":"val.length <= 150",
"message": "Field may not contain more than 150 characters!"
}For all JavaScript Number functions, see: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
Example: Text matching
Make sure the given input contains the word Hello:
{
"rule":"val.includes('Hello')",
"message": "Field must contain word Hello!"
}For all JavaScript String functions, see: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String?retiredLocale=de
Example: Valid email address
Make sure the given input is an email (simple approach):
{
"rule":"val.indexOf('@'') > 0",
"message": "Field must contain a valid email!"
}Make sure the given input is an email (advanced approach with regex):
{
"rule":"/\S+@\S+\.\S+/.test(val)",
"message": "Field must contain a valid email!"
}Internationalization (i18n)
Validation messages can be internationalized (= translated to different languages). See here for more details, how this works: Internationalization (i18n).