angular-file-upload: A JavaScript repository from chrkhl

#Angular File Upload

English documentation

About

Angular File Upload is a module for the AngularJS framework. Supports drag-n-drop upload, upload progress, validation filters and a file upload queue. It supports native HTML5 uploads, but degrades to a legacy iframe upload method for older browsers. Works with any server side platform which supports standard HTML form uploads.

When files are selected or dropped into the component, one or more filters are applied. Files which pass all filters are added to the queue and are ready to be uploaded.

Demos

Requires

The AngularJS framework
ES5 (Array.indexOf, Array.forEach, Array.filter, Array.every, Function.bind, Date.now) A shim is provided for older browsers

Includes

Directives

nrvFileSelect: Should be applied to <input type="file" />. The selected files are added to the uploaded queue if they have passed the filters.
nrvFileDrop: Set up a drop area. Usually applied to the entire document. Caught files are added to the uploaded queue if they have passed the filters.
nrvFileOver: Should be applied to the element which will change class when files are about to be placed on the drop area. By default it adds the class nrv-file-over but a different class can be specified with the parameter attribute nrv-file-over="className".

Service

fileUploader: Manages the upload queue and the uploading of files

The Uploader API:

Properties

scope {Object}: Scope for HTML update, default is $rootScope
url {String}: Path on the server to upload files
alias {String}: Name of the field which will contain the file, default is file
queue {Array}: Items to be uploaded
progress {Number}: Upload queue progress percentage
headers {Object}: Headers to be sent along with the files
formData {Array}: Data to be sent along with the files
filters {Array}: Filters to be applied to the files before adding them to the queue. If the filter returns true the file will be added to the queue
autoUpload {Boolean}: Automatically upload files after adding them to the queue
method {String}: It's a request method. By default POST
removeAfterUpload {Boolean}: Remove files from the queue after uploading
isHTML5 {Boolean}: true if uploader is html5-uploader
isUploading {Boolean}: true if an upload is in progress

Methods

