This module provides functionality to upload files from a browser to a Node.JS server that runs Socket.IO. Throughout the process, if their browser supports WebSockets, the user will not submit a single HTTP request. Supports Socket.IO 0.9 and higher.
The intended audience are single-page web apps, but other types of Node.JS projects may benefit from this library.
Since version 0.4, this module also supports monitoring file upload progress.
The module is released under the X11 open-source license.
Navigate to your project directory and run:
$ npm install --save socketio-file-upload
In your Express app, add the router like this (if you don't use Express, read the docs below):
var siofu = require("socketio-file-upload");
var app = express()
.use(siofu.router)
.listen(8000);On a server-side socket connection, do this:
io.on("connection", function(socket){
var uploader = new siofu();
uploader.dir = "/path/to/save/uploads";
uploader.listen(socket);
});The client-side script is served at /siofu/client.js. Include it like this:
<script src="/siofu/client.js"></script>If you use browserify, just require it like this:
var SocketIOFileUpload = require('socketio-file-upload');The module also supports AMD; see the docs below for more information.
Then, in your client side app, with this HTML:
<input type="file" id="siofu_input" />Just do this in JavaScript:
var socket = io.connect();
var uploader = new SocketIOFileUpload(socket);
uploader.listenOnInput(document.getElementById("siofu_input"));That's all you need to get started. For the detailed API, continue reading below. A longer example is available at the bottom of the readme.
- Client-Side API
- instance.listenOnInput(input)
- instance.listenOnDrop(element)
- instance.listenOnSubmit(submitButton, input)
- instance.listenOnArraySubmit(submitButton, input[])
- instance.prompt()
- instance.submitFiles(files)
- instance.destroy()
- instance.resetFileInputs = true
- instance.maxFileSize = null
- instance.chunkSize = 100 KiB
- instance.useText = false
- instance.useBuffer = true
- instance.serializeOctets = false
- instance.topicName = "siofu"
- instance.wrapData = false
- instance.exposePrivateFunction = false
- Client-Side Events
- Server-Side API
- SocketIOFileUpload.listen(app)
- SocketIOFileUpload.router
- instance.listen(socket)
- instance.abort(id, socket)
- instance.dir = "/path/to/upload/directory"
- instance.mode = "0666"
- instance.maxFileSize = null
- instance.emitChunkFail = false
- instance.uploadValidator(event, callback)
- instance.topicName = "siofu" (see client)
- instance.wrapData = false (see client)
- instance.exposePrivateFunction = false (see client)
- Server-Side Events
- Adding Meta Data
- Example
The client-side interface is inside the SocketIOFileUpload namespace. Include it with:
<script src="/siofu/client.js"></script>If you're awesome and you use AMD/RequireJS, set up your paths config like this:
requirejs.config({
paths: {
"SocketIOFileUpload": "/siofu/client",
// ...
}
});and then include it in your app like this:
define("app", ["SocketIOFileUpload"], function(SocketIOFileUpload){
// ...
});When instantiating an instance of the SocketIOFileUpload, pass a reference to your socket.
var instance = new SocketIOFileUpload(socket);Each public property can be set up in an object passing at second parameter of the Siofu constructor:
var instance = new SocketIOFileUpload(socket);
instance.chunkSize = 1024 * 1000
// is the same that
var instance = new SocketIOFileUpload(socket, {
chunkSize: 1024 * 1000
});When the user selects a file or files in the specified HTML Input Element, the library will begin to upload that file or those files.
JavaScript:
instance.listenOnInput(document.getElementById("file_input"));HTML:
<label>Upload File: <input type="file" id="file_input" /></label>All browsers tested support this method.
When the user drags and drops a file or files onto the specified HTML Element, the library will begin to upload that file or those files.
JavaScript:
instance.listenOnDrop(document.getElementById("file_drop"));