Page History
...
- 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.
Guidelines
(From General UX Concepts – Table Guidelines)
- Table headers should use clear and descriptive labels, aligned with content, and remain visible when scrolling.
- Column sorting should be available where useful, with clear visual cues.
- Filters should be supported for large datasets, placed close to the table, and easy to use.
- Zebra tables should be used to improve readability for dense data.
- Pagination should be preferred over infinite scroll for long lists, with consistent page sizes.
- Responsiveness must be ensured on smaller screens, using horizontal scroll or column reduction if needed.
- Actions such as edit or delete should be placed consistently at the end of rows, with recognizable icons and tooltips.
Accessibility
...
Usage
- Use the Files Table to upload, list, and remove attachments within forms by wiring the three data sources:
getElementsDataSourceId(list),uploadFilesDataSourceId(upload), andremoveFileDataSourceId(delete), plus their respective*HttpRequestParametersMapsettings 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 |
| Use upload start/end events to show progress and refresh. | Leave uploads silent with no completion handling. | ON_FILETABLE_UPLOAD_START, ON_FILETABLE_UPLOAD_END |
| 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.
