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

Single Select

The Single Select Component is a dropdown form control that allows users to select a single option from a list of choices. It can be configured to source its data either from a static predefined list or dynamically from an API endpoint. This component is particularly useful in forms where users need to select one item from a predefined set of options like categories, statuses, user roles, or any enumeration type data.

Properties

Visual Properties

  • placeholderTranslations - Sets the placeholder text displayed when no option is selected, with support for multiple languages. For example, {"en-US": "Select a country", "de-DE": "Land auswählen"} ensures proper localization of the placeholder text based on the user's language settings.

  • initValue - Defines an initial value that will be selected when the component is first rendered. For example, setting to "USA" would pre-select this option in the dropdown when the form loads, providing users with a default selection.

  • disabled - Controls whether the dropdown can be interacted with by users. When set to true, the dropdown appears grayed out and cannot be clicked, which is useful for display-only scenarios or conditionally disabled fields.

  • showClearIcon - Determines whether to display an icon that allows users to clear the current selection. When enabled, users can quickly reset their selection to blank rather than having to scroll to find a blank or null option.

  • hidden - Controls whether the component is visible in the form. When set to true, the component remains in the form structure but is not displayed, which is useful for conditional rendering based on other field values.

  • saveInLocalStorage - Determines whether the component's selected value is preserved in local storage between sessions. When enabled, user selection persists between page reloads, improving user experience for complex forms that may take time to complete.

  • defaultValue - Sets the value that will be used when the form is reset. For example, setting to "standard" would reset the dropdown to this value when the form's reset action is triggered.

  • readonly - Controls whether the selection can be changed by users. When set to true, the field displays the selected value but cannot be modified, which is useful for display-only scenarios or when values are determined programmatically.

Non-Visual Properties

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

  • useStaticData - Determines whether the dropdown options come from a static list or a dynamic data source. When set to true, the component uses the options defined in staticData rather than fetching from an API endpoint.

  • staticData - Specifies the predefined list of options when useStaticData is true. For example, [{"value": "usa", "text": "United States"}, {"value": "can", "text": "Canada"}] provides a fixed set of country options.

  • dataSourcePath - Specifies the path in the response data where the list of options can be found. For example, setting to "data.items" would extract options from this nested path in API responses, useful when working with complex API structures.

Datasource Properties

  • dataSourceId - Specifies the API endpoint ID for retrieving dropdown options when useStaticData is false. For example, "api/countries" would fetch the list of countries from this endpoint to populate the dropdown.

  • getEntityCollectionHttpRequestParametersMap - Configures HTTP parameters for data fetching requests. This object maps additional parameters needed for the data request, allowing customization of query parameters, headers, or path variables.

  • modelValue - Identifies which field in the API response contains the value to be submitted when an option is selected. For example, setting to "id" would use the id field from each object as the selection value.

  • modelDisplayValue - Identifies which field in the API response contains the text to display for each option. For example, setting to "name" would display the name field from each object in the dropdown list.

  • emitObject - Determines whether the entire object or just the value is submitted when an option is selected. When set to true, the complete object is emitted rather than just the key value, which is useful when additional object properties are needed elsewhere.

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

  • pageSize - Sets the number of options to load per page when pagination is enabled. For example, setting to 20 will fetch 20 records at a time, allowing for more efficient loading of large option sets.

  • loadAll - Determines whether all options should be loaded at once regardless of pagination settings. When enabled, the component will continue fetching all pages of data automatically, useful for ensuring all options are available for searching.

Validation Properties

  • validation - Configures validation rules for the single select dropdown, including:
    • required - When set to true, an option must be selected before the form can be submitted. This ensures users make a selection instead of leaving the field blank.

Authorization Properties

  • authorizationDisable - Specifies a policy set that determines when the component should be disabled based on user permissions. For example, setting to "readOnlyPolicy" will disable the dropdown for users who don't have edit permissions according to the specified policy.

Event Actions

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