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

Design

* Required property

button-text *

string

The button text

error-message

string

Sets the Uploader in error state and displays a custom error message, e.g. the required-field error "Please add at least one file"

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.

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\".

icon

string

The Material Design Icon character code (e.g. f1c0)

label

string

A description for the Uploader.

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

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.

required-field

boolean

Displays an asterisk next to the label indicating that the field is required. Note: this must be used in conjunction with the label property.

show-info

"time" | "size" | "none"

The additional information which should be displayed for each file (type 3 only). Defaults to time.

sort-by

name | date

How to sort the list of files. name is descending (a -> z), date is ascending (earlier -> later). Defaults to date

Properties of the objects passed to `files`

id *

string

A unique identifier for the file

name *

string

The file name, without the extension

type *

string

The file extension. NOT the MIME type! e.g. 'pdf', not 'application/pdf'

fileActions

string

Space-separated list of available file actions. Accepts preview download delete. Defaults to download delete

lastUpdated

ISO string

e.g. 2020-01-28T22:29:10.397Z

progress

string

A percentage value (0-100)

size

number

The size of the file in bytes.

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>
<hr>
<wm-uploader id="uploader2" required-field label="Upload Project Documents" button-text="Upload documents" files='[]' file-types="doc docx pdf txt"></wm-uploader>
<button type="submit" onClick="handleSubmit()">Submit</button>

Javascript Sample

Example code for functionality.

const uploaders = document.querySelectorAll("wm-uploader");

uploaders.forEach((uploader) => {
  uploader.addEventListener("wmUploaderFilesSelected", (ev) =>
    handleFilesSelected(ev)
  );

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

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

  uploader.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) {
  // this is where the files get uploaded to the server.
  // you must pass the upload progress back to the component so that the
  // progress bar and the number of files uploading are displayed correctly.
  // The Fetch API cannot be used as it doesn't include progress 
  // see https://stackoverflow.com/questions/37806594/how-to-get-progress-from-fetch-api#37806796
  // You can create an XHR request then listen to its progress event
  // and emit wmUploadProgress in the callback.
  // See https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
  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)
  );
}

function handleSubmit() {
  const requiredUploader = document.getElementById("uploader2");
  const fileList = JSON.parse(requiredUploader.files);
  requiredUploader.errorMessage =
    fileList.length === 0 ? "Please upload at least one file" : "";
}

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.

Example

Anatomy

The Uploader component consists of a secondary button with an icon, number of attachments that can be uploaded as well as maximum file size, and helper text of the accepted file types.

Button - The button is a secondary button with an icon. Language for the button should use the same words that a descriptor might have. For example, If the instructions say, “Attach important reports and documents that demonstrate your organization’s value and design, as well as evidence of success and improvement”, then you would use the language “Attach Files” in your button. Always pair the text with an icon that is appropriate with the language.
Accepted file types - List the files accepted by the uploader by type. For example, group the image types together, then documents, then videos.
Number of attachments (optional) - To the right of the button, you can include a label that says “Attach up to ___ files”. When the number of files have reached the maximum amount, change the language to say “Maximum number of files reached”
Tip: Make sure the language is consistent with the button language.
Maximum file size - To the right of the upload button, the maximum file size automatically shows if the property is set on the component by the developer. By default, it is 100MB, but may change depending on the use case.

Once a file is uploaded, a file block is added below it.

File name - The file name is always present and has the file type at the end of it.
Date uploaded / File size (optional) - Only one of these tags should be present. The “date uploaded” or “file size” tag is right-aligned and pinned to the buttons on the right. If there is a change in the number of buttons, the text should move to the right and stay pinned to the button. The date format should always be MM/DD/YYYY and keep with 12 hour time, and file size format should always be ##MB (or KB, or GB, depending on the size. The date or file size tag is not present in certain use cases where it is not beneficial to the user. The date or file size tag is also not present when the screen size is in a mobile format.
Preview button (optional) - If the use case calls for it, use a preview button. If preview is to be used, it is the first icon button shown.
Download button (optional) - If the use case calls for it, use a download button. Download comes before delete, but after preview (if used), and can also be used on its own.
Delete button (optional) - If the permissions for the user allow it, use the delete button. If it’s grouped with other buttons, it is the last icon button shown. It can also be used on its own. Once clicked, it will trigger a snackbar to alert the user that the file has been deleted.

States

Empty

When no files have been uploaded.

New file uploaded

When a new file is uploaded, a check mark appears showing that the upload was successful. The checkbox persists for the duration of the session.

File uploaded

The label for how many files have been uploaded changes based on the amount of files that have been uploaded.

File block content combinations

The file block is flexible so that you can use three different buttons in different combinations or not at all, depending on what the use case is. Keep in mind that everything is optional EXCEPT for the file name itself. Think about the use case and what actions the user needs to make and what information is necessary for that particular user.

Download and Delete

Preview and Download

Delete Only

Preview Only

Download Only

Error

If the user is trying to upload a file that is not a supported file type, or if the file is too big, an error is displayed. The user will have the ability to clear each error.

If the user has selected mulitple files at a time to upload, but that number exceeds the limit, an error will appear stating that the upload was unsuccessful.

Required State

Use a label with an asterisk to indicate that a file is required. The label’s action verb should match the verb used in the button, i.e. “Attach your Capstone Files” with the button “Attach Files”, or “Upload Program Files” with the button “Upload Files”.

If no file has been added, an error state is displayed and the user will be prevented from moving on until a file is added.

Smaller screen size

When the uploader is smaller than 500px, a truncated view of the file block is shown. If there are two or more buttons needed for the file block, the buttons are wrapped in an Action Menu. If there is only one button, there is no need to change or remove any buttons. At this size, the date or file size are not shown.

Overflow menu replaces the action buttons

Tip: Make sure that the overflow menu items are in the same order as the buttons it is replacing.

Show the action button when there is only one.

Max width

The max width of the file block is 1140px.

File uploading

During the upload, the file block displays a progress bar at the top. Only the file name is displayed.

Once the file is uploaded, the user will see the green check mark as well as the date uploaded and any file block buttons.

Button behavior

Attach files button

The button type (secondary with an icon) will always be the same for the uploader. It must contain an icon and supporting button text.

Paperclip icon with the word “attach”

The icon should reflect what the button says

Upload file

In some cases, it might make more sense to use “upload file”

Disabled button with icon

Button is disabled when the maximum number of files has been reached.

Action buttons

Once files have been uploaded, the file blocks contain a few different action buttons to choose from.

Preview

Opens file up in file preview mode.

Download

Downloads uploaded file to computer.

Delete

Removes the file. Always show a snackbar to alert the user it’s been deleted.

Overflow

Replaces the action buttons with a menu.

Spacing

Pattern Spacing

Pattern spacing is built into the component and should not be adjusted.

Tip: Keep 80px between the file name and date uploaded. File name will be truncated to fit this spacing.

At less than 500px, the spacing in between the action button and file name is 40px so that the user sees more of the file name.

An ellipsis should be used for truncated characters and should represent three or more truncated characters in the file name (ex. thisisalon…ame.doc). There must be at least five characters of non-truncated content in the file name. On hover there should always be a tooltip that shows the entire non-truncated file name.

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

Example

Anatomy

States

Empty

New file uploaded

File uploaded

File block content combinations

Error

Required State

Smaller screen size

Max width

File uploading

Button behavior

Attach files button

Action buttons

Spacing

Pattern Spacing

Properties of the objects passed to `files`

Deprecated `wm-uploader` properties

Deprecated `wm-network-uploader` properties