(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Combobox

The Dynamic Combobox Component is a form control that provides a dropdown selection interface, allowing users to select a single value from a list of options. The component supports both static data and dynamic data fetched from server endpoints, with features including search, pagination, and customizable display formats. It's especially useful for selecting from large datasets where a traditional select input would be impractical.

Properties

General Properties

• displayName - Sets the display name of the component shown in the structure panel. For example, "Customer Type Selector" allows for easy identification of the component's purpose in the component structure.

Visual Properties

• labelTranslations - Sets the field label with support for multiple languages. For example, {"en-US": "Customer Type", "de-DE": "Kundentyp"} ensures proper localization of the field label.

• showClearIcon - Controls whether an icon is displayed to clear the selected value. When enabled, a small "x" button appears in the combobox when a value is selected, allowing users to quickly reset their selection.

• saveInLocalStorage - Determines whether the combobox's selected value is preserved in local storage. When enabled, the user's selection persists between page reloads or browser sessions, improving user experience.

• defaultValue - Sets the initial value of the combobox when first rendered. For example, setting to "corporate" would pre-select the corporate customer option.

• readonly - Controls whether the combobox allows user interaction. When set to true, the combobox will display its value but not allow changes, useful for display-only scenarios.

Non-Visual Properties

• useStaticData - Determines whether the component uses static data defined in the component configuration or fetches data from an API endpoint. When set to true, the component will use the data provided in the staticData property rather than calling an API.

• staticData - Defines the list of options that will be available in the dropdown when useStaticData is enabled. For example, [{"value": "corporate", "text": "Corporate Customer"}, {"value": "individual", "text": "Individual Customer"}] provides two selectable customer types.

• dataSourcePath - Specifies the path within the response data where the list of options is located. For example, if the API returns data in a nested structure, setting this to "data.customers.types" will extract the options from that location.

• dataField - Defines the field name that will be used when submitting form data. For example, setting to "customerType" ensures the selected value is submitted with this field name in the form data.

• controlsRequestType - Specifies how the field data is sent in HTTP requests: 'BODY' (in request body) or 'HEADER' (in request headers). For example, setting to "BODY" includes the field data in the request body, which is standard for most form submissions.

Datasource Properties

• dataSourceId - Specifies the data source ID for retrieving dropdown options. For example, "api/customerTypes" connects the combobox to the customer types API endpoint. This property is used when useStaticData is false.

• getEntityCollectionHttpRequestParametersMap - Configures HTTP parameters for data fetching. This object maps additional parameters needed for the API request, such as filters or sorting options.

• modelValue - Defines the field in the returned data objects that should be used as the value when an option is selected. For example, setting to "id" will use the id property of each data object as the value.

• modelDisplayValue - Defines the field in the returned data objects that should be displayed in the dropdown. For example, setting to "name" will display the name property of each data object to the user.

• searchKey - Specifies which field in the data objects should be used for filtering when users type in the combobox. For example, setting to "name" will search through the name property of data objects.

• emitObject - Controls whether the entire selected object is emitted as the value, rather than just the key field. When enabled, the complete data object is available in form submissions rather than just the ID value.

• pageSize - Sets the number of items loaded per page when fetching data from the server. For example, setting to "20" will load 20 records at a time, with pagination controls allowing access to additional pages.

• loadAll - Determines whether all available data should be loaded at once rather than using pagination. When enabled, the component will attempt to fetch all records in a single request, which can be useful for smaller datasets.

Validation Properties

• validation - Configures validation rules for the combobox, including:
  • required - When set to true, the field must have a selection before the form can be submitted.

Event Actions

• events - Configures the events that the component can trigger and respond to:
  • ON_INIT: Triggered when the combobox component is initialized. Can be used to perform setup operations like loading initial configuration.
  • ON_DESTROY: Triggered when the component is removed from the DOM. Useful for cleanup operations and releasing resources.
  • ON_VALUE_CHANGE: Triggered when the user selects a different option. Can be used to perform immediate actions based on the selection, such as loading related data.
  • ON_INIT_BASED_ON_USER_VIEW: Triggered specifically when the component initializes in user view mode rather than edit mode.

Testing Hooks

• dataTestId - Sets the testing hook ID for automated testing. For example, setting it to "customer-type-selector" allows test scripts to reliably locate this component.