Working with files and images

Store a Single Image in an Aggregate

When to use:
Choose this approach when the aggregate requires exactly one image field that is tied to a specific business purpose, such as:

An equipment photo in an asset record
A user profile picture in an account
A company logo in an organization profile

This is useful when the image:

Has its own dedicated update command and access permissions
Must always represent the same type of visual (not an arbitrary collection of images)
Should be stored, displayed, and managed as a single value rather than part of a gallery or list

How to:

1. Define the image field and update command

Add a field of type Image to the aggregate.
Create a command (e.g., updateImage).
Add the image field as a command parameter.

2. For in-place viewing and editing

Drag and drop the image field onto the screen.
Select the “Value only” display option.
Click the image component to review its configuration.
Remove the update command from the configuration if you want the image to be read-only.
If the update command is kept:
- Clicking the image will prompt the user to browse for a new file if none is set.
- If an image is already set, clicking will clear it.

3. To use a dialog for editing

Drag and drop the image field onto the screen.
Select the “Value and label” display option.
Click the field component to review its configuration.
Clicking the field opens a standard action dialog.
- The dialog can be configured to allow clearing the image (if the parameter is not marked as required).
- The dialog can also allow selecting a new image.
- You can add additional parameters to the update command for more complex update logic.

Store a Single File in an Aggregate

When to use:
Use this pattern when an aggregate needs to store one specific, named file that has its own update command and access permissions. This is ideal when:

The file serves a dedicated business purpose and is always the same type of document.
It must be managed independently from other files in the system.
Access rights and update rules differ from other documents in the aggregate.

Example:
An Employee record might store three separate documents—employmentContract, jobDescription, and signedNDA—each requiring its own permissions and update logic. Instead of treating them as a single collection of attachments, define each as an individual file field.

How to:

1. Define the file field and update command

Add a field of type File to the aggregate.
Create a command (e.g., updateFile).
Add the file field as a parameter to that command.

2. Add the field to the screen

Drag and drop the file field onto the screen.
Select the “Value and label” display option.
Click the field component to review its configuration.

3. Configure file interaction

Clicking the field will open a standard action dialog.
- The dialog allows the user to clear the file (if the parameter is not marked as required).
- The dialog allows the user to browse and select a new file.
- You can add extra parameters to the update command for more complex update logic.

Store a Collection of Files in an Aggregate

When to use:
Use this pattern when an aggregate needs to store and manage multiple related files of the same type as a set, rather than as separate named fields. This is ideal when:

All files share the same update command and permissions.
Files are added, displayed, and removed from one unified list.
The number of files can change over time.

Example:
A Project record might store reference images, design drafts, or supporting documents that all follow the same rules. Instead of creating one field per file, store them together in a single file collection field for simpler management.

1. Define the collection field and update command

Add a field of type File to the aggregate.
Mark it as a collection.
Create a command (e.g., updateFiles).
Add the file collection field as a command parameter.

2. Easiest option — automatic display with built-in file management

Drag and drop the command onto the screen and select “Automatic form”.
Remove the Submit and Cancel buttons.
In the Page Structure panel, select the box that has the Create a Command Form behavior and enable auto-save.

Result:
This automatically renders a file list that allows:

Uploading new files
Deleting existing files
Downloading files by clicking them

No extra wiring or custom logic is needed.

3. Advanced — create a custom display

Drag and drop the file field onto the screen.
Choose Repeater as the display type.
Drag and drop the command and select a Button type.
Activate Play mode, click the button, and select one or more files to upload.
Deactivate Play mode.
Style the repeater to match your layout.
Bind the click event on repeater items to execute the update command.

4. Support deletion of individual files (custom approach)

Create the delete command:

Create a deleteFile command.
Add a storageId parameter (type: Text).
Create a new mutation field targeting the collection field.
In the mutation field, use:

return data.files.reject({ storageId }).add({ $replace: true })

Wire up the UI:

In the repeater, add an Add Dependency behavior before Set Component Data:
- Name: parentData
- Value: data
Add a trash icon to each repeater card.
On the trash icon’s onClick event, add a Show Custom Dialog behavior.
In the dialog’s On submit, run:

parentData.removeFile({ storageId: data.storageId })

Store a Collection of Files in an Aggregate where each file has domain-specific fields

When to use

Choose this when each file is essentially an entity with its own data and lifecycle, not just an attachment. Typical needs:

Custom metadata (e.g., owner, status, tags)
Domain commands (e.g., Approve, Reject)
Workflows/lifecycle (e.g., Draft → Approved → Archived)

Example:
A Project has a documents collection of Document entities. Each Document has a single file (content), plus fields like owner and status, and commands such as Approve / Reject.

Define the collection field and entity in the aggregate

1. Add the collection to the aggregate

Create a new field on the aggregate (e.g., documents).
Set its type to New Entity.
When prompted, name the entity Document.
The UI links documents (collection) ↔ Document (entity).

2. Add fields to the new entity

In Document, add a File field (e.g., content).
Add any domain fields you need (e.g., owner, status, tags).

3. Create the update command on the parent

On the aggregate, create updateDocuments (regular command, not “Entity Create”).
Add the documents collection as a parameter, make sure the parameter is set as a collection (Is Collection).
Set the mutation for that parameter to Replace values.

4. Create the delete command on the entity

On Document, add a standard Delete command.

5. Configure the upload dialog (on updateDocuments)

Add a Dialog declaration.

Configure the documents field:

componentId: @skyjs/data-model/web/DocumentsInput
props: { "hidePreview": true, "fieldName": "content" }
Hide label : true

fieldName must match the entity’s single File field.

6. Set default values when adding new files

In the parameter’s onChange property, use:
```
return newValue => newValue.assignNewDocumentsValues(
  { uploadDate: new DateTime(), owner: currentUser, status: 'DRAFT' },
  data
);
```
This code is your chance to set default values for your custom entity when new files are added. You could, for example, set the current user as the owner, initialize a status, or apply any other default metadata relevant to your domain.

UI — Automatic file list via command form

Drag updateDocuments onto the screen → choose Manual form.
Remove Submit and Cancel buttons.
In Page Structure, select the box with Create a Command Form → enable auto-save.

Result:
A working list that supports upload, delete, and download.

With "hidePreview": true, selected files won’t show the default preview.
Set it to false for filename/size, or build a custom view (below) to show domain fields and actions.

UI — Custom document cards in a Repeater

Drag the documents collection onto the screen → choose Repeater.
Drag updateDocuments onto the page → choose a Button type.
In Play mode, click the button and select one or more files; exit Play mode.
Style the repeater.
Inside each card:
- Add the Delete command (button/icon/link).
- Add your domain commands (e.g., Approve / Reject).
- Display fields like owner, status, tags, uploadDate.
To allow downloading the file, attach to a filename component or download icon a Execute JavaScript behavior:

window.location = await getFileUrl("get", data.content.storageId, data.name)

data.content = your content field name
data.name = suggested download filename