Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/thetutlage/vue-clip

Simple and hackable file uploader for VueJs. Supports Vue >= 2.1
https://github.com/thetutlage/vue-clip

dropzonejs file-uploader vuejs2

Last synced: 2 months ago
JSON representation

Simple and hackable file uploader for VueJs. Supports Vue >= 2.1

Lists

README 

        
## 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.





  Version

  Build Status

  Downloads

  License




#### Features

1. Written in vanilla Javascript.

2. Weighs **17.9KB ( Minified and Gzip )**, **57KB ( Minified )**.

3. Hackable to the core with custom events.

4. Does not pollute DOM by adding unnecessary markup. Infact the component will create a single div element.



## Quick Intro



## 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



  

    

      


        
 Click or Drag and Drop files here upload 


      


    



    

      


        

        {{ file.name }} {{ file.status }}

      


    



  



  export default {



    data () {

      return {

        options: {

          url: '/upload',

          paramName: 'file'

        }

      }

    }



  }



```



## 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 `acceptedFiles` option defines the mime types of files to be accepted.



```js

// as an array of mime types



{

  acceptedFiles: ['image/*', 'application/pdf']

}



// as an object with an array of mime types

// and a custom error message



{

  acceptedFiles: {

    extensions: ['image/*'],

    message: 'You are uploading an invalid file'

  }

}



// as a plain, comma-delimited string



{

  acceptedFiles: 'image/*,application/pdf'

}

```



#### 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](https://vuejs.org/v2/guide/components.html#Scoped-Slots).



```html



  



    

      


        
 Click or Drag and Drop files here upload 


      


    



  



  .upload-action.is-dragging {

    background: green;

  }



```



## 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



  

  



  export default {



    methods: {

      init (uploader) {

        // javascript uploader instance

      }

    }



  }



```



#### 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



  

  



  export default {



    data: function () {

      return {

        files: []

      }

    }



    methods: {

      addedFile (file) {

        this.files.push(file)

      }

    }



  }



```



#### 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



  

  



  export default {



    methods: {

      removedFile (file) {

        this

        .$http

        .post(`delete/${file.customAttributes.id}`)

        .then(console.log)

        .catch(console.error)

      }

    }



  }



```



#### 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



  

  



  export default {



    methods: {

      sending (file, xhr, formData) {

        formData.append('_csrf', '<token>')

      }

    }



  }



```



#### 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



  

  



  export default {



    methods: {

      complete (file, status, xhr) {

        // Adding server id to be used for deleting

        // the file.

        file.addAttribute('id', xhr.response.id)

      }

    }



  }



```



#### onDragEnter

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



```html



  

  



  export default {



    methods: {

      dragging () {

        // user started dragging the file.

      }

    }



  }



```



#### onDragLeave

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



```html



  

  



  export default {



    methods: {

      stoppedDragging () {

        // user stopped dragging the file.

      }

    }



  }



```



#### onDrop

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



```html



  

  



  export default {



    methods: {

      drop () {

        // user stopped dragging the file.

      }

    }



  }



```



#### 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



  

  



  export default {



    methods: {

      totalProgress (progress, totalBytes, bytesSent) {

      }

    }



  }



```



#### onQueueComplete

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



```html



  

  



  export default {



    methods: {

      queueCompleted () {

      }

    }



  }



```



#### onMaxFiles

The event is called when maxFiles upload limit has been reached. This event will be fired `n times`for each file exceeding the limit. For example



- **maxFiles** - 3

- **filesUploaded** - 5

- **eventCalled** - 2 times with file instance



```html



  

  



  export default {



    methods: {

      maxFilesReached (file) {

      }

    }



  }



```



## 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



  


    
 Click or Drag and Drop files here upload 


  



```