Components / Library version 3.5.2

Uploader

The wm-uploader component is to be used in situations where users are uploading files that they will be able to access later; it is not for entering data into our system, for example by uploading a CSV. At this point, the component does not have filtering capabilities; if the pattern you are implementing includes a filter section, you won't be able to use the component.

The uploader comprises the input and the file list. It takes a list of files to display as input (files property). When the user selects files, the component checks whether they are valid then displays eventual error(s) and exposes the valid files to upload via the wmUploaderFilesSelected event. Once the files are uplaoded, when the user clicks on an element's delete or download button, an event is emitted with the file id so that you can create a callback function to handle these cases (respectively, wmUploaderDeleteFile and wmUploaderDownloadFile).

A second component, wm-network-uploader, includes the network requests. It takes the different endpoints as props and will retrieve, add and remove files to/from the server. It assumes a particular set-up in the back-end and will only work for that case. See the Notes tab for more more information.

Properties Examples Events Accessibility Notes

* Required property

Properties common to wm-uploader and wm-network-uploader

button-text *
string
The button text
empty-state-text *
string
The text to display when the component is empty (type 1 only)
icon
string
The Material Design Icon character code (e.g. f1c0)
file-types
string
Space-separated list of the file extensions the component should accept. Defaults to "pdf txt log xml doc docx xls xlsx ppt pptx gif jpg png csv".
max-size
number
The maximum file size in Mb. Defaults to 100Mb and can only be set to a smaller value
max-files
number
The maximum number of files that the uploader accepts. Default: no limit
sort-by
name | date
How to sort the list of files. name is descending (a -> z), date is ascending (earlier -> later). Defaults to date

wm-uploader properties

uploader-type
"1" | "2"
The style of the uploader. See both variants in the examples tab.
info
string
Info text to display next to the button (type 2 only)
files
JSON string
The files to display (uploaded or retrieved from the server). Should be a JSON string representation of an array of objects representing a file. For more information about the properties of that object, see section below.
rejected-files
JSON string
The file-specific errors to display from the server. Should be a JSON string representation of an array of objects representing each error. Each object should have a "name" property containining the filename, and a "message" property of the error message.

Properties of the objects passed to files

name *
string
The file name, without the extension
id *
string
A unique identifier for the file
type *
string
The file extension. NOT the MIME type! e.g. 'pdf', not 'application/pdf'
last-updated
ISO string
e.g. 2020-01-28T22:29:10.397Z
progress
string
percentage value (0-100)

wm-network-uploader properties

get-path *
string
The endpoint used to retrieve the list of files (GET)
upload-path *
string
The endpoint used to POST the new files
request-upload-path *
string
The endpoint returning the url which will be used for the PUT request (GET)
request-download-path *
string
The endpoint returning the temporary download url (GET)
delete-path *
string
The endpoint used to DELETE a file
associated-data *
JSON string
Data to add to the file data before the POST request

Deprecated properties

type
"1" | "2"
Deprecated in favor of uploader-type. Previously, the style of the uploader.

Please note that the examples above are not fully functional.

Usage in HTML

Edit the code below to see changes reflected in the example above.

Usage in Elm
wmUploaderFilesSelected
Emitted when the user selects files. The event's detail property contains the files that passed validation. Replaces the deprecated wmFilesSelected.
wmUploaderDeleteFile
Emitted when the user clicks the delete button. The event's detail property contains the file ID. Replaces the deprecated wmDeleteFile.
wmUploaderDownloadFile
Emitted when the user clicks the download button. The event's detail property contains the file ID. Replaces the deprecated wmDownloadFile.
wmNetworkUploaderFilesChanged
Emitted when the Network Uploader's files have changed. The event's detail property contains the file list.

The number of files uploading is shown as a notification and announced via an aria-live region.

When a file is deleted, you should announce it with the snackbar component.

wm-network-uploader

This version assumes the files are stores n AWS and authentication through signed URLs (not access tokens). AWS provides an upload and a download link in response to a GET request to an endpoint.

When a valid file is selected by the user, it is uploaded to the cloud and an entry is created in the database.

The delete button will send a DELETE request to the specified endpoint, removing the entry from the database (hard delete).

If your use case is different, please use the wm-uploader component.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.