Polymer-based web component for D2L file uploader

[ This description is mirrored from README.md at github.com/BrightspaceUI/file-uploader on 2019-05-10 ]

file-uploader

Published on webcomponents.org Bower version Build status

Polymer component for uploading files with drag and drop capability. This component does not perform the actual uploading work, it simply provides visual cues and exposes an event when files have been uploaded.

screenshot of file uploader

For further information on this and other components, refer to The Brightspace UI Guide.

Installation

d2l-file-uploader can be installed from Bower:

bower install d2l-file-uploader

Usage

Include the webcomponents.js "lite" polyfill (for browsers who don't natively support web components), then import d2l-file-uploader.html:

<head>
	<script src="../webcomponentsjs/webcomponents-lite.js"></script>
	<link rel="import" href="../d2l-file-uploader/d2l-file-uploader.html">
</head>

Basic Usage with Accessible Label

It's important to always provide an accessible label which describes the purpose of the uploader using the label attribute. The label will be hidden visually but associated with the upload input for those using assistive technologies such as a screen reader.

<d2l-file-uploader label="profile picture"></d2l-file-uploader>

Multi-file Uploads

To allow for multiple files to be uploaded, add the multiple attribute:

<d2l-file-uploader multiple ...></d2l-file-uploader>

Localization

The file uploader will automatically render using the language found on the HTML element -- i.e. <html lang="fr">. If the language attribute is not present or isn't supported, the uploader will render in English.

screenshot of file uploader localized

Feedback Messages

If you encounter a scenario where you'd like to display feedback about the uploaded file(s) -- like a warning or an error -- use the feedback and feedback-type attributes.

The feedback-type defaults to "warning":

<d2l-file-uploader
	feedback="Sorry, we cannot upload files larger than 1GB.">
</d2l-file-uploader>

screenshot of file uploader in warning state

But feedback-type can also be set to "error":

<d2l-file-uploader
	feedback="An error occurred occurred processing the upload."
	feedback-type="error"></d2l-file-uploader>

screenshot of file uploader in error state

Feedback Changed Event

To listen for when feedback changes within the uploader, register for the feedback-changed event.

Vanilla JavaScript:

<d2l-file-uploader id="my-uploader" ...></d2l-file-uploader>
<script>
document.getElementById('my-uploader')
	.addEventListener('feedback-changed', function(evt) {
		var feedbackMessage = evt.detail.value;
		console.log(feedbackMessage);
	});
</script>

From within another Polymer element you can use Polymer's annotated event listeners:

<dom-module id="my-element">
	<template>
		<d2l-file-uploader on-feedback-changed="handleFeedback"></d2l-file-uploader>
	</template>
</dom-module>

Handling Uploaded Files

When the user uploads one or more files, a d2l-file-uploader-files-added event is fired. To listen for this event, wire up an event listener to the <d2l-file-uploader> element. The listener will be passed an event with an array of File objects from the File API.

Vanilla JavaScript:

<d2l-file-uploader id="my-uploader" ...></d2l-file-uploader>
<script>
document.getElementById('my-uploader')
	.addEventListener('d2l-file-uploader-files-added', function(evt) {
		var files = evt.detail.files;
		console.log(files);
	});
</script>

From within another Polymer element you can use Polymer's annotated event listeners:

<dom-module id="my-element">
	<template>
		<d2l-file-uploader on-d2l-file-uploader-files-added="handleFileAdded"></d2l-file-uploader>
	</template>
</dom-module>

Developing, Testing and Contributing

After cloning the repo, run npm install to install dependencies.

If you don't have it already, install the Polymer CLI globally:

npm install -g polymer-cli

To start a local web server that hosts the demo page and tests:

polymer serve

To lint (eslint and Polymer lint):

npm run lint

To run unit tests locally using Polymer test:

polymer test --skip-plugin sauce

To lint AND run local unit tests:

npm test

Versioning

Commits and PR merges to master will automatically do a minor version bump which will:

  • Update the version in package.json
  • Add a tag matching the new version
  • Create a github release matching the new version

By using either [increment major] or [increment patch] notation inside your merge message, you can overwrite the default version upgrade of minor to the position of your choice.

Install

Link to this version
ImportedReleased 10 October 2018Apache License 2.0
Framework Support
Polymer 2.0+
Also supported:
Polymer 1 (0.0.20)
Browser Compatibility
Install with
bower install --save BrightspaceUI/file-uploader"#0.5.0"
Run the above Bower command in your project folder. If you have any issues installing, please contact the author.
Release notes - Version 0.5.0

Dependencies

  • d2l-colors#^3.1.2
  • d2l-localize-behavior#^1.0.0
  • d2l-offscreen#^3.0.3
  • polymer#1 - 2