data-files

Overview

data-files binds existing file metadata onto a file input so FileElementFactory can show previews for already-uploaded files.

It is the correct directive when you want to display server-side files on <input type="file"> elements. It does not set the browser's native file value.

Why use it:

• ✅ Displays existing uploaded files declaratively
• ✅ Accepts a single file object or an array of file objects
• ✅ Reactive when file metadata is rebound
• ✅ Clears stale previews automatically when the expression becomes empty

Basic Usage

Existing Avatar

<input type="file"
       name="avatar"
       data-preview="true"
       data-files="avatarFiles"
       data-file-reference="url">

{
  avatarFiles: [
    { url: 'uploads/avatar.jpg', name: 'avatar.jpg' }
  ]
}

Single File Object Also Works

<input type="file"
       name="resume"
       data-files="resume">

{
  resume: {
    url: 'uploads/resume.pdf',
    name: 'resume.pdf'
  }
}

Expected File Shape

The minimum useful shape is:

{
  "url": "uploads/document.pdf",
  "name": "document.pdf"
}

Additional properties such as size, size_text, id, or timestamps can also be present and may be used by surrounding UI.

Reactive Behavior

When the data-files expression changes:

• the expression is evaluated again
• the generated data-files JSON attribute is refreshed
• existing previews are replaced when a FileElementFactory instance already exists
• old previews are removed if the expression becomes empty

This makes data-files suitable for API-loaded edit forms and for blocks that are rebound with new records.

Common Pitfalls

1. Using data-attr="value:..." on File Inputs

<!-- ❌ Browser security prevents this -->
<input type="file" data-attr="value:filePath">

Use data-files instead.

2. Using It on Non-file Inputs

data-files only makes sense on <input type="file">.

3. Returning the Wrong Type

If the expression resolves to a non-object value, nothing is shown.

Related Directives

• data-attr - One-way attribute binding
• data-model - Read newly selected files from the native input
• data-bind - Bind structured row data to managed tables