Wiki source code of Validatoren

Show last authors
1 {{content/}}
2
3
4 {{figure image="designer_validators_datatypes_en.png"}}
5 Many common datatypes are built-in and can be used easily. If necessary, you can also define your own datatypes via JavaScript, regexps or plugins.
6 {{/figure}}
7
8 Text fields may contain arbitrary text. Often you want to restrict this, such as allowing only valid email addresses or phone numbers. This aids the user when they fill out your form and informs them early about potential errors. This is done by adding a validator to a text field.
9
10 == Built-in validators ==
11
12 For many commonly used datatypes there are built-in validators provided by {{formcycle/}}. You can select the datatype in the constraints sections of the properties panel.
13
14 When you create a form in multiple languages, you would also want to translate the error messages. You can view and edit the error message texts in the [[i18n variabels tempalte>>doc:Formcycle.UserInterface.FilesAndTemplates.I18nVariables]].
15
16 The following built-in validators are available:
17
18 {{table dataTypeAlpha="0-1" preSort="1-asc" colWidth="150-150-400"}}
19 |=Name|= XM_FORM_VRULES|=Description
20 |Text|-|Default setting. The input won't be validated. All characters are allowed.
21 |Letters & spaces|onlyLetterSp|Only letters (UTF-8) and spaces are allowed, including characters with diacritics (ö, ü, ä, é etc.).
22 |Letters, numbers and spaces|onlyLetterNumber|Only letters (UTF-8), numbers, and spaces are allowed, including characters with diacritics (ö, ü, ä, é etc.).
23 |Integer|integer|Only numbers without a decimal point are allowed, such as //100// or //-100//.
24 |Positive integer|posinteger|Only positive numbers without a decimal, such as //100// or //200//.
25 |Number|number|Only numbers with a German-style decimal separator (comma) are allowed, such as /100//, //-4,45// or //1,9//.//
26 |Money|money|Only numbers with exactly two decimals places are allowed. The decimal separator is a comma. Thousands separators are not allowed. For example, both //100// and //99,99// are allowed, but not //1,234// or //456.123,23//.
27 |Positive amount of money|posmoney|Same as //money//, but must not be negative.
28 |Positive amount of money (opt. decimal)|posmoneyOptionalComma|Same as //money//, but does not require two decimal place. For example, //3//, //3,4//, and //3,49// are allowed, but not //3,493//.
29 |Email|email|E-Mail Validator ([[International email address>>url:https://en.wikipedia.org/wiki/International_email||target="_blank"]])
30 |Date(DD.MM.YYYY)|datumDE|Only German-style dates are allowed, ie. {{code language="none"}}DD.MM.YYYY{{/code}}. Example: //01.01.2015//.
31 |Time|time|Allows only time values of the format {{code language="none"}}hh:mm{{/code}}, such as //01:30// or //13:30//.
32 |Postal code(Germany)|plzDE|Only German postal codes are allowed, ie. five digits such as //01109// or //01069//.
33 |Phone number|phone|Only phone number are allowed. For example, //+49 351 810 500//, //0049-351-810-500// and //0049/351/810/500// are allowed
34 |URL|url|Only valid URLs are allowed, such as {{code language="none"}}http://www.xima.de{{/code}}, {{code language="none"}}https://www.xima.de{{/code}}, and {{code language="none"}}ftp://ftp.xima.de{{/code}}.
35 |IP address|ipv4|Only IP v4 addresses are allowed, such as //127.0.0.1// and //192.168.0.255//.
36 |Regular expression|-|Lets you use a custom regexp for validation. When this data type is selected, you can also enter a custom error message. This message can be [[translated into different languages>>doc:Formcycle.Designer.Form.Internationalization]] as well. The regexp is evaluated as a JavaScript regexp, described in detail at [[mozilla.org>>url:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions]].
37 {{/table}}
38
39 == Regexp datatype ==
40
41 {{figure image="designer_validators_regexp_en.png" width="500"}}
42 When you set the datatype to regexp, you can enter a custom regexp for validation. It is also possible to specify a custom error message that is shown when the regexp does not match.
43 {{/figure}}
44
45
46 When you select the regexp datatype, you can can enter a custom regexp that is used to validate the text field. If the regexp matches the current value of the text field, it is considered valid. Otherwise, the error message you entered is displayed. The regexp is interpreted as a JavaScript regexp and must be entered without the initial and final slash ({{{/}}}).
47
48 As a simple example, the following regexp requires that the entered value contains at least one of the words //apple// or //banana//.
49
50 {{code language="none"}}
51 \b(apple|banana)\b
52 {{/code}}
53
54 Often you want to match against the entire value of the text field. In this case, use the anchors //^// (matches the beginning) and //$// (matches the end):
55
56 {{code language="none"}}
57 ^[a-zA-Z][a-zA-Z\d]{3,15}$
58 {{/code}}
59
60 The above regexp checks for valid user names that must contain between 4 to 16 characters, may contain only letters and numbers, and must start with a letter.
61
62 == Server-side validation ==
63
64 {{figure image="designer_validators_server_side_en.png"}}
65 Activate the server-side validation to have the data checked by the server as well. This prevents users from manipulating the form with JavaScript.
66 {{/figure}}
67
68 By default, the form is only validated in the browser of the user. Given enough technical knowledge, a user can manipulate the form and circumvent the validation. This would enable them to send invalid data, such as wrong email addresses. In case it becomes necessary to prevent these kind of manipulations, you can activate the server-side validation by clicking on the checkbox in the constraints section of the properties panel. When the form is submitted, the server checks the submitted data according to the rules as defined in the {{designer/}}. When the data does not pass this server-side validation, the server rejects the submitted data and shows an appropriate error message to the user.
69
70 For each element you can choose whether or not you would like to activate the server-side validation.
71
72 Please note that the server-side validation is supported only for constraints that were set in the graphical user interface of the {{designer/}}. If you added any custom logic or validators via JavaScript, that logic is not considered during the server-side validation process. Also, if you override built-in validators (see below), you should disable the server-side validation as the server always uses the default rules for built-in validators.
73
74 == Custom validator function ==
75
76 {{figure image="designer_validators_errorfunc_en.png" width="500"}}
77 Add a validator function to implement custom logic for checking the value of form elements.
78 {{/figure}}
79
80 When you encounter more complex requirement, you may need to write custom business logic for validating form elements. {{jsdoc page="jquery" name="errorfunc"}}To do so, use the JavaScript function errorFunc.{{/jsdoc}}
81
82 The errorFunc lets you add a custom function to a form element that checks whether it is valid or not. It returns the error message to be shown:
83
84 {{js}}
85 $('[name="tfMail"]').errorFunc(function(){
86 // The datatype of the field 'tfMail' was set to 'email'.
87 // We now add an additional validation rule: The host must be one of 'example.com' or 'example.de'
88 const value = String(this.val() || "");
89 const hostIndex = value.indexOf("@");
90 const host = hostIndex >= 0 ? value.substr(hostIndex + 1) : "";
91 if (host === "example.com" || host === "example.de") return "";
92 return "The host must be either example.de or example.com!";
93 });
94 {{/js}}
95
96 {{jsIE}}
97 $('[name="tfMail"]').errorFunc(function(){
98 // The datatype of the field 'tfMail' was set to 'email'.
99 // We now add an additional validation rule: The host must be one of 'example.com' or 'example.de'
100 var value = String(this.val() || "");
101 var hostIndex = value.indexOf("@");
102 var host = hostIndex >= 0 ? value.substr(hostIndex + 1) : "";
103 if (host === "example.com" || host === "example.de") return "";
104 return "The host must be either example.de or example.com!";
105 });
106 {{/jsIE}}
107
108 == Plugins ==
109
110 Another way of adding custom validators is by uploading a [[Java-Plugin>>doc:Formcycle.UserInterface.Client.Plugins]] to {{formcycle/}}. Once you have uploaded and installed the plugin, you can select the new validator as a datatype in the constraints section of the properties panel. Developers may view [[the documentation for this plugin type>>doc:Formcycle.PluginDevelopment.Types.IPluginValidationRule]].
111
112 == Overriding validators ==
113
114 {{figure image="designer_validators_custom_en.png" width="500"}}
115 Adding a new validator to the global object //XM_FORM_VRULES//. To use the validator, you need to set the HTML attribute //vdt// to the name of the validator.
116 {{/figure}}
117
118 {{warning}}
119 Overriding built-in validators is deprecated. It is not maintainable and error-prone. Consider using the datatype //regexp// instead, or add a custom validator via {{jsdoc page="jquery" name="errorfunc"/}} or plugins.
120 {{/warning}}
121
122 It is possible to override the built-in validators. The validators are regexps that are stored in the global JavaScript object //window.XM_FORM_VRULES//. The corresponding error messages can be found in //window.XM_FORM_I18N//. You can use JavaScript to override some entries of these objects:
123
124 For example, you can modify the validator for the money datatype; so that it now accepts a period instead of a comma as the decimal separator:
125
126 {{code language="javascript"}}
127 XM_FORM_VRULES.money = /^-{0,1}([0]{1}|[1-9]{1}[0-9]*)[.]{1}[0-9]{2}$/;
128 XM_FORM_I18N.money = "Please use a period before the cents (ex: 100.00)";
129 {{/code}}
130
131 Furthermore, you could also add new entries to the JavaScript objects //XM_FORM_VRULES// and //XM_FORM_I18N//. To use the newly created validator with a text field, set the HTML attribute to the name of the validator. You can set HTML attributes in the attributes section of the properties panel.
132
133 For example, to create a new validator for numbers with exactly 2 decimal digits and at most 5 digits before the period:
134
135 {{code language="javascript"}}
136 XM_FORM_VRULES.number_5_2 = /^(0|[1-9]\d{0,4})\.\d\d$/;
137 XM_FORM_I18N.number_5_2 = "Please enter a number with 2 digits after the period and at most 5 digits before the period.";
138 {{/code}}
139
140 The new validator has not got the name //number_5_2//. This is the name you need to set as the value of the HTML attribute //vdt//.