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 uploaded, when the user clicks on an element's preview, delete, or download button, an event is emitted with the file id so that you can create a callback function to handle these cases (see Events tab).

While wm-uploader previously made use of multiple types, they have since been deprecated (in addition to wm-network-uploader) in lieu of a single design.

NB: To reflect upload progress in wm-uploader and ensure proper screen reader accessibility, wmUploadProgress events must be dispatched from the component. See the Events and Notes tab for more information.

Properties Examples Events Accessibility Notes

* Required property

button-text *
string
The button text
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
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.
show-info
"time" | "size" | "none"
The additional information which should be displayed for each file (type 3 only). Defaults to time.

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'
lastUpdated
ISO string
e.g. 2020-01-28T22:29:10.397Z
progress
string
percentage value (0-100)
size
number
The size of the file in bytes.
fileActions
string
Space-separated list of available file actions. Accepts preview download delete. Defaults to download delete

Deprecated wm-uploader properties

uploader-type
"1" | "2"
The style of the uploader. Types 1 and 2 have been deprecated.
type
"1" | "2"
Deprecated in favor of uploader-type. Previously, the style of the uploader.
empty-state-text
string
The text to display when the component is empty (type 1 only)
info
string
Info text to display next to the button (type 2 only)

Deprecated 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

Please note that the example above is not fully functional.

Usage in HTML

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

Javascript Sample

Example code for functionality.

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.
wmUploaderPreviewFile
Emitted when the user clicks the preview button. The event's detail property contains the file ID.
wmUploaderDownloadFile
Emitted when the user clicks the download button. The event's detail property contains the file ID. Replaces the deprecated wmDownloadFile.
wmUploaderDeleteFile
Emitted when the user clicks the delete button. The event's detail property contains the file ID. Replaces the deprecated wmDeleteFile.
wmNetworkUploaderFilesChanged
Emitted when the Network Uploader's files have changed. The event's detail property contains the file list.
wmUploadProgress
A custom event that must be dispatched while an upload is in progress. The event's detail must contain the keys id (corresponding to the file's id) and progress (0-100). Not applicable for wm-network-uploader.

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-uploader

To show upload progress and ensure screen reader accessibility, the wmUploadProgress event must be dispatched from the component during and at the end of an upload. This will show the currently uploading file in the list with a progress bar, announce progress via live-region, update the "x files uploading" text, and announce when the file is finished uploading.

wmUploadProgress's detail must contain the keys id and progress.

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.