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

Adding Combo

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

var form = new dhx.Form("form_container", {
    rows: [
        {
            type: "combo",
            label: "count",
            labelInline: true,
            labelWidth: "50px",
            width:"200px",
            data: [
                {id: "empty", value:""},
                {id: "email", value: "email"},
                {id: "integer", value: "integer"},
                {id: "numeric", value: "numeric"},
                {id: "alphanumeric", value: "alphanumeric"},
                {id: "IPv4", value: "IPv4"}
            ]
        }  
    ]
});

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) the width of a control
height - (string) the height of a 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)
gravity - (boolean) arranges form controls evenly throughout the container, depending on the direction of layout ("cols" or "rows"), true by default
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
showItemsCount - (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 of the object returned by the getItem() method.

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

var value = form.getItem("Combo_id").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
getValue(): string|string[] - returns the current string value, if multiselection:false is set or the multiselection config is not defined, otherwise - returns an array of string value of a Combo control
getWidget(): object - returns the dhtmlxCombo widget attached to a Combo control
hide() - hides a Combo control
isDisabled(): boolean - checks whether a Combo control is disabled
setValue(value: string|string[]) - sets the value for a Combo control: as a string value either "1" or ["1"], if multiselection:false is set or the multiselection config is not defined, otherwise - as an array of string values
show() - shows a Combo control on the page
validate(): boolean - validates a Combo control. Returns the result of validation: true, if a control is valid, otherwise - false

Working with the widget of Combo control

There is a possibility to use methods of dhtmlxCombo 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_id").getWidget();  // -> ComboBox
combo.focus(); // sets focus in the input