Home

Awesome

simple-uploader.js Build Status codecov.io Build Status

Sauce Test Status

中文

QQ

A JavaScript library providing multiple simultaneous, stable, fault-tolerant and resumable/restartable file uploads via the HTML5 File API.

Forked flow.js but refactor it.

The library is designed to introduce fault-tolerance into the upload of large files through HTTP. This is done by splitting each file into small chunks. Then, whenever the upload of a chunk fails, uploading is retried until the procedure completes. This allows uploads to automatically resume uploading after a network connection is lost either locally or to the server. Additionally, it allows for users to pause, resume and even recover uploads without losing state because only the currently uploading chunks will be aborted, not the entire upload.

Uploader (simple-uploader.js) does not have any external dependencies other than the HTML5 File API. This is relied on for the ability to chunk files into smaller pieces. Currently, this means that support is limited to Firefox 4+, Chrome 11+, Safari 6+ and Internet Explorer 10+.

Samples and examples are available in the samples/ folder. Please push your own as Markdown to help document the project.

New Features

How can I install it?

Download a latest build from https://github.com/simple-uploader/Uploader/releases/ it contains development and minified production files in dist/ folder.

or use npm:

npm install simple-uploader.js

or use git clone

git clone https://github.com/simple-uploader/Uploader

How can I use it?

A new Uploader object is created with information of what and where to post:

var uploader = new Uploader({
  target: '/api/photo/redeem-upload-token', 
  query: { upload_token: 'my_token' }
})
// Uploader isn't supported, fall back on a different method
if (!uploader.support) location.href = '/some-old-crappy-uploader'

To allow files to be either selected and drag-dropped, you'll assign drop target and a DOM item to be clicked for browsing:

uploader.assignBrowse(document.getElementById('browseButton'))
uploader.assignDrop(document.getElementById('dropTarget'))

After this, interaction with Uploader.js is done by listening to events:

uploader.on('fileAdded', function (file, event) {
  console.log(file, event)
})
uploader.on('fileSuccess', function (rootFile, file, message) {
  console.log(rootFile, file, message)
})
uploader.on('fileComplete', function (rootFile) {
  console.log(rootFile)
})
uploader.on('fileError', function (rootFile, file, message) {
  console.log(rootFile, file, message)
})

How do I set it up with my server?

Most of the magic for Uploader.js happens in the user's browser, but files still need to be reassembled from chunks on the server side. This should be a fairly simple task and can be achieved in any web framework or language, which is able to receive file uploads.

To handle the state of upload chunks, a number of extra parameters are sent along with all requests:

You should allow for the same chunk to be uploaded more than once; this isn't standard behaviour, but on an unstable network environment it could happen, and this case is exactly what Uploader.js is designed for.

For every request, you can confirm reception in HTTP status codes (can be change through the permanentErrors option):

Handling GET (or test() requests)

Enabling the testChunks option will allow uploads to be resumed after browser restarts and even across browsers (in theory you could even run the same file upload across multiple tabs or different browsers). The POST data requests listed are required to use Uploader.js to receive data, but you can extend support by implementing a corresponding GET request with the same parameters:

After this is done and testChunks enabled, an upload can quickly catch up even after a browser restart by simply verifying already uploaded chunks that do not need to be uploaded again.

Full documentation

Uploader

Configuration

The object is loaded with a configuration options:

var r = new Uploader({ opt1: 'val', ...})

Available configuration options are:

Properties

Methods

Events

Uploader.File

Properties

If .isFolder is false then these properties will be added:

Methods

Origin

Uploader.js was inspired by and evolved from https://github.com/flowjs/flow.js and https://github.com/23/resumable.js.