File Picker Drawer

<bk-file-picker-drawer></bk-file-picker-drawer>

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

The File Picker Drawer 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 Drawer 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 Drawer does not require any configuration.

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

However, such File Picker Drawer 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 Drawer 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 Drawer 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-drawer",
  "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
            }
          }
        }
      }
    }
  }
}

Locale

The texts of the File Picker Drawer 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
  }
}

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

Examples

Example: Basic Usage

A File Picker Drawer configured like the following:

{
  "tag": "bk-file-picker-drawer",
  "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 Drawer allows at most one file to be linked to it. After uploading a new file and submitting, the File Picker Drawer 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.

API

Properties & Attributes

property	attribute	type	default	description
dataSchema	-	ExtendedJSONSchema7Definition	-	data schema describing the fields of the collection
mask	mask	boolean	true	whether to mask or not the drawer
rootElementSelector	root-element-selector	string	-	root element to append the drawer to
width	width	number	500	width of the drawer

Listens to

event	action
loading-data	disables footer submit button
link-file-to-record	launches the upload of a file from selected ones

Emits

event	description
update-data-with-file	updates data 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