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.

CONTENTS

• Built-in validators
• Regexp datatype
• Server-side validation
• Custom validator function
• Plugins
• Overriding validators

Built-in validators

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.

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 variables template.

Alternatively, you can also enter an error message directly in the form designer, when you select a data type other than text. You can translate this error message into other languages by selecting the target language in the form designer. If possible, for consistency, we recommend that you manage error messages globally with the i18n template. However, this option may prove useful in case you need to change the error message only for a specific form field.

The following built-in validators are available:

Regexp datatype

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 (/).

As a simple example, the following regexp requires that the entered value contains at least one of the words apple or banana.

\b(apple|banana)\b

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):

^[a-zA-Z][a-zA-Z\d]{3,15}$

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.

Server-side validation

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 formcycle 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.

For each element you can choose whether or not you would like to activate the server-side validation.

Please note that the server-side validation is supported only for constraints that were set in the graphical user interface of the formcycle 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.

Custom validator function

When you encounter more complex requirement, you may need to write custom business logic for validating form elements. To do so, use the JavaScript function errorFunc. 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:

$('[name="tfMail"]').errorFunc(function(){
  // The datatype of the field 'tfMail' was set to 'email'.
  // We now add an additional validation rule: The host must be one of 'example.com' or 'example.de'
  const value = String(this.val() || "");
  const hostIndex = value.indexOf("@");
  const host = hostIndex >= 0 ? value.substr(hostIndex + 1) : "";
  if (host === "example.com" || host === "example.de") return "";
  return "The host must be either example.de or example.com!";
});

Plugins

Another way of adding custom validators is by uploading a Java-Plugin 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.

Overriding validators

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 jQuery.fn.errorfunc or plugins.

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:

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:

XM_FORM_VRULES.money = /^-{0,1}([0]{1}|[1-9]{1}[0-9]*)[.]{1}[0-9]{2}$/;
XM_FORM_I18N.money = "Please use a period before the cents (ex: 100.00)";

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.

For example, to create a new validator for numbers with exactly 2 decimal digits and at most 5 digits before the period:

  XM_FORM_VRULES.number_5_2 = /^(0|[1-9]\d{0,4})\.\d\d$/;
  XM_FORM_I18N.number_5_2 = "Please enter a number with 2 digits after the period and at most 5 digits before the period.";

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.