oi.file — AngularJS file uploader

☛ Русская документация

Key features

• File selection from explorer/finder and by drag'n'drop
• Validation
• Image upload before posting to server (if browser supports FileReader)
• Image upload via xhr and iframe (for older browsers)
• Files data are embedded into a model, but can be read separately
• Files are uploaded using POST method, each request per file
• For AngularJS 1.2+, but there is oi.file.old.js for old versions

Demo, sandbox

Usage

Angular module dependency:

angular.module('myApp',['oi.file']);

As a directive:

<!-- Uploading via explorer/finder --><inputtype="file" oi-file="options"><!-- Uploading by dragging into drop area --><uloi-file="options"><ling-repeat="item in items"><imgng-src="{{item.thumb}}"></li></ul>

By the way, you can drop right onto the select files button

File upload setup in controller:

$scope.file={}//Model$scope.options={//Called for each selected filechange: function(file){//file contains info about the uploaded file//uploading to serverfile.$upload('uploader.php',$scope.file)})}}

Creating model element for each file

$scope.items=model$scope.options={change: function(file){//Creating empty element for future file$scope.add(function(i,id){//Uploading the file via FileReader before main server postfile.$preview($scope.items[i]);//Uploading the filefile.$upload('uploader.php'+id,$scope.items[i],{allowedType: ["jpeg","jpg","png"]}).catch(function(data){//Removing element if something goes wrong$scope.del(data.item.id);})})}}

catch method is available starting from Angular 1.2. If you're using older versions, then use then(null, function (data) {...}) instead.

$preview and $upload return promises. See $q.

Third argument in $upload method is a validation params object. Upload module has validation function built-in, which can be overriden. Same way you can override the function of error handling.

Example with image resizing on client-side:

file.$preview({}).then(function(data){//Image is read by this moment. Resizing it with canvasminimize(file._file);//Sendingfile.$upload('uploader.php',$scope.avatar)},function(data){//Image hasn't been read. Sending as isfile.$upload('uploader.php',$scope.avatar)});

Default settings can be overridden in a service variable oiFileConfig

Setting up

• changefunction (file). Getting the file object. If it is null - doing nothing.

  • file{object} - File object, that contains info about selected file and methods:

    • $preview function (item, [field])item -model, field - field, where the image in dataUrl format is written (writing here unless specified otherwise). Returns promises with success, error callbacks
    • $upload function (url, item, [permit])url - upload script, item - model, permit - validation settings object (see below). Returns promises with success, error, notice callbacks

    In promises' callbacks $preview и $upload xhr is passed with additional fields: item: {...}model into which the uploading is performed and response: {...}server response, decodeed from JSON

• validatefunction (file, permit). Files validation

  • file{object} - file object
  • permit{object} - validation params. Example:
    • allowedType: ["jpeg", "jpg", "png", "gif"], whitelist of extensions
    • maxNumberOfFiles: 100, maximum number of files
    • maxSize: 4194304, maximum file size
    • maxSpace: 104857600, maximum server storage space available
    • quantity: 3, files uploaded
    • space: 481208, storage place taken
    • errorBadType: "You can upload only: JPEG, JPG, PNG, GIF", Error messages...
    • errorBigSize: "The file is too big",
    • errorMaxQuantity: "Maximum number of uploaded files exceeded: 100",
    • errorMaxSize: "Only 2,3 МB of free space is left"
  • return{object} - array of error objects [{msg: 'error msg', code: 'код'}, {...}, ... ]

• setErrorfunction (code, data). Error handling

  • code{string} - error code
  • data{object} - xhr with additional fields
    • item: {...}, model, into which the uploading is performed
    • response: {...}, server response, decoded from JSON
  • return{object} - object: {item: model, response: errors array}

• url{string}. Default url to uploader script 'uploader.php'

• fieldName{string}. $_FILES array key 'Files'

• fileClass{string}. Draggable file class name 'dragover-file'

• notFileClass{string}. Draggable non-file class name 'dragover-plain'

Fields added to model (for each file):

• fileName{string}. File name 'filename'
• fileThumb{string}. Thumbnail reference 'thumb',
• fileSize{string}. File size 'size',
• fileLoaded{string}. Loaded, bytes (will be removed in the end) 'loaded'
• fileProgress{string}. Upload percentage (will be removed in the end) 'progress'
• fileUploading{string}. Находится ли файл в процессе загрузки 'uploading'

Fields added to scope:

• queue{string}. Upload queue 'uploading'. Contains a general options:
  • queue.total - all files size, bytes
  • queue.loaded - all files loaded, bytes
  • queue.progress - all files upload percentage
  • queue.all - number of uploaded files
  • queue.length - number of remaining files (native option)