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.

Related sample:  All dhxForm inputs - DHTMLX Form

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"
• id - (string) the id of a control, auto-generated if not set
• 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
• 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"]
• validation - (function) the validation function, takes as a parameter the value to validate and returns true/false to indicate the result of validation
  
  
• parent - (string) the id of the parent control
• width - (string) the width of a control
• height - (string) the height of a control
• css - (string) adds style classes to a control
• disabled - (boolean) defines whether a control is enabled (false) or disabled (true)
• label - (string) specifies a label for a control
• labelWidth - (string) 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
• labelInline - (boolean) defines the position of a label: true - to set a label inline with a control
• name - (string) the name of a control
• required - (boolean) defines whether the field with Combo is required (for a form)
• help - (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
• gravity - (boolean) arranges form controls evenly throughout the container, depending on the direction of layout ("cols" or "rows"), true by default
  
  
• cellHeight - (number) sets the height of a cell in the list of options
• listHeight - (number) sets the height of the list of options
• readonly - (boolean) makes Combo readonly (it is only possible to select options from the list, without entering words in the input)
• disabled - (boolean) makes Combo disabled
• template - (function) sets a template of displaying options in the popup list
• customFilter - (function) sets a custom function for filtering Combo options. Check the details
• multiselection - (boolean) enables selection of multiple options in Combo
• placeholder - (string) sets a placeholder in the input of 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
• 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
• 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
• setConfig(config: object) - sets a new configuration for a Combo control
• 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

Setting configuration of Combo control

It is possible to update the configuration of a Combo control on the fly with the help of the setConfig() method of the object returned by the getItem() method.

To do this, you need to get access to the object of the control by using the getItem() method of Form and pass a new configuration object as a parameter of the setConfig() method:

form.getItem("combo_id").setConfig({
    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"}
    ]
});

Back to top