Class Listbox

The Listbox control offers the same functions as the Dropdown control but shows the entries as an open list in the browser.

Note

This control operates the same way on both edit and view pages. Refer to this documentation for guidance on its use on view pages as well.

Hierarchy

Properties

element

Accessors

multiple required

Methods

checkValidity deselectAllEntries deselectEntries getDisplayValue getEntries getSelectedEntries getValue hasValue reload reset selectAllEntries selectFirstEntry setDisplayValue setValue triggerOnchange

Properties

element

element: HTMLSelectElement

Accessors

multiple

  • get multiple(): boolean

  • Determines whether the control allows multiple items to be selected from a list.

    Returns boolean

    Returns true if multiple selection is enabled; otherwise, false.

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    ctrl.multiple; // returns true or false

required

  • get required(): boolean

  • Check if the control is required.

    Returns boolean

    Returns true if the control is required; otherwise, false.

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    ctrl.required; // returns true or false
  • set required(value): void

  • Sets the control's required state.

    Parameters

    • value: boolean

      The value to set.

      var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
      ctrl.required = true; // sets the control to required

    Returns void

Methods

checkValidity

  • Checks the validity of the control.

    Returns Promise<ValidationInfo>

    A promise that resolves to a ValidationInfo object.

    Example

    const validityResult = await ix.api.dom.getControl("<GUID>").checkValidity();

    // example of `validityResult` - field is required, but was not filled
    ValidationInfo {
      valStatus: false,
      valMessage: 'Please make a selection',
      valType: 'required'
    }

deselectAllEntries

  • Deselects all entries (equivalent to reset).

    Parameters

    • triggerOnchange: TriggerValues = "always"

      Whether to trigger the onchange event.

    Returns void

    Example

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    ctrl.deselectAllEntries();

deselectEntries

  • Deselects given entries.

    Parameters

    • entries: HTMLOptionElement[]

      The entries to deselect.

    • triggerOnchange: TriggerValues = "always"

      Whether to trigger the onchange event.

    Returns void

    Example

    // Get all entries
    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    var entries = ctrl.getEntries();

    // Deselect entry one and two in list
    ctrl.deselectEntries([entries[0], entries[1]]);

getDisplayValue

  • Get the current value of the control.

    Returns null | string | string[]

    Display text of the selected option as string.

    • It returns null when no option is selected
    • An array containing the value of each selected option when there is at least one and it is possible to select more.

    Example

    // Control values: { value: "1", displayValue: "Option 1" }
    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    ctrl.getDisplayValue();

    // Returns:
    // "Option 1"
    // or
    // ["Option 1", "Option 2"]

getEntries

  • Returns an array of all entries as HTMLOptionElement.

    Returns HTMLOptionElement[]

    Example

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    ctrl.getEntries();

    // Returns:
    // [
    //   HTMLOptionElement,
    //   HTMLOptionElement,
    //   ...
    // ]

getSelectedEntries

  • Returns all selected entries.

    Returns HTMLOptionElement[]

    Example

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    ctrl.getSelectedEntries();

    // Returns:
    // [
    //   HTMLOptionElement,
    //   HTMLOptionElement,
    //   ...
    // ]

getValue

  • Get the current value of the control.

    Returns string

    Value of the form element as string.

    • It returns null when no option is selected
    • An array containing the value of each selected option when there is at least one and it is possible to select more.

    Example

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    var value = ctrl.getValue();
    console.log(value);

hasValue

  • Checking at least one option is selected from current control instance.

    Returns boolean

    It returns true when at least one option is selected.

    Example

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    console.log(ctrl.hasValue());

reload

  • Reloads the control.

    Parameters

    • reset: boolean

      Reset the control to its first entry.

    Returns Promise<void | Error>

    Example

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    ctrl.reload();

reset

  • Deselects all entries.

    Parameters

    • fireEvent: boolean

      Whether to trigger the onchange event triggerOnchange.

    Returns void

    Example

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    // Fires onchange event
    ctrl.reset(true);

    // Without triggering onchange event
    ctrl.reset();

selectAllEntries

  • Selects all entries.

    Parameters

    • triggerOnchange: TriggerValues = "always"

      Whether to trigger the onchange event.

    Returns void

    Example

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    ctrl.selectAllEntries();

selectFirstEntry

  • Selects the first entry.

    Parameters

    • triggerOnchange: TriggerValues = "always"

      Whether to trigger the onchange event.

    Returns void

    Example

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    ctrl.selectFirstEntry();

setDisplayValue

  • Sets the value of the control based on its display value.

    Optionally, triggers the change event based on the settings parameter.

    Parameters

    • value: string | string[]

      The display value to be set.

    • Optional settings: {
          triggerOnchange: TriggerValues;
      }

      Optional settings to control the triggering of the change event.

    Returns void

    Example

    // Control values: { value: "1", displayValue: "Option 1" }

    // Set the display value to "Option 1" and trigger the `change` event
    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    ctrl.setDisplayValue('Option 1', {
      triggerOnchange: 'always'
    });

    // Set multiple display values and trigger the `change` event
    ctrl.setDisplayValue(['Option 1', 'Option 2'], {
      triggerOnchange: 'always'
    });

setValue

  • Sets the value of the control based on its record id.

    Optionally, triggers the change event based on the settings parameter.

    Parameters

    • value: string | string[]

      The unformatted raw value to be set.

    • Optional settings: {
          triggerOnchange: TriggerValues;
      }

      Optional settings to control the triggering of the change event.

    Returns void

    Example

    // Control values: { value: ["1", "2"], displayValue: ["Option 1", "Option 2"] }
    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    // Set the value to "1" and trigger the `change` event
    ctrl.setValue('1', {
      triggerOnchange: 'always'
    });

    // Set multiple values and trigger the `change` event
    ctrl.setValue(['1', '2'], {
      triggerOnchange: 'always'
    });

triggerOnchange

  • Dispatches the onchange event.

    Returns void

    Example

    var ctrl = ix.api.dom.getControl("<ELEMENT-GUID>");
    ctrl.triggerOnchange();

Settings

Member Visibility

Theme

On This Page