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.

My file.txt 10 Kb 
<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.

My file.txt 10 Kb
My file2.txt 56 Kb 
<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

Arguments
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

Arguments
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

Arguments
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

Arguments
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);