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

Table Selection

Overview

The Dynamic Table Selection Component is an advanced form control that allows users to select one or multiple items from a table-based dropdown. This component combines the convenience of a form field with the power of a data grid, making it ideal for scenarios where users need to select from a large or complex dataset that is better presented in a table format rather than a standard dropdown list.

Properties

General Properties

  • keyExpr - Defines the field used to uniquely identify rows in the table. For example, setting keyExpr to "customerId" ensures each row can be uniquely identified by its customer ID, which is essential for tracking selections and data operations.

Visual Properties

  • 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. When enabled, user selections persist between page reloads, improving user experience for complex forms that may take time to complete.

  • defaultValue - Sets the initial value that will be used when the form is reset. For example, setting to "10001" would pre-select the record with ID "10001" when the form initially loads.

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

  • selectionMode - Sets the selection behavior of the component: "single" (one row) or "multiple" (many rows). For example, "multiple" allows selecting several customers for a bulk operation, while "single" restricts to one selection only.

Column Properties

  • elements - Defines the columns configuration for the data grid displayed in the selection 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 user ID, name, and email to help users identify the correct record.

  • fieldsUsedInSearch - Specifies which data fields are included when searching within the component. For example, setting to ["name", "email", "companyName"] ensures the search functionality looks through these specific fields when users type in the search box.

Datasource Properties

Table Selection Datasource

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

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

  • enablePagination - Activates server-side pagination for large datasets. 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 table. For example, setting to 25 will display 25 records per page when pagination is enabled, providing a balance between visibility and performance.

  • paginationRequestParamsMap - Maps client-side pagination parameters to server-expected parameters. For example, {"page": "pageNumber", "size": "pageLimit"} adapts to server naming conventions when making pagination requests.

  • paginationResponseFieldsMap - Maps server pagination fields to client expectations. For example, {"content": "data", "totalElements": "count"} handles different response structures from the server.

  • useFiltersInRequestBody - Places filters in the request body instead of URL parameters. When enabled, filter data is sent in the request body, which is better for complex filters or when URL length limitations might be a concern.

  • paginationFilterFieldsMap - Maps filter field names for pagination requests. For example, {"value": "filterValue", "key": "filterField"} adapts to server filter naming conventions.

  • filterOperatorsMap - Configures the mapping between client-side filter operators and server-side filter operators. For example, {"contains": "like", "=": "eq"} ensures that the filtering operations use the correct syntax for the backend API.

  • dataSourcePath - Specifies the path within the response data where the list of options is located. For example, setting this to "data.items" will extract the dropdown items from that location in the response structure.

Non-Visual Properties

  • dataField - Defines the field name that will be used when submitting form data. For example, setting to "selectedEmployeeIds" ensures the selected employee IDs are 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 table selection control, 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.
    • ON_VALUE_CHANGE: Triggered when the user changes their selection. 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 to "employee-selection-table" allows test scripts to reliably locate this component.
  • No labels