Version: 13.x (Current)

File Picker Modal

<bk-file-picker-modal></bk-file-picker-modal>

The File Picker Modal renders a modal containing a drag-and-drop area to handle file uploads / downloads.

The File Picker Modal is designed to handle fields that hold metadata about storage location for files saved in a file storage service and handled by Mia Platform's Files Service. Such fields are identifiable in a data-schema as fields of type object or array and format file, and their value is expected to extend the schema:

{
  "_id": {
    "type": "string"
  },
  "name": {
    "type": "string"
  },
  "file": {
    "type": "string"
  },
  "size": {
    "type": "number"
  },
  "location": {
    "type": "string"
  }
}

The File Picker Modal opens when a component signals the request to update a file field associated to the item of a collection with event link-file-to-record, and allows interaction with such field through a drag-and-drop area.

In particular, it allows:

request the download of the corresponding file from the file storage service, via the download-file event. Such event could be handled by a component such as the File Service Client.
The upload of new files, with consequent update of the CRUD collection item with the storage metadata of the new file. This request is signaled with the update-data-with-file event, and could be picked up by a component such as the File Manger.

Further details on how Back-Kit components can be composed to handle file fields are available in the specific section.

How to configure

For its basic usage, File Picker Modal does not require any configuration.

{
  "tag": "bk-file-picker-modal"
}

However, such File Picker Modal assumes handled file field to always be of type object - that is, links at most one file to the field. A data-schema should be provided to the File Picker Modal with dataSchema property in case the file filed to handle might be of type array (thus allowing multiple files to be linked to it), or if the uploaded files should have extra metadata.

Metadata

File fields may themselves have a dataSchema or items property.

When that is the case, the File Picker Modal not only include the drag-and-drop area but also provides an area to edit the additional metadata associated with the file field. For file fields of type object, a form is displayed, while for file fields of type array, an accordion of forms.

caution

Only fields of type string are supported for metadata.

{
  "tag": "bk-file-picker-modal",
  "properties": {
    "dataSchema": {
      "type": "object",
      "properties": {
        "image": {
          "type": "object",
          "format": "file",
          "dataSchema": {
            "type": "object",
            "properties": {
              // <- here are fields to be handled as metadata associated to the `image` field
            }
          }
        }
      }
    }
  }
}

Preview Files

The File Picker Modal offers a file preview feature located below the drag-and-drop area. Specifically, it allows for the preview of uploaded files that are currently associated with the field under consideration. This preview functionality can be enabled by configuring the previewUploadedFiles property with the value "preview".

Moreover, when the previewUploadedFiles property is configured as "fetch", the File Picker Modal follows this sequence of actions:

It initiates a request to retrieve files from the file storage service by emitting the fetch-files event.
A component, such as the File Service Client, may respond to the request and communicate the fetched files using the fetched-files event.
If this happens, the fetched files are presented in a preview format within the modal.
This preview feature allows users to interact with the files through checkboxes for selecting items.
When a user selects a file using this method, the associated field establishes a connection with that chosen file.
If metadata is available for the files, it can be accessed through a modal within the modal. The metadata will be presented based on the data-schema specified for the corresponding file field being updated. Some metadata fields may not be visible, if not included in the data-schema. Note: to use this feature with Mia Platform's Files Service, version 2.7.0 or higher is required.

Locale

The texts of the File Picker Modal can be customized through the property customLocale, which accepts an object shaped like the following:

type Locale = {
  formTitle: LocalizedText
  filePickerTitle: LocalizedText
  ctaLabel: LocalizedText
  filePicker: {
    dragAndDropCaption: LocalizedText
    removeFile: LocalizedText
    checkboxCaption: LocalizedText
    metaDataTitle: LocalizedText
    preview: {
      openFile: LocalizedText
      brokenFile: LocalizedText
      absentFile: LocalizedText
      loadMore: LocalizedText
    }
    previewDrawer: {
      dateFormat: LocalizedText
      closeTitle: LocalizedText
      metaDataTitle: LocalizedText
      brokenFile: LocalizedText
      absentFile: LocalizedText
      downloadCta: LocalizedText
    }
  }
}

