Skip to main content

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 functionalityvar 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 FormDatavar 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

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();

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:

Required fields

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.

Value validate

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.

Length validate

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 rule by setting it as a value of the validation attribute:

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

Related sample: Form. Validation

note

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

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:

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

var 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 serverform.events.on("BeforeSend", function(){   // your logic here});
// fires after sending a form to the serverform.events.on("AfterSend", function(){   // your logic here});

Clearing form#

The API of dhtmlxForm 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 validationform.clear("validation");
// clears only form valuesform.clear("value");
// clears both form values and validationform.clear();

Related sample: Form. Clear

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.