file-uploader
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
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.
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.
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>
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>
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.
Links
Compatibility
Was this helpful? Need more help?
Leave a comment or a question below. You can also join
the chat on Discord or
ask questions on StackOverflow.
Version
Dependencies
- d2l-colors#^3.1.2
- d2l-localize-behavior#^1.0.0
- d2l-offscreen#^3.0.3
- polymer#1 - 2
- Released
- 2018-10-10
- Maturity
- IMPORTED
- License
- Apache License 2.0
Compatibility
- Framework
- Polymer 2.0+
- Polymer 1.0+ in 0.0.20
- Browser
- Browser Independent