where LocalizedText is either a string or an object mapping language acronyms to strings.

Examples

Example: Basic Usage

A File Picker Modal can configured like the following:

{
  "tag": "bk-file-picker-modal",
  "dataSchema": {
    "type": "object",
    "properties": {
      "_id": {
        "type": "string"
      },
      "name": {
        "type": "string"
      },
      "avatar": {
        "type": "object",
        "format": "file"
      }
    }
  }
}

upon receiving to a link-file-to-record event with the following payload and meta

{
  "payload": {
    "_id": "item-id-1",
    "name": "Joe",
    "avatar": {
      "_id": "file-id",
      "name": "fileName.jpg",
      "file": "file.jpg",
      "size": 3992,
      "location": "/v2/files/download/file.jpg"
    }
  },
  "meta": {
    "property": "avatar"
  }
}

would open, allowing to request the download the file associated to the "image" field and allowing to upload a new via a drag-and-drop area. Being the "avatar" field of type object, the File Picker Modal allows at most one file to be linked to it. After uploading a new file and submitting, the File Picker Modal signals the need to upload the new file, and consequently patch the "image" field of the connected item with the storage location metadata of the new file. This request is signaled by emitting the update-data-with-file, like:

{
  "payload": {
    "_id": "item-id-1",
    "name": "Joe",
    "avatar": {
      ... // -> this contains the uploaded file
    },
  },
  "meta": {
    "property": ["avatar"]
  }

}

The payload of the event contains the newly uploaded file inside field "avatar". The meta of the event indicates what property should be used to extract the file from the payload to upload. A component like the File Manager should pick up on this event.

Example: Preview files

A File Picker Modal can be configured like the following:

{
  "tag": "bk-file-picker-modal",
  "properties": {
    "dataSchema": {
      "type": "object",
      "properties": {
        "_id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "avatar": {
          "type": "object",
          "format": "file"
        }
      }
    },
    "previewUploadedFiles": "fetch"
  }
}

Upon opening, the File Picker Modal requests files to be fetched from the file service storage. This is achieved by emitting a fetch-files event, with a payload like:

{
  "page": 0
}

The page option is included in the request to enable data pagination for the fetched files. In the File Picker Modal, a button is provided that allows users to request the retrieval of additional files, increasing the value of the page field.

If a response is received in the form of a fetched-files event, such as:

{
  "files": [
    {
      "_id": "avatar-img-id",
      "name": "avatar-img-name.jpg",
      "file": "avatar-img.jpg",
      "size": 3992,
      "location": "/v2/files/download/avatar-img.jpg"
    },
    {
      "_id": "avatar-img2-id",
      "name": "avatar-img2-mame.jpg",
      "file": "avatar-img2.jpg",
      "size": 2412,
      "location": "/v2/files/download/avatar-img2.jpg"
    },
  ]
}

The File Picker Modal displays a preview of these fetched files within its interface. Users can interact with the displayed files by selecting them. Selecting a file establishes a link between the chosen file and the field being handled by the File Picker Modal.

API

Properties & Attributes

property	attribute	type	default	description
`dataSchema`	-	ExtendedJSONSchema7Definition	-	data schema describing the fields of the collection
`rootElementSelector`	`root-element-selector`	string	-	root element to append the modal to
`width`	`width`	number	500	width of the modal
`previewUploadedFiles`	`preview-uploaded-files`	"none" \| "preview" \| "fetch"	"none"	allows to preview uploaded files and files from a bucket

Listens to

event	action
loading-data	disables footer submit button
link-file-to-record	launches the upload of a file from selected ones
fetched-files	receives files to display as preview

Emits

event	description
update-data-with-file	requests data update by uploading a new file and patching the dataset with its storage location metadata
update-data	requests data update after unlinking the file to the record
fetch-files	requests files to be fetched for preview

How to configure​

Metadata​

Preview Files​

Locale​

Examples​

Example: Basic Usage​

Example: Preview files​

API​

Properties & Attributes​

Listens to​

Emits​