Work with Form
Getting values of controls
The getValue() method returns the current values or states of Form controls. The default return value is an object with control names (or ids, if a control has no name) and their values or states.
// default functionality
const state = form.getValue();
//->{"name":"John Doe","email":"jd@mail.com", "agree":true}
To get this information as FormData, pass the following parameter:
asFormData— (boolean) defines whether the method returns control values as FormData
// returning form details as FormData
const state = form.getValue(true);
Related sample: Form. Get value
Setting new values for controls
To set new values or states for Form controls on the fly, use the setValue() method. The method takes an object with key:value pairs as a parameter, where key is the control name (or id, if the control has no name) and value is the new value or state of the control:
form.setValue({
"input_name":"Jack London",
"slider_id":10
// more name:value pairs
});
Related sample: Form. Set value
Enabling/Disabling a form
To enable a form, use the enable() method:
form.enable();
To disable a form, use the disable() method:
form.disable();
Related sample: Form. Disable/enable
Checking if a form is disabled
To check if a form is disabled, call the isDisabled() method:
form.isDisabled(); // -> true/false
To check whether a form control is disabled, pass the control name (or id, if the control has no name) to the isDisabled() method:
form.isDisabled("input"); // -> returns true/false
Related sample: Form. Is disabled
Hiding/Showing a form
To hide a form, use the hide() method:
form.hide();
To show a form, use the show() method:
form.show();
Related sample: Form. Hide/Show control
Checking if a form is visible
To check if a form is visible, call the isVisible() method:
form.isVisible(); // -> true/false
To check whether a form control is visible, pass the control name (or id, if the control has no name) to the isVisible() method:
form.isVisible("input"); // -> returns true/false
Using input masks
Input masks control how users enter values in the Input and Textarea Form controls. To work with input masks, use the numberMask and patternMask configuration options and the getText() method of these controls.
numberMask
The numberMask property sets an input mask for entering number values in the Input and Textarea Form controls. You can set it in two ways:
- As an object with the following properties:
prefix— renders text before the resulting valuesuffix— renders text after the resulting valuegroupSeparator— sets a separator for thousandsdecSeparator— sets a separator for decimalsallowNegative— allows negative numbersmaxIntLength— sets the maximum length of the integer partmaxDecLength— sets the maximum length of the decimal partminDecLength— sets the minimum rendered length of the decimal part
For example, the numberMask config can be set as the following object:
{
type: "input",
numberMask:{
prefix: "$",
groupSeparator: ",",
decSeparator: ".",
maxIntLength: 7,
maxDecLength: 2,
minDecLength: 0
}
}
With this config, the value 1000000.0000 becomes $1,000,000.
Default numberMask configs depending on the input type
When an input has inputType:"number", the resulting value is converted to the number type. The default config for this input type is:
{
groupSeparator: ",",
decSeparator: ".",
allowNegative: true,
maxIntLength: 16,
maxDecLength: 2,
minDecLength: 0
}
The default config for inputType: "text" (the default input type) is:
{
groupSeparator: ",",
decSeparator: ".",
allowNegative: true,
minDecLength: 0
}
When an input has inputType:"text", the resulting number is converted to the string type without the mask, as if it were a number. For example, if the input value is "$ 1,000,000", the getValue() method returns "1000000".
- As a boolean value, the
numberMaskproperty converts the number displayed in the input field to one of the predefined templates, depending on the specifiedinputType:
{
type: "input",
numberMask: true,
}
In the example above, the input type is not set, so the template of the default inputType:"text" converts 100000.01 to 100,000.01.
Related sample: Form. Number mask
patternMask
The patternMask property sets an input mask for entering number and string values in the Input and Textarea Form controls according to a pattern. You can set it in two ways:
- As an object with the following properties:
pattern— (function | string) specifies the mask and lets you change it dynamically, depending on the entered values. You can set it as:- a function that takes the entered value (a string or a number) as a parameter and returns a string with a pattern mask
- a string with a pattern mask
charFormat— (object) optional, specifies a regular expression for an optional symbol. Set it as an object withkey:valuepairs, wherekeyis a symbol andvalueis a regular expression. The default configuration of this property is:
{
"0": /\d/,
"a": /[A-Za-z]/,
"#": /[A-Za-z0-9]/,
"*": /./,
}
| Symbol | Description |
|---|---|
| "0" | any number from 0 to 9 |
| "a" | a single letter of the Roman alphabet, including all capital letters from A to Z and all lowercase letters from a to z |
| "#" | a single letter of the Roman alphabet (either an uppercase or a lowercase one) or a single number from 0 to 9 |
| "*" | any symbol |
The patternMask property supports static masks: symbols that are not specified in charFormat render as they are and cannot be changed.
The following patternMask property specifies a mask pattern for entering a date in an input:
{
type: "input",
label: "DD/MM/YYYY HH:MM",
placeholder: "01/01/2001 00:00",
patternMask: {
pattern: "00/00/0000 H0:M0", // a common mask pattern for date and time
charFormat: { // setting regular expressions for hours and minutes
"H": /[0-2]/,
"M": /[0-5]/,
}
}
}
A date that matches this mask: 01/01/2001 12:59.
- As a string, the
patternMaskproperty sets a mask with a predefined set of symbols. The followingpatternMaskproperty specifies a mask for entering an SSN:
{
type: "input",
patternMask: "000-00-0000"
}
An SSN that matches this mask: 123-41-1234.
Related sample: Form. Pattern mask
Selecting the suitable data format
You can specify different mask patterns depending on the type of data entered in an input. The examples below show common data formats:
- Phone number
A phone number can include digits, symbols, and spaces. Specify this format as a string value of the patternMask property:
{
type: "input",
patternMask: "+0 (000) 000-0000",
};
Example: +9 (123) 123-1234
- License plate format
A license plate usually combines letters, digits, and symbols. Specify this format as a string value of the patternMask property:
{
type: "input",
patternMask: "0-aaa-000",
}
Example: 9-AAA-999
- Price format
You can set a price format with the numberMask property, for example as the following object:
{
type: "input",
numberMask: {
prefix: "$ ",
maxDecLength: 2
}
}
Example: $ 1,000,000
In the example above, the prefix property sets the currency sign, and the maxDecLength property limits the number of decimal places to 2.
- Date and time format
For a date and time input, specify the patternMask property as the following object:
patternMask: {
pattern: "00/00/0000 H0:M0",
charFormat: {
"H": /[0-2]/,
"M": /[0-5]/,
}
}
Example: 01/01/2001 12:59
In the example above:
- The
patternproperty sets a common mask pattern for date and time - The
charFormatproperty specifies regular expressions for hours and minutes:"H": /[0-2]/— a digit from 0 to 2 for the hour inH0"M": /[0-5]/— a digit from 0 to 5 for the minutes inM0
Related sample: Form. Number mask
Related sample: Form. Pattern mask
Getting the text value of an input or a textarea
To get the value of an input or a textarea with the applied mask, use the getText() method of the Input control or the getText() method of the Textarea control.
The method returns the control value as a string and works with the numberMask and patternMask properties.
const input = form.getItem("input");
input.setValue(1000.01);
input.getValue(); // 1000.01 for the input type number
input.getValue(); // "1000.01" for the input type string
input.getText(); // "1,000.01" with the applied numberMask/patternMask
Validating form
Form validation covers required fields, minimum and maximum values, the number of allowed characters, and validation rules.
Required fields
To make a field required, set the required property:
{
type: "checkbox",
label: "I agree",
name: "agree",
required: true,
id: "agree",
value: "checkboxvalue"
}
When you set required:true for a field, an asterisk appears next to its label:
Related sample: Form. Required
The property applies to input fields with the number, text, and password input types.
Minimal and maximal values
From v7.0, you can validate number values entered in an input field.
Specify the minimum value, the maximum value, or both with the min and max properties:
{
type: "input",
inputType: "number",
label: "Age",
value: 18,
placeholder: "Enter your age",
min: 12,
max: 18
}
These properties apply to input fields with the number input type.
Number of allowed characters
From v7.0, you can limit the number of characters entered in an input or textarea field.
Use the minlength and maxlength properties, which check the length of the value. Validation succeeds if the length is greater than or equal to minlength and less than or equal to maxlength, whichever of them you set:
{
type: "input",
inputType: "text",
label: "Name",
placeholder: "John Doe",
minlength: 3,
maxlength: 10
}
These properties apply to input and textarea fields with the text and password input types.
Validation rules
To define how an input or a textarea is validated, use one of the predefined validation rules:
"email"—validEmail"integer"—validInteger"numeric"—validNumeric"alphanumeric"—validAplhaNumeric"IPv4"—validIPv4
Set the rule name as the value of the validation property:
{
type: "input",
inputType: "text",
label: "Email",
placeholder: "jd@mail.name",
validation: "email"
}
You can also set a custom validation function as the value of the validation property:
{
type: "input",
inputType: "text",
label: "Name",
placeholder: "John Doe",
validation: function(value) {
return value && value.length > 4;
}
}
Related sample: Form. Validation
If the inputType property is set to "number", you can set the validation property only as a function.
{
name: "combo",
type: "combo",
multiselection: true,
value: ["id:1", 4],
data: [
{ value: "value: 1", id: "id:1" },
{ value: "value: 2", id: "id:2" },
{ value: "value: 3", id: 3 },
{ value: "value: 4", id: 4 },
{ value: "value: 5", id: 5 },
],
validation: (value, text) => {
return value.includes(4) || text.includes("value:5");
}
}
{
name: "combo",
type: "combo",
multiselection: false,
value: 4,
data: [
{ value: "value: 1", id: "id:1" },
{ value: "value: 2", id: "id:2" },
{ value: "value: 3", id: 3 },
{ value: "value: 4", id: 4 },
{ value: "value: 5", id: 5 },
],
validation: (value, text) => {
return value === 4 || text === "value:5";
}
},
Messages
Along with validation rules, you can define messages that tell users whether they are filling in the form correctly. Three types of messages are available:
| preMessage | (string) a message that contains instructions for interacting with the control |
| successMessage | (string) a message that appears in case of successful validation of the control value |
| errorMessage | (string) a message that appears in case of error during validation of the control value |
For example, the following configuration object defines an email input:
{
type: "input",
label: "Email",
placeholder: "jd@mail.name",
errorMessage: "Invalid email",
successMessage: "Valid email",
validation: "email"
}
Related sample: Form. Messages
Validation API
After a user fills out the form, check whether it is filled out correctly. To validate a form, use the validate() method:
const result = form.validate();
The method returns true if all fields are filled as required, or false if some fields need attention.
Related sample: Form. Validate
Sending form to server
To send a form to the server, use the send() method. The method takes three parameters:
| url | (string) the URL of the server |
| method | (string) the request type; the default value is "POST" |
| asFormData | (boolean) optional, defines whether values of Form controls should be sent as Form Data |
The method returns a promise object.
const send = form.send("myserver.com", "POST");
To control how the form is sent, handle the beforeSend and afterSend events:
// fires before sending a form to the server
form.events.on("BeforeSend", function(){
// your logic here
});
// fires after sending a form to the server
form.events.on("AfterSend", function(){
// your logic here
});
Clearing form
The clear() method clears a form fully or partially, depending on the parameter you pass:
"value"— clears only form values"validation"— clears only form validation- Without parameters — clears both form values and validation
// clears only form validation
form.clear("validation");
// clears only form values
form.clear("value");
// clears both form values and validation
form.clear();
Related sample: Form. Clear form
Setting focus to a control
From v7.0, you can set focus to a Form control with the setFocus() method. The method takes the control name (or id, if the control has no name) as a parameter:
form.setFocus("input");
Related sample: Form. Set focus on control
You can set focus to the DatePicker, Checkbox, ColorPicker, Combo, Input, RadioGroup, Select, Textarea, and TimePicker controls.