vue-clip

Introduction

Vue clip is a minimalistic and hackable file uploader for VueJs. I wrote this plugin due to the absence of well written file uploaders with fine-grained controls.

#### Features
1. Written in vanilla Javascript.
2. Weighs 17.9KB ( Minified and Gzip ), 57KB ( Minified ).
3. Hackable to the core with custom events.

Setup

You can make use of module by installing it from npm or directly using it from CDN.

#### Npm

``bash
npm i --save vue-clip
`

`javascript
import Vue from 'vue'
import VueClip from 'vue-clip'

Vue.use(VueClip)
`

#### Globally

Also, you can reference the script file via [CDN]() which will add a global component called vue-clip to the Vue instance.

Basic Usage

`html



`

Configuration Options

| Option | Possible Values | Description |
|--------|-----------------|-------------|
| url | String, Function | Url to be used for uploading files. This can be a string or a function ( in case your URL is dynamic ) |
| method | String, Function | Http method to be used. Defaults to post.
| parallelUploads | Number | Number of files to be uploaded in parallel.
| maxFilesize | Number, Object | The file size in MB to be allowed. Also, you can pass an object with limit and error message.|
| paramName | String | Param name to be used for uploading file(s). Defaults to file.|
| uploadMultiple | Boolean | Whether or not to upload multiple files.|
| headers | Object | Http headers to be sent along each request.|
| maxFiles | Number, Object | a maximum number of files to be uploaded. You can also pass an object with limit and error message.|
| acceptedFiles | Array, Object | File types to be accepted. ['image/*', 'application/pdf'].
| accept | Function | A custom function to be used for validating each file upload. This method receives a done callback. In the case of any errors, you must call done with a single error argument.

#### maxFilesize
The maxFilesize option defines the size of the file to be checked for when uploading files.

`js
{
maxFilesize: 1 // 1mb
}

// or

{
maxFilesize: {
limit: 1,
message: '{{ filesize }} is greater than the {{ maxFilesize }}'
}
}
`

#### maxFiles

The maxFiles option defines the maximum number of files to be uploaded.

`js
{
maxFiles: 5
}

// or

{
maxFiles: {
limit: 5,
message: 'You can only upload a max of 5 files'
}
}
`

#### acceptedFiles

The mime types of files to be accepted.

`js
{
acceptedFiles: ['image/*', 'application/pdf']
}

// or

{
acceptedFiles: {
extensions: ['image/*'],
message: 'You are uploading an invalid file'
}
}
`

#### accept

The accept is a low-level method to run manual validations and return a formatted error string ( in the case of error).

`js
{
accept: function (file, done) {
if (file.size > (1024 * 1024)) {
done('File must be smaller than 1MB')
return
}

done()
}
}
`

Dragging

The most common requirement is to know when a user starts and stops dragging a file so that you can add some visual feedback to the UI. The easiest way is to make use of Scoped slots.

`html



`

Events

You can make use of vue-clip without writing any javascript code, but if you want low-level control over the upload behavior, consider listening to special events.

#### onInit(uploader)
Called every time the vue-clip is initiated and binds to DOM.

`html



`

#### onAddedFile(file)
This event is invoked every time a new file gets uploaded. You can listen for this event, you want to have access to each file object within your own parent component.

`html



`

#### onRemovedFile(file)
This event is invoked every time the file has been removed. This is the nice place to make a request to your server for deleting the file.

`html



`

#### onSending(file, XHR, formData)
This event is emitted before making the upload HTTP request. So this is the time to modify the HTTP request and send some custom attributes.

`html



`

#### onComplete(file, status, xhr)
This event is called when a file has been processed. It includes error, success both. 3rd argument will be the xhr response, if the error is returned from the server when uploading the file.

`html



`

#### onDragEnter
This event is invoked as soon as the user starts dragging the file.

`html



`

#### onDragLeave
This event is invoked when the user stops dragging the file.

`html



`

#### onDrop
This event is invoked when the user drops a file on the vue-clip area.

`html



`

#### onTotalProgress(progress, totalBytes, bytesSent)
This event returns the total upload progress for all the files. Think of it as the global progress indicator for multiple files uploaded together.

`html



`

#### onQueueComplete
The event is called when all files in the queue have been uploaded to the server.

`html



`

#### onMaxFiles
The event is called when maxFiles upload limit has been reached. This event will be fired n timesfor each file exceeding the limit. For example

- maxFiles - 3
- filesUploaded - 5
- eventCalled - 2 times with file instance

`html



`

File Attributes

The file instance sent along events has following attributes.

| Attribute | Type | Description |
|-----------|------|-------------|
| name | String | The client name of the file |
| status String | String | The file status, which can be success, error, queued, added. |
| width | Number | The file width. Only for images. |
| height | Number | The file height. Only for images. |
| bytesSent | Number | The total bytes sent to the server so far. |
| progress | Number | Total upload progress. |
| total | Number | The total number of bytes to be sent to the server. |
| type | String | The file mime-type. |
| size | Number | The file size on user disk. |
| dataUrl | String | File base64 data URL to be used for displaying images preview. |
| xhrResponse | Object | Server xhrResponse. Only contains response, responseText and statusCode |
| errorMessage | String | Error message when processing a file. If the error is returned from the server, it will be the value of XHR error. Also can be client errors for maxSize etc.|
| customAttributes | Object | Each file needs some custom attributes, for example server id to be used for deleting the files.|

#### Adding/Accessing Custom Attributes
`javascript
file.addAttribute('id', xhr.response.id)

// access id
file.customAttributes.id
`

Browser Support

- Chrome 7+
- Firefox 4+
- IE 10+
- Opera 12+
- Safari 6+


#### Things to consider
Make sure you add class dz-message to the uploader action wrapped inside clip-uploader-action slot. This makes your entire action body clickable. There are ways to get around it, but I wanted to keep the API transparent, instead of adding a bunch of DOM elements behind the scenes.

`html

``

Recipes

#### Tutorial

#### Displaying Files Out Of Vue Clip Area

#### Uploading Files Using A Custom File Input