File / File List
Shesha provides two related file components. File handles a single file attachment - a user can upload, replace, or delete one file linked to a record. File List manages a collection of attachments with richer display options, version history, bulk download, and custom actions per file. Both components link uploaded files to a specific entity record using an owner ID and owner type.
File
The File component provides a single-file upload field. The user uploads one file at a time. Depending on your settings, they can also replace or delete it. It appears on the form as an upload button or, optionally, as a drag-and-drop zone.
The following properties are available to configure the behavior of the File component from the form editor (this is in addition to common properties).
Common
List Type object
Controls how the uploaded file is displayed once it has been added.
| Option | Description |
|---|---|
File Name | Displays the file as its name, with a download/action icon. This is the default. |
Thumbnail | Displays the file as an image preview. Use this when the file is expected to be an image. |
Hidden when Is Dragger is enabled.
Is Dragger boolean
When enabled, the upload area becomes a large drag-and-drop zone instead of a button. Users can drag a file from their desktop and drop it directly onto the field.
Hidden when List Type is Thumbnail.
Hide File Name boolean
When enabled, the file name is hidden below the thumbnail. Only appears when List Type is Thumbnail.
Allow Upload boolean
Controls whether the user can upload a new file. When disabled, the upload button is hidden and no file can be added. Hidden when the component is in read-only mode.
Allow Replace boolean
Controls whether the user can replace the existing file with a new version. When enabled, a replace action appears on the uploaded file. Hidden when the component is in read-only mode.
Allow Delete boolean
Controls whether the user can delete the uploaded file. When enabled, a delete control appears on the file. Hidden when the component is in read-only mode.
Files
These settings sit in a labelled Files panel on the Common tab. They control what the user may do with the file and which record it belongs to.
Owner ID string
The ID of the entity record that owns this file. Shesha uses this to link the uploaded file to the correct record. You can enter a static ID or a JavaScript expression that resolves to an ID at runtime.
Owner Type string
The entity type that owns this file (for example, Shesha.Domain.Person). Use the autocomplete to select a registered entity type.
Synchronous Upload boolean
When enabled, the file is uploaded to the server immediately when the user selects it, before the form is submitted. When disabled, the file is held in memory and uploaded when the form saves.
Use synchronous upload when you need the file available on the server before the form is submitted, for example to generate a document or trigger a backend process.
Allowed File Types array
Restricts which file types the user can upload. Enter one or more MIME types or file extensions, for example .pdf, image/jpeg. Leave empty to accept all file types.
Once the user downloads the file, its value carries a userHasDownloaded flag set to true. You can use this flag in conditional expressions on other components, for example to enable a Continue button only after a required file has been downloaded.
File List
The File List component manages a collection of file attachments on a record. Users can add, remove, and replace files. The list can display as a simple file-name list or as a thumbnail grid for image-heavy use cases. It also supports version history, bulk zip download, custom per-file actions, and embedded custom content beneath each file.
The following properties are available to configure the behavior of the component from the form editor (this is in addition to common properties).
Common
Is Dragger boolean
When enabled, the upload area becomes a large drag-and-drop zone. Hidden when List Type is set to Thumbnail.
List Type object
Controls how uploaded files are displayed. Hidden when Is Dragger is enabled.
| Option | When to use |
|---|---|
File Name | Displays files as a simple list of names. Use this for documents and general attachments. |
Thumbnail | Displays files as image previews. Use this when files are images. |
Hide File Name boolean
When enabled, the file name is hidden below each thumbnail. Only appears when List Type is Thumbnail.
Allow Add boolean
Controls whether the user can upload new files. When disabled, the upload control is hidden. Hidden when the component is in read-only mode.
Allow Remove boolean
Controls whether the user can remove files from the list. When disabled, the remove control is hidden on each file. Hidden when the component is in read-only mode.
Allow Replace boolean
Controls whether the user can replace an existing file with a new version. Hidden when the component is in read-only mode.
Allow View History boolean
When enabled, users can open a version history panel for each file to see all previously uploaded versions.
Download Zip boolean
When enabled, a button appears that lets users download all files in the list as a single zip archive.
Custom
A collapsible sub-panel within the Common tab that configures custom per-file actions and extra content.
Custom Actions object
Opens the action configurator to add buttons that appear on each file in the list. Each action can define an id, name, label, icon, tooltip, visibility, and the action it triggers.
Show Custom Content boolean
When enabled, a custom form is rendered below each file in the list. Use this to display extra metadata or controls alongside each attachment. Enabling this reveals the next three properties.
Form Selection Mode object
Shown when Show Custom Content is enabled. Controls how Shesha determines which form to render below each file.
| Option | When to use |
|---|---|
Name | You pick a specific form by name. |
Dynamic | Shesha selects the form automatically based on form type. |
Form Type string
Shown when Show Custom Content is enabled and Form Selection Mode is Dynamic. Enter or select the form type to look up.
Form object
Shown when Show Custom Content is enabled and Form Selection Mode is Name. Select the form to render below each file.
Data
Owner string
The property path on the form's data object that contains the owner record. Use this when the owner is derived from the form's current data rather than a static value.
Owner Type string
The entity type that owns these files (for example, Shesha.Domain.Person). Use the autocomplete to select a registered entity type.
Owner ID string
The ID of the entity record that owns these files. Shesha uses this to link all uploaded files to the correct record.
Files Category string
An optional label that groups uploaded files into a named category. Use this when a single record needs multiple distinct sets of files (for example, identity-documents and supporting-evidence). Add two File List components with different Files Category values to keep the groups separate.
Allowed File Types array
Restricts which file types the user can upload. Enter one or more MIME types or file extensions, for example .pdf, image/jpeg. Leave empty to accept all file types.
Events
Events are JavaScript handlers that run when the user interacts with the file list. All event handlers have access to the following variables, plus all standard constants such as data, form, actions, utils, and page.
| Variable | Type | Description |
|---|---|---|
value | any | The component's current file list value. |
event | object | The event data from the interaction that triggered the handler. |
On File List Changed function
Fires whenever the file list changes - when a file is added, removed, or replaced. Use it to react to uploads, update a status field, or trigger a follow-up action.
Form type to use: Edit Form - use when files are being attached to an existing record.
Example - Show a confirmation message when a file is uploaded:
actions.showMessage.success('File list updated.');
On Download function
Fires when a user downloads a file from the list. Use it to log download activity or trigger a follow-up action.
Each file in the list carries a userHasDownloaded flag that becomes true once the user downloads that file. You can use this flag in conditional expressions on other components, for example to keep a Submit button hidden or disabled until the user has downloaded a required document.
Files uploaded through a File List persist when the user navigates between Wizard steps. A file added on one step is still there if the user moves to another step and back.
Appearance
The Font, Dimensions, Border, Background, Shadow, Margin & Padding, and Style settings on this tab work the same way as described in the common properties. File List adds two extra sub-panels that are unique to this component, documented below as their own sections.
Container Styles
A collapsible panel within the Appearance tab that styles the container wrapping the thumbnails, separately from the file items themselves.
Layout object
Controls how thumbnails are arranged on screen. Only appears when List Type is Thumbnail and Is Dragger is disabled.
| Option | When to use |
|---|---|
Vertical | Thumbnails stack in a single column. |
Horizontal | Thumbnails flow left to right in a single row. |
Grid | Thumbnails wrap into a multi-row grid. Use this for larger collections of images. |
Gap number
The spacing between thumbnails in pixels. Only appears when List Type is Thumbnail.
The Container Styles panel also contains its own Dimensions, Margin & Padding, and Custom Style (Style script) controls, which apply to the container rather than the component as a whole. These work the same way as the equivalent controls described in the common properties.
Downloaded File Styles
A collapsible panel within the Appearance tab, collapsed by default, that lets you style a file differently once the current user has downloaded it.
Style Downloaded File boolean
When enabled, reveals the Icon setting below, plus a Font sub-panel and a Custom Styles sub-panel that only apply to downloaded files.
Icon string
Shown when Style Downloaded File is enabled. Select an icon to show next to a file the user has already downloaded.
The Font and Custom Styles controls inside this panel work the same way as the equivalent controls described in the common properties, but only apply once a file has been downloaded.