Easily achieve beautiful, transparent uploads and downloads with a reactive XmlHttpRequest
MIT License
Easily achieve beautiful, transparent uploads and downloads with a reactive XmlHttpRequest
The standard XmlHttpReuest object that is part of the standard browser toolkit provides an imperative / callback based API, and so reacting to changes can be a frustrating exercise in "what callbacks do I register? onloadend? onload?", "In what order are they fired?", "what are the properties of the event", etc...
Ember.XHR
is a drop-in replacement for the native browser
XMLHttpRequest whose properties are fully reactive, and so integrating
it into your UI is a breeze. There are no need to register any
callbacks since all of its properties can be observed, bound to, or
computed from.
All of the properties of the the XHR, including readyState
,
status
, response
, responseText
, progress
, etc... are reactive
and can be bound to in templates, and can also be used as the input
for other computed properties.
This is particularly useful in tracking the progress of an upload or a download.
There are progress properties that correspond to the state of the
upload and the download, and that react as that state changes. The
download progress properties are the progress
property. E.g. progress.total
, while the upload progress is on the
upload.progress
property. E.g. upload.progress.total
These reactive properties are:
Because Ember.XHR radiates all information about its progress, building UIs to track it are a snap.
Ember XHR can be used via ember-cli, or from a global build. The choice is yours, but to use the global build, you'll have to jump through a few more hoops.
Using it with ember-cli is a snap:
npm install --save ember-xhr
Then, anywhere in your app:
import XHR from 'ember-xhr';
git clone git://github.com/cowboyd/ember-xhr.git
cd ember-xhr
npm install
ember build
This will build dist/ember-xhr.js
and dist/ember-xhr.js.map
which you can place into your vendor/
directory or wherever it is you keep your javascript files. This will define Ember.XHR
, so anywhere in your app, you can say:
var XHR = Ember.XHR;
var file = getDraggedFile();
var xhr = XHR.create();
xhr.open('PUT', '/path/to/some/blob', true);
xhr.setRequestHeader('Content-Type', 'application/octet-stream');
xhr.send(file);
this.set('xhr', xhr);
The xhr can just be dropped into a template.
{{xhr.readyState}}
Bytes Uploaded: {{xhr.upload.progress.loaded}}
Bytes Downloaded: {{xhr.progress.loaded}}
Avg. Upload Speed (bytes/second): {{xhr.upload.progress.averageSpeed}}
Avg. Download Speed (bytes/second): {{xhr.progress.averageSpeed}}
Percentage Uploaded: {{xhr.upload.progress.percentage}} {{!=> .45}}
Percentage Downloaded: {{xhr.progress.percentage}}
It's not just for templates though... binding the upload percentage to the width of a progress bar is another simple application.
As a kicker, every instance of Ember.XHR
implements the promise
interface.
xhr.then(function(response) {
console.log('response', response);
})