Upload
Helps upload images and files. Supports multiple uploads, can detect already uploaded files or images and helps them to be removed from the list of uploaded files.
Usage
The upload module has five installation options. Let's see them all.
1. Box
Create an element with the upload
class, add data-kube="upload"
.
Finally specify the path to the server upload script.
Now you have a layer where you can drop file or select it to upload.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-url="/upload/"></div> </div> </form>
The server upload script must return JSON as for the Response service. For example, in the success case:
{ "type": "message", "data": { "message": "File was uploaded" } }
Or for the error case:
[ { "type":"error" }, { "type": "message", "data": { "message": "File was not uploaded", "type": "is-error" } } ]
2. Single Photo
Single Photo mode allows you to upload only one photo and immediately show it as thumbnail.
<form action=""> <div class="form-item"> <div class="upload-box" data-kube="upload" data-type="image" data-url="/upload/" data-url-remove="/upload-remove/"> <div class="upload-item"></div> </div> </div> </form>
And here is how you can show the already uploaded photo.
<form action=""> <div class="form-item"> <div class="upload-box" data-kube="upload" data-type="image" data-url="/upload/" data-url-remove="/upload-remove/"> <div class="upload-item" data-id="1"> <span class="close"></span> <img src="image.jpg"> <input type="hidden" name="file-uploaded" value="1"> </div> </div> </div> </form>
The server upload script must return JSON like this in the success case:
{ "file-0": { "url": "image-url.jpg", "name": "image name", "id": "some-id", "size": "10 Kb" } }
The name
and size
are optional parameters.
Or for the error case, like this:
[ { "type":"error" }, { "type": "message", "data": { "message": "File was not uploaded", "type": "is-error" } } ]
3. Multiple Photos
Multiple Photos mode allows you to upload more then one photo and show them as thumbnails.
<form action=""> <div class="form-item"> <div class="upload-box" data-kube="upload" data-type="image" data-multiple="true" data-url="/upload/" data-url-remove="/upload-remove/"> <div class="upload-item"></div> </div> </div> </form>
And here is how you can show the already uploaded photos.
<form action=""> <div class="form-item"> <div class="upload-box" data-kube="upload" data-type="image" data-multiple="true" data-url="/upload/" data-url-remove="/upload-remove/"> <div class="upload-item" data-id="1"> <span class="close"></span> <img src="image-1.jpg"> <input type="hidden" name="file-uploaded[]" value="1"> </div> <div class="upload-item" data-id="2"> <span class="close"></span> <img src="image-2.jpg"> <input type="hidden" name="file-uploaded[]" value="2"> </div> <div class="upload-item"></div> </div> </div> </form>
The server upload script must return JSON like this in the success case:
{ "file-0": { "url": "image-url.jpg", "name": "image name", "id": "some-id", "size": "10 Kb" } }
The name
and size
are optional parameters.
If more than one file has been uploaded JSON must look like this:
{ "file-0": { "url": "image-url.jpg", "name": "image name", "id": "some-id", "size": "10 Kb" }, "file-1": { "url": "image-url.jpg", "name": "image name", "id": "some-id", "size": "11 Kb" } }
Or for the error case, like this:
[ { "type":"error" }, { "type": "message", "data": { "message": "File was not uploaded", "type": "is-error" } } ]
4. Single File
Single File mode allows you to upload only one file and show it in the list.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-type="file" data-target="#my-upload-target" data-url="/upload/" data-url-remove="/upload-remove/"> </div> <div id="my-upload-target" class="upload-target"></div> </div> </form>
And here is how you can show the already uploaded file.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-type="file" data-target="#my-upload-target" data-url="/upload/" data-url-remove="/upload-remove/"> </div> <div id="my-upload-target" class="upload-target"> <div class="upload-item" data-id="3746"> <span class="close"></span> <span>My file.txt <em>10 Kb</em></span> <input type="hidden" name="file-uploaded[]" value="3746"> </div> </div> </div> </form>
The server upload script must return JSON like this in the success case:
{ "file-0": { "url": "file-url.txt", "name": "file name", "id": "some-id", "size": "10 Kb" } }
The name
and size
are optional parameters.
Or for the error case, like this:
[ { "type":"error" }, { "type": "message", "data": { "message": "File was not uploaded", "type": "is-error" } } ]
5. Multiple Files
Multiple Files mode allows you to upload more then one file and show them as a list.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-type="file" data-multiple="true" data-target="#my-upload-target" data-url="/upload/" data-url-remove="/upload-remove/"> </div> <div id="my-upload-target" class="upload-target"></div> </div> </form>
And here is how you can show the already uploaded files.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-type="file" data-multiple="true" data-target="#my-upload-target" data-url="/upload/" data-url-remove="/upload-remove/"> </div> <div id="my-upload-target" class="upload-target"> <div class="upload-item" data-id="3746"> <span class="close"></span> <span>My file.txt <em>10 Kb</em></span> <input type="hidden" name="file-uploaded[]" value="3746"> </div> <div class="upload-item" data-id="3747"> <span class="close"></span> <span>My file2.txt <em>56 Kb</em></span> <input type="hidden" name="file-uploaded[]" value="3747"> </div> </div> </div> </form>
The server upload script must return JSON like this in the success case:
{ "file-0": { "url": "file-url.txt", "name": "file name", "id": "some-id", "size": "10 Kb" } }
The name
and size
are optional parameters.
If more than one file has been uploaded JSON must look like this:
{ "file-0": { "url": "file-url.txt", "name": "file name", "id": "some-id", "size": "10 Kb" }, "file-1": { "url": "file-url.txt", "name": "file name", "id": "some-id", "size": "11 Kb" } }
Or for the error case, like this:
[ { "type":"error" }, { "type": "message", "data": { "message": "File was not uploaded", "type": "is-error" } } ]
Settings
url
Type: Boolean
String
Default: false
Sets URL path to the file upload script.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-url="/upload/"></div> </div> </form>
urlRemove
Type: Boolean
String
Default: false
Sets the URL for the script on the server side, which removes the uploaded files.
When deleting a file, a POST request is sent to the server side,
which contains a parameter with the name id
and the id value of the file.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-url="/upload/" data-url-remove="/remove-file/"></div> </div> </form>
param
Type: String
Default: 'file'
The name of the file variable to be sent to the server.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-url="/upload/" data-param="my-file"></div> </div> </form>
progress
Type: Boolean
Default: false
This setting allows to show the progress bar when the upload is sending files to the server.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-url="/upload/" data-progress="true"></div> </div> </form>
placeholder
Type: String
Default: 'Drop files here or click to upload'
Placeholder text that will be shown in the drop layer.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-url="/upload/" data-placeholder="My placeholder"></div> </div> </form>
size
Type: Number
Default: 120
The thumbnail size (in pixels) of the uploaded image.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-url="/upload/" data-size="200"></div> </div> </form>
multiple
Type: Boolean
Default: false
This setting allows multiple images/files uploading simultaneously to your server.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-url="/upload/" data-multiple="true"></div> </div> </form>
type
Type: Boolean
String
Default: false
This setting specifies the mode of uploading.
If image
is specified, the uploaded images will be displayed after uploading as thumbnails.
If you set file
, the uploaded files will be displayed as a list.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-url="/upload/" data-type="image"></div> </div> </form>
target
Type: Boolean
String
Default: false
This setting sets the target element where the list of uploaded files will be displayed.
<form action=""> <div class="form-item"> <div class="upload" data-kube="upload" data-type="file" data-target="#my-upload-target" data-url="/upload/" data-url-remove="/upload-remove/"> </div> <div id="my-upload-target" class="upload-target"></div> </div> </form>
Response
Success
The server can return two kinds of JSON response on successful uploading.
1. If no data-type
was specified, then you need to return JSON as for the Response service.
For example:
{ "type": "message", "data": { "message": "File was uploaded" } }
2. If the data-type
attribute was specified, then you need to return the JSON of the following form:
{ "file-0": { "url": "image-url.jpg", "name": "image name", "id": "some-id", "size": "10 Kb" } }
The name
and size
are optional parameters.
If more than one file has been uploaded JSON must look like this:
{ "file-0": { "url": "image-url.jpg", "name": "image name", "id": "some-id", "size": "10 Kb" }, "file-1": { "url": "image-url.jpg", "name": "image name", "id": "some-id", "size": "11 Kb" } }
Error
If an error occurred while uploading the file, it is necessary to return JSON like this:
{ "type": "error" }
You can use the Response service to send messages from the server-side.
[ { "type":"error" }, { "type": "message", "data": { "message": "File was not uploaded", "type": "is-error" } } ]
Events
start
module | Object |
the current upload module |
This event fires immediately when the uploading started.
(function($K) { $K.add('module', 'mymodule', { init: function(app, context) { this.app = app; }, // catch event onmessage: { upload: { start: function(sender) { console.log('Upload is started'); } } } }); })(Kube);
beforeSend
module | Object |
the current upload module |
xhr | Object |
XMLHttpRequest object |
This event is fired before image or file send to upload.
(function($K) { $K.add('module', 'mymodule', { init: function(app, context) { this.app = app; }, // catch event onmessage: { upload: { beforeSend: function(sender, xhr) { // send headers for example xhr.setRequestHeader('X-CSRF-Token', 'your-token-value'); } } } }); })(Kube);
error
module | Object |
the current upload module |
response | Object |
object with data about upload error |
Triggered when server-side upload script is telling about the upload error with JSON response.
(function($K) { $K.add('module', 'mymodule', { init: function(app, context) { this.app = app; }, // catch event onmessage: { upload: { error: function(sender, response) { } } } }); })(Kube);
complete
module | Object |
the current upload module |
response | Object |
object with data about uploaded image or file |
This event is fired when the upload is completed.
(function($K) { $K.add('module', 'mymodule', { init: function(app, context) { this.app = app; }, // catch event onmessage: { upload: { complete: function(sender, response) { } } } }); })(Kube);
Catch events from a specific upload module
Set an ID for the upload:
<form action=""> <div class="form-item"> <div id="myupload" class="upload" data-kube="upload" data-url="/upload/"></div> </div> </form>
Or set data-name
attribute:
<form action=""> <div class="form-item"> <div class="upload" data-name="myupload" data-kube="upload" data-url="/upload/"></div> </div> </form>
Catch events in your module by the specified ID or data-name:
(function($K) { $K.add('module', 'mymodule', { init: function(app, context) { this.app = app; }, // catch event onmessage: { upload: { complete: function(sender, response) { if (sender._id === 'myupload') { // do something } } } } }); })(Kube);