Documentation

Form

API Reference

Overview

Any form is a means of getting an information from users. It contains input fields and select components like checkboxes, radiobuttons alongside with submit/cancel buttons depending on the situation. Find them all in our Controls Guide.



Initialization

Ui-related form inherits from view. It resembles layout very much as it is divided into columns and rows where controls are put.

  • elements - the form's specific property, an array of vertically arranged controls and control groups;
  • columns - an array of horizontally arranged controls and control groups;
  • rows - an array of vertically arranged controls and control groups.

Login form

webix.ui({
    view:"form", 
    id:"log_form",
    width:300,
    elements:[
        { view:"text", label:"Email"},
        { view:"text", type:"password", label:"Password"},
        { margin:5, cols:[
            { view:"button", value:"Login" , type:"form" },
            { view:"button", value:"Cancel" }
        ]}
        ]
    });

Related sample:  Basic Initialization

There exists a possibility to specify common configuration for all controls included in this or that form.

Grouping Controls in Form

Dividing form into sections

Form elements can be divided into columns and rows with any level of complexity.

{ view:"form", elements:[
    {cols:[
        { rows:[
            {view:"text"},
            {view:"datepicker"}
        ]},
        {view:"checkbox"},
        {view:"button"}
    ]},
 
]}

To add user-friendliness to form interface, separated blockes can be set within it by:

  • Adding headers with section type before control blocks;
  • Dividing a form into fieldsets.

Sections

Form elements are placed into different row arrays where the first row is a section header. Its template define text value of the header:

{view:"form", elements: [
    { rows:[ 
        { template:"Alpha fields", type:"section"},
        { view:"text", label:"Alpha 1", value:'' },
        { view:"text", label:"Alpha 2", value:'' }]
    },
    { rows:[ 
        { template:"Beta fields", type:"section"},
        { view:"text", label:"Beta 1", value:'' }]
    }
]}



Related sample:  Splitting Form into Sections

Fieldsets

Fieldset is a collection of controls surrounded by a border from all the sides. Webix fieldset features text label and body where rows or cols array of controls are stored:

{view:"form", elements:[
    { view:"fieldset", label:"Field Set 1", body:{
         rows:[
            { view:"text", label:"Login"},
            { view:"text", label:"Email"}]
         }
    }
]}



Related sample:  Fieldset

Multiview Form

Form field can be placed into different tabs thus forming a multiview layout. Switching between tabs there is implemented with tabbar and segmented buttons as well as with the help of the dedicated tabview.

The switching controls are placed directly into the array of form elements.

{view:"form", elements:[
    {view:"tabview",
        tabs:["A","B","C"],
        cells:[
            { view:"text", name:"value1", label:"value1" },
            { view:"text", name:"value2", label:"value2" } 
        ]
    }]
}

Related sample:  Form with Tabs

Retrieving Form Values

Getting value of a single element

Since form elements comprise an array you can refer to each of them by its number starting from 0 and get/set the value of any item.

var form1 = [
    { view:"text", id:"log", label:'Login', name:"login"},
    { view:"text", id:"em" label:'Email', name:"email" },
    { view:"button", id:"sub", name:"submit", value:"Sumbit"}
];
 
webix.ui({
    view:"form", 
    id:"my_form", 
    elements: form1
});
 
var login = form1[0].login;// returns current input value;
var button = form1[2].submit; //returns "Submit";

Or, you can apply getValue() method directly to the needed control:

$$("log").getValue();

Getting values of all form elements

To get an associative array of all elements (name:value pairs) you can use getValues method. To get to the necessary value, you should specify the name of the needed control.

$$("my_form").getValues().login; //returns current value of the text input field

Additionally, you can get only changed and unchanged form values with the following methods respectively:

Disabling Form Elements

Any form element can be disabled or switched to readonly mode.

 
var form2 = [
        { view:"header" }
        { view:"text", value:'..', label:".."},
        { view:"text", type:'..', value:'..', label:".."},
]
 
form2[i].readonly = true; //where "i" takes the number value of the element staring from 0.
form2[i].disabled = true;

Related sample:  Attributes

See also Form and HTMLform Treatment article to learn more about the most important form methods.

Reacting on Changes in Input Fields

If you want to track the moment when the value in an input changes from one to another and attach some event to it, make use of the dedicated "onChange" event.

The event is attached to element object that can be retrieved by its ID or name.

The attached function can be any you wish. Here is an example of logging the changes. The old value comes as oldv parameter while the new one is referred as newv

$$("form1").elements["login"].attachEvent("onChange", function(newv, oldv){
            webix.message("Value changed from: "+oldv+" to: "+newv);

Related sample:  'onChange' Event

Getting Parent Form for the Input

The easiest way to get to a parent form from any of its elements is to call the getFormView:

{view:"text", on:{"onChange":function(){
    var form = this.getFormView();
}}}

Loading and Parsing Initial Data

Webix form can load or parse data like any data management component. All the data loading rules are true for it.

Data attributes should coincide with names of form fields:

Parsing

var data = {id:1, fname:"Ann", lname:"Brown"};
 
webix.ui({
    view:"form", id:"myform", elements:[
        {view:"text", name:"fname"},
        {view:"text", name:"lname"}
    ],
    data:data
});    
//or
$$("myform").parse(data);

Loading

$$("myform").load("data.php");

Sending Form Data

Form data can be sent to server in either of the following ways:

1 . Using Webix Ajax helper:

webix.ajax().post("some.php", form.getValues()); 
//with callback
webix.ajax().post("some.php", form.getValues(), function(text, data, xhr){ });

2 . Using webix.send method that emulates HTML form submitting:

webix.send("come.php", form.getValues());

3 . Indirectly, via the bound master component or DataCollection:

The method is good when the form is used for editing the data of the main component (datatable, tree, list, etc.). In this case not the form data matters but the data of the main component. Form saves the data to the master component while the master handles the serverside part.

//data from selected list item is pushed to the form
form.bind(list);
 
//pushes the data back to list item
form.save()

Data binding concept is described in a separate documentation article.

Related Articles

Back to top