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.

<wm-uploader id="uploader" button-text="Attach files" show-info="time" max-files="3" max-size="25"  files='[{"id": "file1", "name": "File retrieved from server", "type": "pdf", "lastUpdated": "2020-01-28T22:29:10.397Z", "size": "5403241", "fileActions": "preview download delete"},{"id": "file2", "name": "Another file", "type": "exe", "lastUpdated": "2010-11-14T12:21:05.397Z", "size": "3241", "fileActions": "download delete"}]' ></wm-uploader>

Javascript Sample

Example code for functionality.

document.addEventListener("wmUploaderFilesSelected", (ev) =>
  handleFilesSelected(ev)
);

document.addEventListener("wmUploaderPreviewFile", (ev) => {
  alert(ev.detail + " preview triggered");
});

document.addEventListener("wmUploaderDownloadFile", (ev) => {
  alert("downloading " + ev.detail);
});

document.addEventListener("wmUploaderDeleteFile", (ev) => {
  removeFile(ev);
});

function handleFilesSelected(ev) {
  const upl = ev.target;
  let fileList = JSON.parse(upl.files);

  upl.filesToUpload.map((file) => {
    const parts = file.name.split(".");
    const fileType = parts.pop();
    const fileName = parts.join(".");
    const newfile = {
      id: "mockID",
      name: fileName,
      type: fileType,
    };
    fileList.push(newfile);
  });

  upl.files = JSON.stringify(fileList);
  dispatchWmUploadProgress(upl);
}

function dispatchWmUploadProgress(upl) {
  const mockProgress = 40; // fake progress percentage as an example
  const wmUploadProgress = new CustomEvent("wmUploadProgress", {
    detail: { id: "mockID", progress: mockProgress },
  });
  upl.dispatchEvent(wmUploadProgress);
}

function removeFile(ev) {
  const upl = ev.target;
  const fileList = JSON.parse(upl.files);
  upl.files = JSON.stringify(
    fileList.filter((file) => ev.detail !== file.id)
  );
}

Usage in Elm

-- wm-uploader uses JSON encoders and decoders, as shown below
renderUploader =
  let
    files = [
      { "name" = "File retrieved from server"
      , "id" = "file1"
      , "type" = "pdf"
      , "lastUpdated" = "2020-01-28T22:29:10.397Z"
      },
      { "id" = "file2"
      , "name" = "Another file"
      , "type" = "exe"
      , "lastUpdated" = "2010-11-14T12:21:05.397Z"
      }
    ]
  in
  node "wm-uploader"
    [ id "uploader1"
    , attribute "button-text" "Upload new document"
    , attribute "empty-state-text" "Browse and upload files"
    , attribute "files" encodeFileList files
    ]
    []


-- the helpers below abstract away the JSON encoding part:

type alias WmUploaderFile =
  { fileType : String
  , fileUuid : String
  , lastUpdated : String
  , name : String
  }

encodeFileList : List WmUploaderFile -> String
encodeFileList files =
    JE.encode 0 (JE.list (List.map encodeFile files))

encodeFile : WmUploaderFile -> JE.Value
encodeFile file =
    JE.object
        [ ( "name", JE.string file.name )
        , ( "id", JE.string file.fileUuid )
        , ( "type", JE.string file.fileType )
        , ( "lastUpdated", JE.string file.lastUpdated )
        ]

-- wm-network-uploader doesn't require JSON decoders / encoders
node "wm-network-uploader"
  [ attribute "get-path" (model.config.endpoint ++ "/" ++ model.config.nodeUuid ++ "/documents")
  , attribute "request-upload-path" (model.config.endpoint ++ "/sign_url/")
  , attribute "upload-path" (model.config.endpoint ++ "/documents/")
  , attribute "request-download-path" (model.config.endpoint ++ "/sign_url_for_download")
  , attribute "delete-path" (model.config.endpoint ++ "/documents/" ++ model.config.nodeUuid)
  , attribute "button-text" "Upload New Document"
  , attribute "empty-state-text" "No documents uploaded yet."
  , attribute "associated-data" associatedData
  , attribute "sort-by" "name"
  , attribute "max-files" "5" -- for testing purposes only
  ]
  [ h3 [ class "wrapper-title" ] [ text translations.referenceDocuments ]
  , div [ class "wrapper-description" ] [ text (translations.referenceDocumentsSubHeader ++ " " ++ translations.referenceDocumentsSubHeaderContinued) ]
  ]

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.

Uploader

Properties of the objects passed to files

Deprecated wm-uploader properties

Deprecated wm-network-uploader properties

Usage in HTML

Javascript Sample

Usage in Elm

wm-uploader

Properties of the objects passed to `files`

Deprecated `wm-uploader` properties

Deprecated `wm-network-uploader` properties