Skip to content

Latest commit

 

History

History
169 lines (119 loc) · 5.36 KB

README.md

File metadata and controls

169 lines (119 loc) · 5.36 KB

file-uploader

Bower version Build status

A 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

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>

Setting the Language

The language attribute sets the language the file uploader should use. Currently supported values are: en, ar-SA, de-DE, es-MX, fr-CA, ja-JP, ko-KR, nb-NO, nl-NL, pt-BR, sv-SE, tr-TR, zh-CN, zh-TW.

If the language attribute is not present, it will default to English.

<d2l-file-uploader language="fr-CA" ...></d2l-file-uploader>

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