/**
* Provides core Upload-functionality.
* Also defines` HTMLInputElement.prototype.sendFiles`.
*
* The Uploader is a Class, which can be instantiated with a `config`-object:
* {url: {String}, the default url to send to
* params: {Object}, the default params that will be send with the request
* options: {Object}, the xhr-options (see http://itsa.io/api/classes/IO.html#method_sendBlob)
* maxFileSize: {Number}, the maximum filesize for every single file to be accepted. Note that the server needs to
* controll this, however, when set, the uploader is enabled to show a proper warning while
* rejecting the io-promise
* totalFileSize: {Number} the maximum filesize for all files (cummulated) to be accepted. Note that the server needs to
* controll this, however, when set, the uploader is enabled to show a proper warning while
* rejecting the io-promise
* }
*
* <i>Copyright (c) 2014 ITSA - https://github.com/itsa</i>
* New BSD License - http://choosealicense.com/licenses/bsd-3-clause/
*
* @module uploader
* @class Uploader
*/
"use strict";
require('polyfill/polyfill-base.js');
require('./css/uploader.css');
var NAME = '[uploader]: ',
later = require('utils').later,
jsext = require('js-ext/js-ext.js'), // we need the full version
Classes = jsext.Classes,
createHashMap = jsext.createHashMap,
TEMPLATE = '<input class="uploader-hidden-input" type="file">';
module.exports = function (window) {
var Event = require('itsa-event'),
IO = require("itsa-io/extra/io-filetransfer.js")(window),
Uploader;
// to prevent multiple Uploader instances
// (which might happen: http://nodejs.org/docs/latest/api/modules.html#modules_module_caching_caveats)
// we make sure Uploader is defined only once. Therefore we bind it to `window` and return it if created before
// We need a singleton Uploader, because submodules might merge in. You can't have them merging
// into some other Uploader-instance than which is used.
window._ITSAmodules || Object.protectedProp(window, '_ITSAmodules', createHashMap());
/*jshint boss:true */
if (Uploader=window._ITSAmodules.Uploader) {
/*jshint boss:false */
return Uploader; // Uploader was already created
}
Uploader = Classes.createClass(function(config) {
/**
* Hidden `input-node` of the type `file` that is being used to transfer the files.
*
* @property _inputNode
* @type DOMNode
* @private
* @since 0.0.1
*/
/**
* Private Array with objects of this structure: {name: xxx, size: xxx}.
* Holds the file-info of all files that have been send by the last transfer.
* Can be used by the method: getLastSent()
*
* @property _lastfiles
* @type Array
* @default []
* @private
* @since 0.0.1
*/
var instance = this,
inputNode;
config || (config={});
instance._inputNode = inputNode = window.document.body.addSystemElement(TEMPLATE);
instance.defaultParams = {};
instance.defaultOptions = {};
instance.setDefaults(config.url, config.params, config.options, config.maxFileSize, config.totalFileSize);
instance._lastfiles = [];
instance.defineEvent('send').defaultFn(instance._defFnSend);
instance.defineEvent('selectfiles').defaultFn(instance._defFnSelectFiles);
instance.defineEvent('fileschanged').defaultFn(function(e) {
var self = e.target;
self._inputNode.getData('autoSend') && self.send(instance._selectedPayload);
});
instance.after('change', function() {
/**
* Fired internally whenever the selected files are changed.
* Its defaultFn will start sending the files (if the selection is triggered with `autoSend=true`)
*
* @event uploader:fileschanged
* @since 0.1
*/
instance.emit('fileschanged', instance._selectedPayload);
}, function(e) {
return (e.target===inputNode);
});
},
{
/**
* Clears the default transition-values that are being used for the values of `url`, params` and `options`.
*
* @method clearDefaults
* @chainable
* @since 0.0.1
*/
clearDefaults: function() {
var instance = this;
instance.defaultURL = null;
instance.defaultParams = {};
instance.defaultOptions = {};
instance.defaultMaxFileSize = null;
instance.defaultTotalFileSize = null;
return instance;
},
/**
* Returns the number of files that are currently selected.
*
* @method count
* @return {number} Number of files currently selected
* @since 0.0.1
*/
count: function() {
return this._inputNode.files.length;
},
/**
* Destroys the fileselector: removes all eventlisteners and removes its protected `input`-domNode.
*
* @method destroy
* @since 0.0.1
*/
destroy: function() {
this._inputNode.remove();
},
/**
* Returns the protected `input`-domNode whichis being used by this uploader-instance.
*
* @method getDomNode
* @return {DOMNode} protected `input`-domNode
* @since 0.0.1
*/
getDomNode: function() {
return this._inputNode;
},
/**
* Returns the currently selected files. This is an `Array-like` object, not a true Array.
*
* @method getFiles
* @return {Array-like} protected `input`-domNode
* @since 0.0.1
*/
getFiles: function() {
return this._inputNode.files;
},
/**
* Returns the size of the largest file that is currently selected.
*
* @method getLargestFileSize
* @return {Number} The size of the largest file in bytes
* @since 0.0.1
*/
getLargestFileSize: function() {
var instance = this,
files = instance._inputNode.files,
len = files.length,
largest = 0,
i, file;
for (i=0; i<len; i++) {
file = files[i];
(file.size>largest) && (largest=file.size);
}
return largest;
},
/**
* Returns the last send-files.
* This is handy to know, because after transmission, getFiles() will return empty.
* This is an true Array with objects of this structure: {name: xxx, size: xxx}
*
* @method getLastSent
* @return {Array} The last sent files
* @since 0.0.1
*/
getLastSent: function() {
return this._lastfiles;
},
/**
* Returns the total size of all files that are currently selected.
*
* @method getTotalFileSize
* @return {Number} The size of all files in bytes
* @since 0.0.1
*/
getTotalFileSize: function() {
var instance = this,
files = instance._inputNode.files,
len = files.length,
total = 0,
i, file;
for (i=0; i<len; i++) {
file = files[i];
total += file.size;
}
return total;
},
/**
* Whether there are currently files selected.
*
* @method hasFiles
* @return {number} Number of selected files
* @since 0.0.1
*/
hasFiles: function() {
return (this.count()>0);
},
/**
* Pops-up the browser's fileselect, by emitting the 'uploader:selectfiles'-event.
* The fileselector allows you to send only 1 file at a time.
* If `payload.autoSend` is set, the files will automaticly be send after selection.
* You also can set other properties at the payload --> these will be available at the listeners.
*
* @method selectFile
* @params [payload] {Object}
* @params [payload.autoSend] {Boolean}
* @chainable
* @since 0.0.1
*/
selectFile: function(payload) {
var instance = this;
instance._selectedPayload = payload ? payload.deepClone() : {};
/**
* Fired to start selecting the files.
* Its defaultFn will pop-up the file-selector.
*
* @event uploader:selectfiles
* @since 0.1
*/
instance.emit('selectfiles', instance._selectedPayload);
return instance;
},
/**
* Pops-up the browser's fileselect, by emitting the 'uploader:selectfiles'-event.
* The fileselector allows you to send multiple files at a time.
* If `payload.autoSend` is set, the files will automaticly be send after selection.
* You also can set other properties at the payload --> these will be available at the listeners.
*
* @method selectFiles
* @params [payload] {Object}
* @params [payload.autoSend] {Boolean}
* @chainable
* @since 0.0.1
*/
selectFiles: function(payload) {
var instance = this;
instance._selectedPayload = payload ? payload.deepClone() : {};
instance._selectedPayload.multiple = true;
instance.emit('selectfiles', instance._selectedPayload);
return instance;
},
/**
* Send the selected files, by emitting the 'uploader:send'-event.
* If `payload.url`, `payload.url` or `payload.url` is set, then these will overrule the default
* values (the way they were set at initiation, or by using `setDefaults`).
* You also can set other properties at the payload --> these will be available at the listeners.
*
* @method send
* @params [payload] {Object}
* @params [payload.url] {String}
* @params [payload.params] {Object}
* @params [payload.options] {Object}
* @chainable
* @since 0.0.1
*/
send: function(payload) {
var instance = this;
/**
* Fired to start uploading through io.
* Its defaultFn will invoke `sendFiles` of the input-node.
*
* @event uploader:send
* @since 0.1
*/
instance.emit('send', payload && payload.deepClone());
return instance;
},
/**
* Sets the default transition-values that are being used for the values of `url`, params` and `options`.
* These values might have been set during initialization, if so, any values passed will be overrule the previous.
*
* @method setDefaults
* @params [url] {String} the default url to send to
* @params [params] {Object} the default params that will be send with the request
* @params [options] {Object} the xhr-options (see http://itsa.io/api/classes/IO.html#method_sendBlob)
* @params [maxFileSize] {Number} the maximum filesize for every single file to be accepted. Note that the server needs to
* controll this, however, when set, the uploader is enabled to show a proper warning while
* rejecting the io-promise
* @params [totalFileSize] {Number} the maximum filesize for all files (cummulated) to be accepted. Note that the server needs to
* controll this, however, when set, the uploader is enabled to show a proper warning while
* rejecting the io-promise
* @chainable
* @since 0.0.1
*/
setDefaults: function(url, params, options, maxFileSize, totalFileSize) {
var instance = this;
(typeof url==='string') && (instance.defaultURL=url);
params && (instance.defaultParams=params.deepClone());
options && (instance.defaultOptions=options.deepClone());
maxFileSize && (instance.defaultMaxFileSize=maxFileSize);
totalFileSize && (instance.defaultTotalFileSize=totalFileSize);
return instance;
},
/**
* Default function for the `uploader:selectfiles`-event
*
* @method _defFnSelectFiles
* @param e {Object} eventobject
* @param [e.multiple] {Boolean} whether to support multiple selected files
* @private
* @since 0.0.1
*/
_defFnSelectFiles: function(e) {
var instance = e.target,
inputNode = instance._inputNode,
autoSend = e.autoSend,
eMultiple = e.multiple,
multiple = (typeof eMultiple === 'boolean') ? eMultiple : false;
inputNode.toggleAttr('multiple', 'true', multiple);
inputNode.setData('autoSend', autoSend);
inputNode.showFileSelect();
},
/**
* Default function for the `uploader:send`-event
*
* @method _defFnSend
* @param e {Object} eventobject
* @param [e.url] {String} overrules the default `url`
* @param [e.params] {Object} overrules the default `params`
* @param [e.options] {Object} overrules the default `options`
* @private
* @since 0.0.1
*/
_defFnSend: function(e) {
var instance = this,
inputNode = instance._inputNode,
url = e.url,
params = e.params,
options = e.options,
defaultTotalFileSize = instance.defaultTotalFileSize,
defaultMaxFileSize = instance.defaultMaxFileSize,
sendOptions, originalProgressFn, largest, total;
if (!inputNode || inputNode.files.length===0) {
return Promise.reject('no file selected');
}
/*jshint boss:true */
if (defaultMaxFileSize && ((largest=instance.getLargestFileSize())>defaultMaxFileSize)) {
return Promise.reject('one of the files exceeds the maximum filesize of '+largest+' bytes');
}
if (defaultTotalFileSize && ((total=instance.getTotalFileSize())>defaultTotalFileSize)) {
return Promise.reject('the size of all files exceeds the maximum of '+total+' bytes');
}
/*jshint boss:false */
sendOptions = options ? options.deepClone() : instance.defaultOptions.deepClone();
sendOptions.emptyFiles = true;
// redefine the argument of the progress-callback:
if (sendOptions.progressfn) {
originalProgressFn = sendOptions.progressfn;
sendOptions.progressfn = function(data) {
e.ioPromise = data.target;
e.total = data.total;
e.loaded = data.loaded;
originalProgressFn(e);
};
}
instance._storeLastSent();
return inputNode.sendFiles(url || instance.defaultURL, params || instance.defaultParams, sendOptions);
},
/**
* Stores the files that are sent into an internal hash, which can be read by `getLastSent()`.
*
* @method _storeLastSent
* @private
* @chainable
* @since 0.0.1
*/
_storeLastSent: function() {
var instance = this,
lastFiles = instance._lastfiles,
files = instance._inputNode.files,
len = files.length,
i, file;
lastFiles.length = 0;
for (i=0; i<len; i++) {
file = files[i];
lastFiles.push({
name: file.name,
size: file.size
});
}
return instance;
}
});
Uploader.mergePrototypes(Event.Listener);
Uploader.mergePrototypes(Event.Emitter('uploader'));
/**
* Sends the input's files by using an AJAX PUT request.
* Additional parameters can be through the `params` argument.
*
* The Promise gets fulfilled if the server responses with `STATUS-CODE` in the 200-range (excluded 204).
* It will be rejected if a timeout occurs (see `options.timeout`), or if `xhr.abort()` gets invoked.
*
* Note: `params` should be a plain object with only primitive types which are transformed into key/value pairs.
*
* @for HTMLInputElement
* @method sendFiles
* @param url {String} URL of the resource server
* @param [params] {Object} additional parameters. NOTE: these will be set as HEADERS like `x-data-parameter` on the request!
* should be a plain object with only primitive types which are transformed into key/value pairs.
* @param [options] {Object}
* @param [options.sync=false] {boolean} By default, all requests are sent asynchronously. To send synchronous requests, set to true.
* @param [options.headers] {Object} HTTP request headers.
* @param [options.timeout=300000] {Number} to timeout the request, leading into a rejected Promise. Defaults to 5 minutes
* @param [options.progressfn] {Function} callbackfunction in case you want to process upload-status.
* Function has 3 parameters: total, loaded and target (io-promise)
* @param [options.withCredentials=false] {boolean} Whether or not to send credentials on the request.
* @param [options.parseJSONDate=false] {boolean} Whether the server returns JSON-stringified data which has Date-objects.
* @param [options.emptyFiles=true] {boolean} Whether the empty the inputElement after transmitting has completed
* @return {Promise}
* on success:
* Object any received data
* on failure an Error object
* reason {Error}
* The returned promise has an `abort`-method to cancel all transfers.
*/
window.HTMLInputElement.prototype.sendFiles = function(url, params, options) {
var instance = this,
files = instance.files,
len = files.length,
hash = [],
promisesById = {},
promise, ioPromise, file, i, totalsize, originalProgressFn;
options || (options={});
(typeof options.emptyFiles==='boolean') || (options.emptyFiles=true);
if (len===1) {
file = files[0];
promise = IO.sendBlob(url, file, params, options);
}
else if (len>1) {
if (options.progressfn) {
totalsize = 0;
originalProgressFn = options.progressfn;
options.progressfn = function(data) {
var promiseInstance = data.target,
totalLoaded = 0;
promisesById[promiseInstance._id] = data.loaded;
promisesById.each(function(value) {
totalLoaded += value;
});
originalProgressFn({
total: totalsize,
loaded: totalLoaded,
target: promise
});
};
}
// files is array-like, no true array
for (i=0; i<len; i++) {
file = files[i];
ioPromise = IO.sendBlob(url, file, params, options);
// we are interested in the total size of ALL files
if (options.progressfn) {
totalsize += file.size;
ioPromise._id = i;
}
hash.push(ioPromise);
}
promise = window.Promise.finishAll(hash).then(function(response) {
var rejected = response.rejected;
rejected.forEach(function(ioError) {
if (ioError) {
throw new Error(ioError);
}
});
});
promise.abort = function() {
hash.forEach(function(ioPromise) {
ioPromise.abort();
});
};
}
else {
promise = Promise.reject('No files selected');
}
if (options.emptyFiles && (len>0)) {
// empty ON THE NEXT stack (not microstack), to ensure all previous methods are processing
later(function () {
instance.resetFileSelect();
}, 0);
}
return promise;
};
window._ITSAmodules.Uploader = Uploader;
return Uploader;
};
