@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; eye action opens a modal gallery in list mode
Preview modeIn-place gallery for all files linked to the selected object
DownloadAlways-visible download action; legacy endpoint by default or modern endpoint when explicitly enabled
Row maintenancedeleteFile, editDatasetMeta, replaceDatasetFile, 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.

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.

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, and timestamps. The cards render base64 PNG previews; the eye/download surfaces also receive a real GET /files/:guid byte endpoint.

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.