Intermediate

Controls Guide

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.

List of Available Controls

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 Initialization

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(){ ... }}

Defining Text Label

The label (string) property sets a text label for a control, a string placed by the control.

underwrites the controls and explains its purpose;
label absence is defined as label:"null" or by omitting this property in the control constructor;
horizontal position of the label is defined by the labelAlign (string) property. Its possible values are:
- "left"(default);
- "right" (except for button and toggle that takes only left alignment);
vertical position of the label is defined by the labelPosition (string). The only possible value is "top";
width of the label is defined by the labelWidth property;
text of the button is set by value property instead of label.

Please, don't mix it with a separate view label.

Related sample: Positioning Labels

Defining Special Modes

Any control can be set disabled and readonly with the help of dedicated properties:

elements:[
    { view:"text", readonly:true},
    { view:"datepicker", disabled:true}
]

Control Positioning

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):

"right";
"left" (default);
"center".

Setting Dimensions

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.

Specifying the width of a control

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:

The options that define the size of a control

height/width (number) - dimensions of space reserved for this control including its label;
maxHeight/maxWidth - maximum dimensions of the whole control. During resizing, the control can't be bigger, but can be smaller;
minHeight/minWidth - minimal dimensions of the whole control. During resizing, the control can't be smaller, but grow bigger;
gravity - relative sizing functor for controls placed in the same row/column.

// text2 is 3 times bigger than text1
rows:[
    { view:"text", name:"text1", gravity:1},
    { view:"text", name:"text2", gravity:3}
]

The options that define the label and the input area size

inputHeight/inputWidth (number) - dimensions of the input area/ button body;
labelWidth - width of the text label by the control. It can't be bigger than inputWidth and, thereby, width. If it is, the control will be incorrectly displayed. By default, it features static width of 106 px.

The option specific for a segmented button and a toolbar

optionWidth (number) - sets the width of an option (segment of tab) for segmented and tabbar. Hence, for such controls inputWidth = optionWidth * N options. If this value is smaller than width, a part of the control will disappear;

Attaching Event Handlers

Controls can trigger any function for any component in the application. Study Event Handling for details.

Inner events of controls include:

clicking;
changing their state (selection made, switching to another tab, adding new data into inputs)

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:

from hidden to visible and vice versa,
from disabled to enabled and vice versa.

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:

the functionality allows for watching various value changes (empty/not empty, selected/not selected, checked/unchecked) for different controls;
relatedView property takes ID of the needed control as parameter (if you don't define ID manually, it will be created automatically and can be derived as view.config.id);
relatedAction offers two possibilities for now:
- "enable";
- "show";
Slave field may have initial values to match with master relatedAction - hidden:true for "show" and disabled:true for "enable".

Defining Initial Values

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:

omit this property at all;
make the property empty ( {view:"text", value:""} );
set default value that can be deleted or changed by users( {view:"text", value:"My text"} );
still it's better to use placeholder (the default value for the input, a hint for user. Disappears as you start typing.);
for two-state controls like checkbox, radio and toggle possible values are:
- true or 1 - for a 'checked' state;
- false or 0 - for 'unchecked' state.
for counter, slider and range slider initial value is normally set as a possible number or the one in the middle of the predefined range.

Multiple-value controls

Such controls fall into two groups:

those presupposing the choice from a pull-down or popup list of predefined values (select, combo, multicombo, richselect and multiselect);
those offering the choice between tabs (segments) of integral buttons, namely tabbar and segmented.

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"}

Note that the getValue() method will return the id of the currently selected tab/segment/option.

Setting Values Dynamically

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:

setValue() - with either 0 (false) to uncheck or 1 (true) to check;
toggle() - to change the initial value (the toggle button as well takes this method);

//check the control if it is unchecked and vice versa
$$("mycheckbox").toggle();

Getting Values

Within the library we have two methods for getting values:

getValue() - for a component that has one value (any control);
getValues() - for a component that stores a number of controls (form / htmlform)

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:

text string in the text or textarea control;
state (boolean) of two-state controls (checkbox, radio and toggle);
ID of selected tab of integral buttons (tabbar and segmented);
ID of selected option of selection controls (select, combo and richselect);
string with selected option IDs of a multiselect and multicombo control.
text on the button;
selected date or color item (datepicker, colorpicker).

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

Clearing Values

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

Visibility of Controls

All controls can be shown and hidden on demand:

one by one applying show() and hide() methods to each of the needed controls or setting hidden property.
in groups by implementing batches functionality. More info.

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.

Styling

Controls can be styled to your taste with the help of CSS Image Maps.

Adding Tooltips to Controls

You can add Webix tooltips to all controls. For details, go to Tooltip Implementation.

Common Configuration within Form and Toolbar

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.