Combo

An input that represents an advanced select box with a set of options. It is able to provide suggestions while a user is typing text.

Combo control

Related sample: Form. Combo

Adding Combo

You can easily add a Combo control during initialization of a form:

var form = new dhx.Form("form_container", {
    rows: [
        {
            type: "combo",
            name: "combo",
            label: "count",
            labelPosition: "left",
            multiselection: true,
            selectAllButton: true,
            value: [
                "id_1",
                "id_2"
            ],
            data: [
                { value: "1", id: "id_1" },
                { value: "2", id: "id_2" },
                { value: "3", id: "id_3" },
                { value: "4", id: "id_4" },
                { value: "5", id: "id_5" }
            ]
        }
    ]
});

Attributes

You can provide the following attributes in the configuration object of a combo:

type	(string) the type of a control, set it to "combo"
name	(string) the name of a control
id	(string) the id of a control, auto-generated if not set
value	(string\|array) specifies the values that will appear in the input: if multiselection:true is set for a combo, the property takes an array of string values as: value: ["1","2","3"], if multiselection:false is set or the multiselection config is not defined, the property gets either of the two values: value:"1" or value: ["1"]
data	(array) an array of Combo options. Each option is an object with a set of key:value pairs - attributes of options and their values. The id attribute is returned and goes to form data. This attribute should always be fulfilled to avoid unexpected behavior The value attribute is displayed in the input field
validation	(function) the validation function, takes as a parameter the value to validate and returns true/false to indicate the result of validation
width	(string\|number\|"content") the width of a control
height	(string\|number\|"content") the height of a control
padding	(string\|number) sets padding between a cell and a border of the Combo control
css	(string) adds style classes to a control
placeholder	(string) sets a placeholder in the input of Combo
disabled	(boolean) defines whether a control is enabled (false) or disabled (true)
required	(boolean) defines whether the field with Combo is required (for a form)
hidden	(boolean) defines whether a control is hidden
readonly	(boolean) makes Combo readonly (it is only possible to select options from the list, without entering words in the input)
label	(string) specifies a label for a control
labelWidth	(string\|number) sets the width of the label of a control
hiddenLabel	(boolean) invisible label that will be used to identify the input on the server side
labelPosition	(string) defines the position of a label: "left"\|"top"
helpMessage	(string) adds a help message to a control
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
itemHeight	(number) sets the height of a cell in the list of options
listHeight	(number) sets the height of the list of options
template	(function) sets a template of displaying options in the popup list
filter	(function) sets a custom function for filtering Combo options. Check the details.
multiselection	(boolean) enables selection of multiple options in Combo
selectAllButton	(boolean) defines whether the Select All button should be shown
itemsCount	(boolean, function) shows the total number of selected options
virtual	(boolean) enables dynamic loading of data on scrolling the list of options

Working with Combo

You can manipulate a Combo control by using methods (or events) of the object returned by the getItem() method.

For example, you can get the value of the control:

var value = form.getItem("Combo").getValue();

List of the control methods:

clear	clears a value of a Combo control
clearValidate	clears validation of a Combo control
disable	disables a Combo control on a page
enable	enables a disabled Combo control
focus	sets focus to a control
getProperties	returns an object with the available configuration attributes of the control
getValue	returns the current value of a Combo control
getWidget	returns the dhtmlxComboBox widget attached to a Combo control
hide	hides a Combo control
isDisabled	checks whether a Combo control is disabled
isVisible	checks whether a Combo control is visible on the page
setProperties	allows changing available configuration attributes of the control dynamically
setValue	sets the value for a Combo control
show	shows a Combo control on the page
validate	validates a Combo control

List of the control events:

afterChangeProperties	fires after configuration attributes of the control have been changed dynamically
afterHide	fires after a control is hidden
afterShow	fires after a control is shown
afterValidate	fires after the control value is validated
beforeChangeProperties	fires before configuration attributes of the control are changed dynamically
beforeHide	fires before a control is hidden
beforeShow	fires before a control is shown
beforeValidate	fires before the control value is validated
change	fires on changing the value of a control

Working with the dhtmlxComboBox widget

There is a possibility to use methods of dhtmlxCombobox via the getWidget() method of a Combo control.

For example, you can set focus in the Combo input without opening a popup with options. To do this, you need to get the widget attached to the Combo control and then use the focus() method of this widget.

var combo = form.getItem("combo").getWidget();  // -> ComboBox
combo.focus(); // sets focus in the input