Work with Form

Getting values of controls

You can get current values/states of Form controls with the help of the getValue() method. By default, this method returns an object with names or IDs of controls (if the name attribute is not defined in the config of the control) and their values/states.

// default functionality
const state = form.getValue();
//->{"name":"John Doe","email":"jd@mail.com", "agree":true}

It is also possible to get this information in the form of FormData. For this, you need to pass the following parameter:

• asFormData - (boolean) defines whether values of Form controls should be returned as Form Data

// returning form details as FormData
const state = form.getValue(true);

Related sample: Form. Get value

Setting new values for controls

If you want to set new values or states for Form controls on the fly, there is the setValue() at your disposal. The method takes as a parameter an object with new values/states of controls. This object should contain a set of key:value pairs where key is either the name of the control or the control's id (if the name attribute is not defined in the config of the control) and value is a new value/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();
// -> true|false

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 either the name of the control or its id (if the name attribute is not defined in the config of the control) as a parameter 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 either the name of the control or its id (if the name attribute is not defined in the config of the control) as a parameter to the isVisible() method:

form.isVisible("input"); // -> returns true/false

Validating form

In order to validate a form, you should deal with several aspects: required fields, minimal and maximal values, number of allowed characters, and validation rules.

Required fields

You can easily specify that an input is obligatory to be treated by a user with the help of the required attribute.

{    
    type: "checkbox",
    label: "I agree",
    name: "agree",
    required: true,
    id: "agree",
    value: "checkboxvalue"
}

While you've set required:true for a field, it gets an asterisk next to its label:

Related sample: Form. Required

The attribute is applicable to the input fields with the input types: "number", "text", "password".

Minimal and maximal values

Starting with v7.0, it is possible to add validation for number values entered in the input field.

You just need to specify the minimum and/or maximum values allowed in the input via the min and/or max attributes.

{
    type: "input",
    inputType: "number",
    label: "Age",
    value: 18,
    placeholder: "Enter your age",
    min: 12,
    max: 18
}

The attributes are applicable to the input fields with the input type: "number".

Number of allowed characters

Starting from v7.0, you can easily limit the number of characters entered in an input or textarea field.

For that, you need to use the minlength and (or) maxlength attributes that check the length of the given value. Validation is successful if the length is greater than or equal to the minlength value and (or) less than or equal to the maxlength value.

{
    type: "input",
    inputType: "text",
    label: "Name",
    placeholder: "John Doe",
    minlength: 3,
    maxlength: 10
}

The attributes are applicable to the input/textarea fields with the input types: "text", "password".

Validation rules

To specify the way of validating a particular input/textarea, you can make use of predefined validation rules, they are:

• "email" - validEmail
• "integer" - validInteger
• "numeric" - validNumeric
• "alphanumeric" - validAplhaNumeric
• "IPv4" - validIPv4

Set a string with the name of the necessary rule as a value of the validation attribute:

{
    type: "input",
    inputType: "text",
    label: "Email",
    placeholder: "jd@mail.name",
    validation: "email"
}

There is also a possibility to specify a custom validation function by setting it as a value of the validation attribute:

Validation for Input control

{
    type: "input",
    inputType: "text",
    label: "Name",
    placeholder: "John Doe",
    validation: function(value) {
        return value && value.length > 4;
    }    
}

Related sample: Form. Validation

info

If the inputType attribute is set to "number", the validation attribute can be set only as a function

Validation for Combo control. Multi select is enabled

// 
{
    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");
    }
}

Validation for Combo control. Multi select is disabled

{
    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

While specifying validation rules for form fields, you can also provide a set of messages that will notify the end user, whether he/she is filling the form in correctly. There are three types of messages 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, a configuration object for an input with email may look as in:

{
    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 has finished filling out the form according to the specified rules, it's high time to check, whether it is done correctly. To validate a form, make use of the validate() method:

const result = form.validate();

The method should return true, if all the fields are filled as required, or false if there are fields that require attention.

Related sample: Form. Validate

Sending form to server

To send a form to the server, make use of the send() method. It takes three parameters:

url	(string) the URL of the server
method	(string) the request type, "POST" by default
asFormData	(boolean) optional, defines whether values of Form controls should be sent as Form Data

and returns a promise object.

const send = form.send("myserver.com", "POST");

To control the process of a from sending, you can make use of the related events: beforeSend and afterSend:

// 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 API of DHTMLX Form provides you with flexible ways of clearing a form. There is the clear() method that clears a form either fully or partially, depending on the passed parameter.

• "value" - clears only form values
• "validation" - clears 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

Starting from v7.0, you can set focus to a Form control via the setFocus() method. It takes either the name of the control or its id (if the name attribute is not defined in the config of the control) as a parameter:

form.setFocus("input");

Related sample: Form. Set focus on control

It is possible to set focus to DatePicker, Checkbox, ColorPicker, Combo, Input, RadioGroup, Select, Textarea, TimePicker controls of Form.