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

Files Table

The Files Table Component is a specialized form control that allows users to upload, display, and manage files within forms. It provides a tabular interface for file listings with features like file upload, file deletion, custom actions, and pagination. This component is particularly useful for document management, attachment handling in forms, media galleries, or any scenario requiring file uploads and management.

Properties

General Properties

  • displayName - Sets the display name of the component shown in the structure panel. For example, "Document Attachments" allows for easy identification of the component's purpose in the application structure, making it easier for developers to locate and work with this specific component.

  • keyExpr - Defines the field used to uniquely identify rows in the table. For example, setting to "fileId" ensures each file can be uniquely identified by this property, which is crucial for operations like deletion or updating file information in the data store.

Visual Properties

  • titleTranslations - Sets the title text displayed above the files table, with support for multiple languages. For example, {"en-US": "Uploaded Documents", "de-DE": "Hochgeladene Dokumente"} ensures proper localization of the table header for users in different regions.

  • 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 file upload capabilities based on other form values or user permissions.

  • saveInLocalStorage - Determines whether the component's uploaded files data is preserved in local storage between sessions. When enabled, file references persist between page reloads, improving user experience for complex forms that may take time to complete.

  • defaultValue - Sets the initial file data that will be used when the form is reset. For example, setting to a predefined array of file references would pre-populate the table with existing files when a form is first loaded.

  • readonly - Controls whether files can be uploaded or deleted by users. When set to true, the table displays files but prevents modifications, which is useful for review scenarios where files should only be viewed but not modified.

  • paddingClass - Configures spacing around the files table using CSS classes. For example, "p-4" adds medium padding on all sides of the table to improve visual spacing within its container.

Datasource Properties

  • getElementsDataSourceId - Specifies the data source ID for retrieving file listings. For example, "api/documents" connects the table to the documents API endpoint to fetch the list of files that should be displayed in the table.

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

  • uploadFilesDataSourceId - Specifies the data source ID for uploading files. For example, "api/documents/upload" determines the endpoint that will handle file upload operations when users add new files to the table.

  • uploadFileHttpRequestParametersMap - Configures HTTP parameters for file upload requests. This maps additional parameters needed when sending files to the server, such as metadata, categorization information, or contextual data that should accompany the file.

  • removeFileDataSourceId - Specifies the data source ID for deleting files. For example, "api/documents/{id}" would be the endpoint for removing specific files from the server and database.

  • removeEntityCollectionHttpRequestParametersMap - Configures HTTP parameters for file deletion requests. This maps additional parameters needed when removing files, such as path parameters that identify which specific file should be deleted.

  • fileNameColumnKeyExpr - Specifies which field in the data contains the file name to be displayed in the primary column. For example, setting to "fileName" or "description" determines which property holds the display text for each file in the list.

  • fileNameColumnCaptionTranslations - Sets the column header text for the filename column, with language support. For example, {"en-US": "Document Name", "de-DE": "Dokumentname"} provides proper localization for the column header.

  • enablePagination - Activates server-side pagination for large file collections. When enabled, file data is loaded in pages rather than all at once, improving performance when dealing with many files.

  • pageSize - Sets the number of files displayed per page when pagination is enabled. For example, setting to 10 will display 10 files per page, allowing users to navigate through multiple pages of files.

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

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

Non-Visual Properties

  • dataField - Defines the field name that will be used when submitting form data. For example, setting to "attachedFiles" ensures the file data is submitted with this field name in the data object, making it clear what the data represents.

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

Custom Actions Properties

  • columnCustomProps - Defines custom action icons displayed for each row in the files table. For example, a "preview" icon that opens a file viewer or a "share" icon that allows users to share the file. Each action can have its own icon, tooltip, and event handlers to perform specific operations on the selected file.

Event Actions Properties

  • events - Configures the events that the component can trigger and respond to:
    • ON_VALUE_CHANGE: Triggered when the list of files changes (files added or removed). Can be used to perform actions based on updated file collection.
    • ON_FILETABLE_UPLOAD_START: Triggered when file upload operation begins. Can be used to show loading indicators or disable certain UI elements during upload.
    • ON_FILETABLE_UPLOAD_END: Triggered when file upload operations complete. Can be used to refresh related data or show completion messages.
    • 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 files table component is initialized. Can be used to perform setup operations or initial file loading.
    • ON_DESTROY: Triggered when the component is removed from the DOM. Useful for cleanup operations and releasing resources.

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 files table for users who don't have edit permissions according to the specified policy.

  • visibilityPolicySetId - Determines the visibility of the component based on specified policy sets. For example, setting to "documentAccessPolicy" restricts the files table to users with document access privileges.

Visibility Properties

  • displayConditions - Defines conditions for displaying the component. This allows showing or hiding the files table based on complex rules involving other form values, user roles, or application state.

Testing Hooks Properties

  • id - Specifies a unique identifier for the component used for programmatic access. For example, "invoiceAttachmentsTable" enables targeted manipulation of this specific files table.

  • dataTestId - Sets the testing hook ID for automated testing. For example, setting to "doc-uploads-table" allows test scripts to reliably locate this component.

  • enableAsHotspot - Enables the component as a guided tour hotspot. When enabled, the files table can be highlighted during onboarding or tutorial flows to explain its functionality to new users.

  • guidedTourHotSpotTitle - Sets the title for the guided tour hotspot, supporting translations. For example, {"en-US": "Upload Documents Here", "de-DE": "Dokumente hier hochladen"} provides instructional text during guided tours.

  • guidedTourHotSpotDescription - Sets the description for the guided tour hotspot, supporting translations. For example, {"en-US": "Click to add files or drag and drop them here", "de-DE": "Klicken Sie, um Dateien hinzuzufügen oder ziehen Sie sie hierher"} provides detailed instructions during guided tours.

  • No labels