Files Table

Overview

• The Files Table Component allows users to upload, display, and manage files in forms.
• It provides a table interface for file listings with upload, deletion, and custom actions.
• Pagination is supported for handling large file collections.
• It is useful for document management, attachment handling, or media galleries.

Specs

Tokens

Token	Description
displayName	Display name of the component in the structure panel
keyExpr	Field used to uniquely identify rows
titleTranslations	Title text above the files table with language support
hidden	Controls if the component is visible
saveInLocalStorage	Preserves uploaded files in local storage
defaultValue	Sets initial file data when form resets
paddingClass	Spacing around the table via CSS classes
getElementsDataSourceId	Data source ID for retrieving file listings
getEntityCollectionHttpRequestParametersMap	HTTP parameters for fetching file data
uploadFilesDataSourceId	Data source ID for uploading files
uploadFileHttpRequestParametersMap	HTTP parameters for file upload
removeFileDataSourceId	Data source ID for deleting files
removeEntityCollectionHttpRequestParametersMap	HTTP parameters for file deletion
fileNameColumnKeyExpr	Field containing the file name
fileNameColumnCaptionTranslations	Column header text for file name with translations
enablePagination	Enables server-side pagination
pageSize	Number of files displayed per page
paginationRequestParamsMap	Maps client pagination parameters to server format
paginationResponseFieldsMap	Maps server pagination fields to client format
dataField	Field name used when submitting form data
controlsRequestType	Defines how field data is sent in requests
columnCustomProps	Custom action icons for each row
events	Configures component events
ON_VALUE_CHANGE (Events)	Event triggered when files change
ON_FILETABLE_UPLOAD_START (Events)	Event triggered when upload begins
ON_FILETABLE_UPLOAD_END (Events)	Event triggered when upload completes
ON_INIT_BASED_ON_USER_VIEW (Events)	Event triggered on init in user view mode
ON_INIT (Events)	Event triggered when component initializes
ON_DESTROY (Events)	Event triggered when component is removed
authorizationDisable	Policy that disables component by permission
visibilityPolicySetId	Policy controlling component visibility
displayConditions	Conditions for displaying the component
id	Unique identifier for programmatic access
dataTestId	Testing hook ID
enableAsHotspot	Enables guided tour hotspot
guidedTourHotSpotTitle	Title for guided tour hotspot with translations
guidedTourHotSpotDescription	Description for guided tour hotspot with translations
readonly	Displays files but prevents modifications (view-only)

Structure

(Configured in General Properties)

• keyExpr – Defines the field used to uniquely identify rows in the table.

(Configured in Datasource Properties)

• getElementsDataSourceId – Specifies the data source ID for retrieving file listings.
  • getEntityCollectionHttpRequestParametersMap – Configures HTTP parameters for fetching file collection data.
• uploadFilesDataSourceId – Specifies the data source ID for uploading files.
  • uploadFileHttpRequestParametersMap – Configures HTTP parameters for file upload requests.
• removeFileDataSourceId – Specifies the data source ID for deleting files.
  • removeEntityCollectionHttpRequestParametersMap – Configures HTTP parameters for file deletion requests.
• fileNameColumnKeyExpr – Specifies which field contains the file name to display.
  • fileNameColumnCaptionTranslations – Sets the column header text for the filename column with language support.

(Configured in Non-Visual Properties)

• dataField – Defines the field name used when submitting form data.
• controlsRequestType – Specifies how the field data is sent in HTTP requests (BODY, HEADER, PATH).

(Configured in Visibility Properties)

• displayConditions – Defines conditions for displaying the component.

Pagination

(Configured in Datasource Properties)

• enablePagination – Activates server-side pagination for large file collections.
• pageSize – Sets the number of files displayed per page.
• paginationRequestParamsMap – Maps client-side pagination parameters to server parameters.
• paginationResponseFieldsMap – Maps server pagination fields to client expectations.

Styling

(Configured in Visual Properties)

• Title – Sets the title text displayed above the files table.
  • titleTranslations – Supports multiple languages for the title.
• hidden – Controls whether the component is visible in the form.
• saveInLocalStorage – Determines whether the uploaded files data is preserved in local storage.
• defaultValue – Sets the initial file data when the form is reset.
• paddingClass – Configures spacing around the files table using CSS classes.

Actions & Variants

(Configured in Event Actions Properties)

