Controls are the most important components for event handling, since they enable interaction with users. They are used separately as well as can be nested into toolbar, form, and other components. All UI-related controls inherit from input.
Button, Checkbox, ColorPicker, Combo, Counter, DatePicker, DateRangePicker, DoubleList,
Fieldset, FormInput,
Icon, Label, Multicombo, Multiselect, Multitext, Radio, RangeSlider,
RichSelect, RichText, Search,
Select, Segmented Button, Slider, Suggest List and
its advanced variations, Switch Button, Tabbar, Text, Textarea, Toggle Button.
Form controls share a lot of features that work the same way with most of them or with very little difference.
Control constructor includes its name and properties defining its look-and-feel and behavior.
Some properties duplicate HTML attributes, some are typically Webix control properties. In addition, you can set necessary HTML attributes to your control within the attributes object property:
{ view:"text", width:200, attributes:{ maxlength:10 }, click: function(){ ... }}
The label (string) property sets a text label for a control, a string placed by the control.
Please, don't mix it with a separate view label.
Related sample: Positioning Labels
Any control can be set disabled and readonly with the help of dedicated properties:
elements:[
{ view:"text", readonly:true},
{ view:"datepicker", disabled:true}
]
Here we make use of the align (string) property that defines horizontal position of the control and its label with respect to the parent container (e.g. form):
Related sample: Aligning Inputs and Labels
Each time control is initialized, space is reserved for it. It is either equal to parent (form, toolbar) dimensions or set as the width of a control.
In case several controls are in the same row/column, the available space is distributed equally among them.
The total width of the control consists of inputWidth and labelWidth (study the picture).
Don't specify the value of inputWidth or labelWidth larger than the value of width, otherwise a part of the control won't be visible. At the same time, you can make the width bigger. In this case a spacing will appear.
There are three groups of sizing options:
// text2 is 3 times bigger than text1
rows:[
{ view:"text", name:"text1", gravity:1},
{ view:"text", name:"text2", gravity:3}
]
Controls can trigger any function for any component in the application. Study Event Handling for details.
Inner events of controls include:
Two major possibilities here include:
1 . Attaching event inside the control constructor.
With the click property. It equals to the "onItemClick" event.
{view:"button", click:function(){
$$("my_form").validate();
}}
With the on property that allows attaching custom handlers to specified inner events of the control:
//clicking
{ view:"button", on:{
onItemClick: function(){...}
}}
//state changing
{view:"text", on:{
onChange: function(){...}
}}
2 . The same using the attachEvent() method.
//clicking
$$("my_button").attachEvent("onItemClick", function(){... });
//state changing
$$("my_text").attachEvent("onChange", function(){...});
The implementation of an onChange() handler is described in the Form documentation.
Each form field can have one related field defined by its relatedView property.
This field can react on changes in master field and change it's state:
This behavior is also defined by the master field with the relatedAction property:
Enabling a form field by changes in another
elements:[
{ view:"text", id:"master", relatedView:"slave", relatedAction:"enable"},
{ view:"text", id:"slave", disabled:true}
]
The following conditions should be observed:
Related sample: Automatic Form Reconfiguration
Single-value controls
For such controls as text and textarea value property isn't normally set beforehand, as they are intended for user filling.
So these exist different variants of value treating:
Multiple-value controls
Such controls fall into two groups:
These values are set within options property either as an array or as a collections of objects.
Array of options for Combo box
{ view:"combo", id:"field_m", label: "Combo", value:"One", yCount:"3",
options:["One", "Two", "Three"]
}
The initial value is specified by the value property and corresponds to any value from the predefined ones:
Collection of objects
{
view:"radio", label:"Branch", value:1, options:[
{ value:"Master", id:1 },
{ value:"Branch", id:2 }
]
}
Related sample: Radio Button ('radio')
Server-side options for multiple-value controls
Such controls as select, combo, multicombo, richselect and multiselect can get values from the server side. The script that returns the needed data, can be defined directly in the options property:
{ view:"combo", options:"server/data.json"}
Related sample: Advanced Options for Select Controls ('combo' and 'richselect')
Note that the getValue() method will return the id of the currently selected tab/segment/option.
Values can be as well set after initialization with the help of the dedicated setValue() method for a single control or setValues() to set the values for controls within the form. Find the latter in the related article.
Both methods take the needed value (or object with 'ID-value' pair(s)) as parameter and are called from the necessary control or the form where the controls are nested:
$$("text1").setValue("Anna"); //for a single text field with "text1" ID
$$("form1").setValues({ //for several text fields in the form
text1:"Anna",
text2:"Brown"
});
Values of two-state controls (checkbox and radio) can be changed in different ways:
//check the control if it is unchecked and vice versa
$$("mycheckbox").toggle();
Within the library we have two methods for getting values:
In case you want to get the value of a separate control, call the getValue method from it:
{view:"select", id:"my_sel", value:1, options:[
{ id:1, value:"Master" },
{ id:2, value:"Release" }
]}
var value = $$("my_sel").getValue(); // returns 1
In case controls are embedded into a form, we call the getValues() method from this form while specifying name or ID of the dedicated control.
webix.ui({
view:"form", elements:[
{view:"text", id:"title", value:""},
//other controls
]
})
var title = $$("myform").getValues().title, //-> returns value of text input
Control Value can be different:
In case the getValue() method returns object (e.g. date object) and you'd like to see the string result at once, you can include the stringResult property into the control constructor:
webix.ui({
view:"datepicker",
stringResult:true, // false by default
// other properties
});
You can add an ability to clear control value via the dedicated icon to the following controls:
To enable the ability set the clear property to true:
webix.ui({
width:400,
rows:[
{ view:"search", label:"Search", clear:"hover"},
{ view:"text", label:"Text", clear:true},
{ view:"combo", label:"Combo", options: list_data, clear:"replace"},
]};
Related sample: Controls: Clear Value
All controls can be shown and hidden on demand:
For hidden inputs within the form the library offer peculiar API that actually eliminates the need of creating hidden fields. Here you manipulate with values only.
Controls can be styled to your taste with the help of CSS Image Maps.
You can add Webix tooltips to all controls. For details, go to Tooltip Implementation.
If you have several instances of one and the same control within a form or a toolbar (a lot of text fields in the form or several buttons on a toolbar) and want them to have the same properties, you can define these properties only once in an elementsConfig object.
Find more info in the corresponding article of our documentation.
Back to top