@orion-front/docs

Appearance

Files ​

Purpose ​

Use a files panel to browse, preview, download, and maintain files linked to the object selected in another panel.

When to use ​

Choose filesList for a paged grid with per-file controls. Choose preview for an always-visible document viewer. Use a file panel only when another panel publishes an object-selection event; it is not a general file repository.

Prerequisites and ownership ​

  • request.getSelectedObjectForEventId must identify an event that supplies an object GUID.
  • The panel store loads Dataset links of the selected object, resolves their file metadata, and resets when selection clears.
  • The panel owns data acquisition and file mutation calls.
  • @mes/aps-document-viewer owns document rendering in the preview surface.
  • filesList.actions are row actions. Upload belongs in panelActions.

Capability map ​

AreaSupported behavior
BindingWatches the configured selection event and reloads linked datasets when the object changes
List modePaged responsive grid, optional fixed column count, filename/size/MIME/modified metadata
PreviewsOptional card thumbnails prepared by the server; eye action opens a modal gallery in list mode
Preview modeIn-place gallery for all files linked to the selected object, one open file at a time
DownloadAlways-visible download action that saves the original file; fileDownload.useModernApi asks the browser for a save dialog once the file is downloaded, where supported and while the click still counts as a user action; otherwise the browser saves the file as usual
Row maintenancedeleteFile, editDatasetMeta, replaceDatasetFile (keeps the file GUID), and unlinkDataset through filesList.actions
Header actionsCommon panelActions, including uploadFile, rendered above the content
StatesLoading spinner and localized empty message

Behavioral model ​

Selection produces an object GUID. The store fetches links and file metadata, formats one view model per dataset, and renders either the list or preview surface. Clearing selection clears the panel. Mutations refresh the linked datasets; preview index and modal state stay panel-local.

Every file request carries the user's token, so the panel downloads content itself instead of handing a plain link to the browser:

  • Card thumbnail. When showPreviews is on and the server reports the thumbnail as ready, the card requests GET /files/{guid}/thumbnail and shows it. Otherwise the card shows the file type, for example PDF. A thumbnail that the server is still preparing appears the next time the panel loads its file list: when an object is selected, and after a file is uploaded, replaced, deleted, or unlinked or its metadata is edited.
  • Gallery. The gallery downloads only the open file. The arrows above the viewer open the previous or next file and download it then.
  • Download. The download action always saves the original file, never its thumbnail.
  • Replace. replaceDatasetFile uploads new content into the same file. The file GUID does not change, and earlier content cannot be opened or restored from the panel. Every card of this panel shows the new content at once; another panel that shows the same file shows it after its list is loaded again.

Alternatives, defaults, and precedence ​

  • variant is required: filesList or preview.
  • List page sizes default to [4, 5, 10, 15]; the first value is the initial page size.
  • Without grid.itemsInRow, CSS chooses a responsive number of columns.
  • showPreviews controls thumbnails in list cards, not the eye action or dedicated preview mode.
  • fileDownload.useModernApi defaults to false.

Limitations ​

  • No selected object means no rendered file content.
  • The panel has a fixed linked-data acquisition strategy; JSON does not define a custom file request.
  • filesList.actions must not contain uploadFile: row actions have a file and dataset context, while upload is a header action for the selected object.
  • Preview support depends on MIME type and the installed viewer. Word, Excel, and PowerPoint files are not rendered by the viewer.
  • Opening a gallery file downloads the whole file, up to 1 GiB, before the viewer shows it. The viewer receives one file at a time, so its thumbnail strip and arrow-key navigation are not available; use the arrows above it.

Minimal configuration ​

json
{
  "id": "files",
  "type": "files",
  "request": {
    "getSelectedObjectForEventId": "orders--selected"
  },
  "variant": "filesList"
}

Scenario: maintain files for a selected order ​

json
{
  "id": "order-files",
  "type": "files",
  "ui": { "title": "Attachments" },
  "request": {
    "getSelectedObjectForEventId": "orders--selected"
  },
  "variant": "filesList",
  "fileDownload": { "useModernApi": false },
  "filesList": {
    "showPreviews": true,
    "pagination": { "rowsPerPage": [6, 12, 24] },
    "grid": { "itemsInRow": 3 },
    "actions": [
      { "id": "edit-file-metadata", "method": "editDatasetMeta", "label": "Edit metadata", "icon": "pencil" },
      { "id": "replace-file", "method": "replaceDatasetFile", "label": "Replace", "icon": "upload" },
      { "id": "unlink-file", "method": "unlinkDataset", "label": "Unlink", "icon": "times" },
      { "id": "delete-file", "method": "deleteFile", "label": "Delete", "icon": "trash" }
    ]
  },
  "panelActions": [
    { "id": "upload-file", "method": "uploadFile", "label": "Upload", "icon": "plus" }
  ]
}

Expected result: selecting an order loads its linked files, upload acts on the selected order, and each row action acts on that row's file/dataset.

Runnable demos ​

Open the shared configurator journeys

Open the Files tab and select any order. The real Files store requests ObjectToDataSetLink, loads two linked Dataset objects, then calls GET /files/:guid/params for their MIME type, name, size, timestamps, and thumbnail state. The cards request GET /files/:guid/thumbnail; the eye and download actions request GET /files/:guid for the original bytes.

This fixture deliberately has no upload or row-mutation actions. It proves selection binding, filesList, previews, pagination, grid columns, metadata, and read/download transport without pretending to cover destructive behavior.

Exact parameter reference ​

Next, copy the selection/list configuration. Add upload or row mutations only after their deployed file and Dataset contracts are verified separately.