bind function( event, handler ) {: Registers an event handler
trigger function( event[, params ]) {: Executes all handlers bound to this event
addToQueue function( items, options ) {: Add items to the queue, where items is a FileList, File or Input, and options is an Object
removeFromQueue function( value ) {: Remove an item from the queue, where value is a queue element Item or index
clearQueue function() {: Removes all elements from the queue
getIndexOfItem function( Item ) { return [Number]; }: Returns the index of the Item queue element
getReadyItems function() { return [Array]; }: Return items are ready to upload
getNotUploadedItems function() { return [Array]; }: Return an array of all pending items on the queue
uploadItem function( value ) {: Uploads an item, where value is a queue element Item or index
uploadAll function() {: Upload all pending items on the queue
cancelItem function( value ) {: Cancels uploading of item, where value is a queue element Item or index
cancelAll function() {: Cancels all current uploads

The Item API:

Properties

url {String}: Path on the server in which this file will be uploaded
alias {String}: Name of the field which will contain the file, default is file
headers {Object}: Headers to be sent along with this file
formData {Array}: Data to be sent along with this file
method {String}: It's a request method. By default POST
removeAfterUpload {Boolean}: Remove this file from the queue after uploading
index {Number} - A sequence number upload
progress {Number}: File upload progress percentage
isReady {Boolean} - File is ready to upload
isUploading {Boolean}: true if the file is being uploaded
isUploaded {Boolean}: true if the file was uploaded
isSuccess {Boolean}: true if the file was uploaded successfully
isCancel {Boolean} : true if uploading was canceled
isError {Boolean} - true if occurred error while file uploading
uploader {Object}: Reference to the parent Uploader object for this file

Methods

remove function() {: Remove this file from the queue
upload function() {: Upload this file
cancel function() {: Cancels uploading of this file

Filters

Register a filter

var uploader = fileUploader.create({
    filters: [
        function( item ) {                    // A user-defined filter
            console.log( 'filter1' );
            return true;
        }
    ]
});

// Another user-defined filter
uploader.filters.push(function( item ) {
    console.log( 'filter2' );
    return true;
});

The default filter

The queue already has registered a default filter that looks like this:

function( item ) { 
	return angular.isElement( item ) ? true : !!item.size;
}

Events

Supported events

afteraddingfile function( event, item ) {: Fires after adding a single file to the queue
afteraddingall function( event, items ) {: Fires after adding all the dragged or selected files to the queue
beforeupload function( event, item ) {: Fires before uploading an item
progress function( event, item, progress ) {: On file upload progress
success function( event, xhr, item, response ) {: On file successfully uploaded
cancel function( event, xhr, item ) { - On cancel uploading
error function( event, xhr, item[, response ]) {: On upload error
complete function( event, xhr, item, response ) {: On file upload complete (independently of the sucess of the operation)
progressall function( event, progress ) {: On upload queue progress
completeall function( event, items ) {: On all loaded when uploading an entire queue, or on file loaded when uploading a single independent file

Registering event handlers

var uploader = fileUploader.create();

uploader.bind( 'progress', function( event, item, progress ) {
    console.log( 'Progress: ' + progress );
});

FAQ

How to add the previously uploaded files in the queue?

// Add a item to the queue
uploader.queue.push({
    example: {},      // your data here
    isUploaded: true
});

How do I deal with Cross Site Request Forgery protection?

See this issue: #40

For example, in Ruby on Rails, add an additional header, and use this method for verifying XSRF:

var csrf_token = document.querySelector('meta[name="csrf-token"]').getAttribute('content');

var uploader = $scope.uploader = fileUploader.create({
      // your code here...
      headers : {
        'X-CSRF-TOKEN' : csrf_token // X-CSRF-TOKEN is used for Ruby on Rails Tokens
      },
      //...
  });

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

О модуле

Angular File Upload - модуль загрузки файлов (html5 + iframe) для фреймворка AngularJS. Поддерживает drag-n-drop загрузку, индикацию прогресса загрузки, очередь. В старых браузерах деградирует до iframe загрузчика.
В общих чертах работа модуля выглядит так: директивы "ловят" файлы и добавляют их в очередь, если те прошли фильтры, после чего "загрузчик файлов" может ими (элементами очереди) манипулировать.

Примеры

Требует

AngularJS фреймворк
ES5 (Array.indexOf, Array.forEach, Array.filter, Array.every, Function.bind, Date.now)

Включает

Директивы

nrvFileSelect - применяется к<input type="file" />. Выбранные файлы добавляются в очередь загрузки, если они прошли фильтры.
nrvFileDrop - задает область сброса файлов / элемент, который будет ловить файлы. Как правило, применяется ко всему документу. Пойманные файлы добавляются в очередь загрузки, если они прошли фильтры.
nrvFileOver - применяется к элементу, который будет реагировать (менять класс), когда файлы находятся над областью сброса. По умолчанию добавляется класс nrv-file-over. Другой класс можно задать в параметре атрибута nrv-file-over="className".

Сервис

fileUploader - управляет очередью и загрузкой файлов

Загрузчик API:

Свойства

scope {Object} - ссылка на scope для обновления html. Если параметр опущен, используется $rootScope
url {String} - путь на сервере, по которому будут загружаться файлы
alias {String} - псевдоним файла
queue {Array}- очередь загрузки
progress {Number}- прогресс загрузки очереди
headers {Object} - заголовки, которые будут переданы вместе с файлами
formData {Array} - данные, отправляемые вместе с файлами
filters {Array} - фильтры, применяемые к [файлу|элементу] перед добавлением его в очередь. Если фильтр возвращает true, [файл|элемент] будет добавлен в очередь
autoUpload {Boolean} - загружать автоматически после добавления элемента в очередь
method {String}: - метод запроса. По умолчанию POST
removeAfterUpload {Boolean} - удалить файлы после загрузки
isHTML5 {Boolean} - true, если это html5-загрузчик
isUploading {Boolean} - загрузчик в процессе загрузки

Методы

bind function( event, handler ) { - регистрирует обработчик события
trigger function( event[, params ]) { - выполняет все обработчики, связанные с данным событием
addToQueue function( items, options ) { - где items [FileList|File|Input], options [Object]
removeFromQueue function( value ) { - где value элемент очереди или его индекс [Item|Index]
clearQueue function() { - удаляет все элементы из очереди
getIndexOfItem function( item ) { return [Number]; } - где item элемент очереди
getReadyItems function() { return [Array]; }- Возвращает элементы готовые к загрузке
getNotUploadedItems function() { return [Array]; } - возвращает массив не загруженных элементов
uploadItem function( value ) { - где value элемент очереди или его индекс [Item|Index]
uploadAll function() { - загружает все незагруженные элементы
cancelItem function( value ) { - где value элемент очереди или его индекс [Item|Index]
cancelAll function() { - отменяет все текущие загрузки

Элемент очереди API:

Свойства

url {String} - путь на сервере, по которому будет загружен файл
alias {String} - псевдоним файла
headers {Object} - заголовки, которые будут переданы вместе с файлом
formData {Array} - данные, отправляемые вместе с файлом
method {String}: - метод запроса. По умолчанию POST
removeAfterUpload {Boolean} - удалить файл после загрузки
index {Number} - индекс / порядковый номер загрузки
progress {Number} - прогресс загрузки файла
isReady {Boolean} - файл готов к загрузке
isUploading {Boolean} - файл в процессе загрузки
isUploaded {Boolean} - файл загружен
isSuccess {Boolean} - файл успешно загружен
isCancel {Boolean} - загрузка файла была отменена
isError {Boolean} - при загрузке файла произошла ошибка
uploader {Object} - ссылка на загрузчик

Методы

remove function() { - удаляет элемент
upload function() { - загружает элемент
cancel function() { - отменяет загрузку элемента

Фильтры

Добавить фильтр

var uploader = fileUploader.create({
    filters: [
        function( item ) {                    // first user filter
            console.log( 'filter1' );
            return true;
        }
    ]
});

// second user filter
uploader.filters.push(function( item ) {
    console.log( 'filter2' );
    return true;
});

Стандартный фильтр

По умолчанию в массиве фильтров уже присутствует один фильтр, который имеет вид:

function( item ) { 
	return angular.isElement( item ) ? true : !!item.size;
}

События

Список событий

afteraddingfile function( event, item ) { - после добавления файла в очередь
afteraddingall function( event, items ) { - после добавления всех файлов в очередь
beforeupload function( event, item ) { - перед загрузкой файла
progress function( event, item, progress ) { - прогресс загрузки файла
success function( event, xhr, item, response ) { - файл успешно загружен
cancel function( event, xhr, item ) { - отменяет загрузку файла
error function( event, xhr, item[, response ]) { - ошибка при загрузке
complete function( event, xhr, item, response ) { - файл загружен
progressall function( event, progress ) { - прогресс загрузки очереди
completeall function( event, items ) { - "очередь загружена", если была инициирована загрузка всей очереди; иначе "файл загружен", если была инициирована загрузка файла

Подписка на событие

var uploader = fileUploader.create();

uploader.bind( 'progress', function( event, item, progress ) {
    console.log( 'Progress: ' + progress );
});

FAQ / Вопросы и ответы

Как добавить ранее загруженные файлы в очередь?

// Add a item to the queue
uploader.queue.push({
    example: {},      // your data here
    isUploaded: true
});

chrkhl/angular-file-upload

English documentation

About

Demos

Requires

Includes

Directives

Service

The Uploader API:

Properties

Methods

The Item API:

Properties

Methods

Filters

Register a filter

The default filter

Events

Supported events

Registering event handlers

FAQ

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

О модуле

Примеры

Требует

Включает

Директивы

Сервис

Загрузчик API:

Свойства

Методы

Элемент очереди API:

Свойства

Методы

Фильтры

Добавить фильтр

Стандартный фильтр

События

Список событий

Подписка на событие

FAQ / Вопросы и ответы