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

Lookup input

User Manual for Dynamic Lookup Input Component

Overview

The Dynamic Lookup Input Component is a specialized form control that allows users to search and select an item from a popup dialog containing a data grid. It's particularly useful when selecting from large datasets where a traditional dropdown would be impractical. The component displays the selected value in a read-only input field that, when clicked, opens a dialog with a searchable data grid for item selection.

Properties

General Properties

  • displayName - Sets the display name of the component shown in the structure panel. For example, "Customer 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", "de-DE": "Kunde"} ensures proper localization of the field label.

  • dialogTitleTranslations - Sets the title text displayed at the top of the lookup dialog with support for multiple languages. For example, {"en-US": "Select Customer", "de-DE": "Kunde auswählen"} ensures users understand the purpose of the dialog.

  • dialogSubtitleTranslations - Sets an optional subtitle text displayed below the dialog title with support for multiple languages. For example, {"en-US": "Active customers only", "de-DE": "Nur aktive Kunden"} provides additional context about the displayed data.

  • 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 field's value is preserved in the user's local storage between sessions. When enabled, the selected value will persist if the user reloads the page, providing a better user experience for complex forms.

  • defaultValue - Sets the initial value to be used when the form is reset. For example, setting to "00001" would pre-select the customer with ID "00001" when the form is initially loaded or reset.

  • readonly - Controls whether the lookup value can be changed by the user. When set to true, the lookup field displays its value but cannot be modified, which is useful for display-only scenarios.

Column Properties

  • elements - Defines the columns configuration for the data grid displayed in the lookup dialog. This array contains DynamicTableColumnComponent objects that specify which fields to display in the dialog grid and how they should be formatted. For example, you can configure columns for customer ID, name, and status to help users identify the correct record.

Datasource Properties

  • getElementsDataSourceId - Specifies the data source ID for retrieving data to populate the lookup dialog. For example, "api/customers" connects the component to the customers API endpoint.

  • getEntityCollectionHttpRequestParametersMap - Configures HTTP parameters for data fetching. This object maps additional parameters needed for the API request, which can include query parameters, path parameters, or fixed values that should be sent with every request.

  • enablePagination - Activates server-side pagination for large datasets in the lookup dialog. When enabled, data is loaded in pages rather than all at once, significantly improving performance for tables with many records.

  • pageSize - Sets the number of records displayed per page in the lookup dialog. For example, setting to 25 will display 25 records per page when pagination is enabled, providing a balance between visibility and performance.

  • valueKey - Defines the field in the data objects that should be used as the value when an item is selected. For example, setting to "id" will store the ID of the selected customer as the field value.

  • displayValueKey - Defines the field in the data objects that should be displayed in the input field after selection. For example, setting to "name" will show the customer's name in the input field, even though the ID might be stored as the actual value.

Non-Visual Properties

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

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

Validation Properties

  • validation - Configures validation rules for the lookup input, including:
    • required - When set to true, the field must have a selection before the form can be submitted. This ensures users make a selection when the information is essential.

Authorization Properties

  • authorizationDisable - Specifies a policy set that determines when the component should be disabled. For example, setting to "readOnlyPolicy" will disable the field 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_INIT: Triggered when the 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.

Testing Hooks

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