• events – Configures the events that the component can trigger and respond to:
  • ON_VALUE_CHANGE (Events) – Triggered when the list of files changes.
  • ON_FILETABLE_UPLOAD_START (Events) – Triggered when a file upload begins.
  • ON_FILETABLE_UPLOAD_END (Events) – Triggered when file uploads complete.
  • ON_INIT_BASED_ON_USER_VIEW (Events) – Triggered when the component initializes in user view mode.
  • ON_INIT (Events) – Triggered when the component is initialized.
  • ON_DESTROY (Events) – Triggered when the component is removed from the DOM.

(Configured in Custom Actions Properties)

• columnCustomProps – Defines custom action icons displayed for each row, such as preview or share icons.

(Configured in Visual Properties)

• readonly – Displays files but prevents modifications, making the table view-only.

Authorization

(Configured in Authorization Properties)

• authorizationDisable – Specifies a policy set that determines when the component should be disabled based on user permissions.
• visibilityPolicySetId – Determines the visibility of the component based on specified policy sets.

Testing

(Configured in Testing Hooks Properties)

• id – Specifies a unique identifier for the component used for programmatic access.
• dataTestId – Sets the testing hook ID for automated testing.
• enableAsHotspot – Enables the component as a guided tour hotspot.
• guidedTourHotSpotTitle – Sets the title for the guided tour hotspot, supporting translations.
• guidedTourHotSpotDescription – Sets the description for the guided tour hotspot, supporting translations.

Links

• Figme: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11528-202526&t=ftfrOGkPzlG2GaTo-1
• Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/id3/8-file-uploader

Guidelines

Usage

• Use the Files Table to upload, list, and remove attachments within forms by wiring the three data sources: getElementsDataSourceId (list), uploadFilesDataSourceId (upload), and removeFileDataSourceId (delete), plus their respective *HttpRequestParametersMap settings for request details.
• Provide a clear, localized title above the table so users know the scope of files shown.
• Ensure each row is uniquely addressable to avoid collisions when files share names or are updated.
• Preserve user-selected files during multi-step form work by caching between edits.

Sizing & Layout

• Apply spacing around the table using the component’s padding token; do not hard-code margins externally.
• Prefer server-side pagination for large collections and set a page size that balances scan-ability and navigation effort.
• Map client pagination args and server response fields explicitly so paging stays stable across APIs.

States & Feedback

• Surface upload progress to the host logic by reacting to start/end events; use them to drive toasts, spinners, or refreshes.
• React to content changes (add/remove) to keep dependent logic in sync (e.g., enable a “Submit” when at least one file exists).

Visibility & Authorization

• Gate visibility by policy and show/hide based on runtime conditions without rebuilding the form.
• Keep the table visible but non-interactive when policy requires read-only access.

Content & Localization

• Localize all user-facing strings in the header and filename column caption.
• Provide guided tour affordances only when they add clarity to file actions or purpose.
• Expose stable hooks for automated tests.

Dos & Don’ts

Do	Don’t	Article setting(s)
Set keyExpr so each row is uniquely identifiable.	Rely on array index or file name only for identity.	keyExpr
Localize the table title and filename column header.	Hard-code English strings.	titleTranslations, fileNameColumnCaptionTranslations
Configure all three data sources before enabling user actions.	Attempt uploads/deletes without endpoints mapped.	getElementsDataSourceId, uploadFilesDataSourceId, removeFileDataSourceId, *HttpRequestParametersMap
Enable pagination and pick a consistent pageSize.	Dump hundreds of files into a single page.	enablePagination, pageSize
Map client and server paging fields explicitly.	Depend on unspecified backend defaults.	paginationRequestParamsMap, paginationResponseFieldsMap
Cache selections during long edits.	Risk data loss when navigating between steps.	saveInLocalStorage
Make destructive actions explicit via row icons.	Hide delete in external flows only.	columnCustomProps, removeFileDataSourceId
Lock to read-only when edits aren’t allowed.	Fake read-only by just hiding delete icons.	readonly, authorizationDisable
Submit files using the correct field and channel.	Post file data in the wrong request part.	dataField, controlsRequestType

Accessibility

• Localize user-facing strings so labels and captions are announced correctly by assistive technologies.
• Keep lists manageable via paging to reduce cognitive load and excessive tab stops.
• Avoid color-only meaning; pair row actions with consistent icons and clear column captions.
• Prevent interaction confusion by switching to read-only when edits aren’t allowed, instead of hiding the component.
• Use pagination mappings to ensure predictable focus order when data updates.
• Provide guided hints only as supplemental onboarding—not as the sole source of critical instructions.