Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vugar005/ngx-awesome-uploader
Angular Library for uploading files with many features
https://github.com/vugar005/ngx-awesome-uploader
List: ngx-awesome-uploader
Last synced: about 1 month ago
JSON representation
Angular Library for uploading files with many features
- Host: GitHub
- URL: https://github.com/vugar005/ngx-awesome-uploader
- Owner: vugar005
- Created: 2019-01-15T19:04:02.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-02-22T16:08:52.000Z (10 months ago)
- Last Synced: 2024-04-10T17:19:19.429Z (8 months ago)
- Language: TypeScript
- Size: 1.22 MB
- Stars: 131
- Watchers: 5
- Forks: 30
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-angular - ngx-awesome-uploader - Angular Library for uploading files with many features. (Uncategorized / Uncategorized)
README
# NGX-AWESOME-UPLOADER
[]() [](https://www.npmjs.com/package/ngx-awesome-uploader) [](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fsimple-demo%2Fsimple-demo.component.ts) [](https://twitter.com/vugar005) [](https://github.com/vugar005/ngx-awesome-uploader) [](https://github.com/vugar005/ngx-awesome-uploader) 
This is an Angular Library for uploading files. It supports: File Upload and Preview (additionally preview images with lightbox), validation, image cropper , drag and drop with multi language support.
Tested on Angular 6+. Supports Server Side Rendering.
>**Breaking Changes:** [Check Changes](https://github.com/vugar005/ngx-awesome-uploader/blob/master/breaking-changes-v10.md) changes if you come from version < 10.
* [Install](#install)
* [Usage](#usage)
* [Configuration](#api)
* [File Validation](#file-validation)
* [Built-in validations](#built-in-validations)
* [Custom validation](#custom-validation)
* [Cropper](#cropper)
* [Custom template](#custom-template)
* [Multi Language](#multi-language)
* [Edit Mode](#edit-mode)
* [Bonus](#bonus)
## Quick-links
[Example Application](https://ngx-awesome-uploader.stackblitz.io/) or
[StackBlitzDemo](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fsimple-demo%2Fsimple-demo.component.ts)
## Install
npm install ngx-awesome-uploader --save
##### Load the module for your app:
```typescript
import { FilePickerModule } from 'ngx-awesome-uploader';
@NgModule({
imports: [
...
FilePickerModule
]
})
```
## Usage
In order to make library maximum compatible with apis you need to create and provide
custom adapter which implements upload and remove requests. That's because I have no idea how to get file id in upload response json :) .
So this libray exposes a FilePickerAdapter abstract class which you can import on your new class file definition:
``` import { FilePickerAdapter } from 'ngx-awesome-uploader';```
After importing it to your custom adapter implementation (EG: CustomAdapter.ts), you must implement those 2 methods which are abstract in the FilePickerAdapter base class which are:
```
public abstract uploadFile(fileItem: FilePreviewModel): Observable;
public abstract removeFile(fileItem: FilePreviewModel): Observable;
```
You can check DEMO adapter [here](https://github.com/vugar005/ngx-awesome-uploader/tree/master/projects/file-picker/src/lib/mock-file-picker.adapter.ts)
#### Now you can use it in your template
```html
```
#### and in the Component:
```typescript
import { HttpClient } from '@angular/common/http';
import { DemoFilePickerAdapter } from './demo-file-picker.adapter';
import { Component} from '@angular/core';
@Component({
selector: 'demo-file-picker',
templateUrl: './demo-file-picker.component.html',
styleUrls: ['./demo-file-picker.component.scss']
})
export class DemoFilePickerComponent {
adapter = new DemoFilePickerAdapter(this.http);
constructor(private http: HttpClient) { }
}
```
>**Note:** As you see you should provide http instance to adapter.
Still in Doubt? Check [Minimal Setup Demo](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fsimple-demo%2Fsimple-demo.component.ts)
## API
```typescript
/** Whether to enable cropper. Default: disabled */
@Input() enableCropper = false;
/** Whether to show default drag and drop template. Default:true */
@Input() showeDragDropZone = true;
/** Single or multiple. Default: multi */
@Input() uploadType = 'multi';
/** Max size of selected file in MB. Default: no limit */
@Input() fileMaxSize: number;
/** Max count of file in multi-upload. Default: no limit */
@Input() fileMaxCount: number;
/** Total Max size limit of all files in MB. Default: no limit */
@Input() totalMaxSize: number;
/** Which file types to show on choose file dialog. Default: show all */
@Input() accept: string;
/** File extensions filter. Default: any exteion */
@Input() fileExtensions: String;
/** Cropper options if cropper enabled. Default:
dragMode: 'crop',
aspectRatio: 1,
autoCrop: true,
movable: true,
zoomable: true,
scalable: true,
autoCropArea: 0.8
*/
@Input() cropperOptions: Object;
/** Custom Adapter for uploading/removing files. Required */
@Input() adapter: FilePickerAdapter;
/** Custom template for dropzone. Optional */
@Input() dropzoneTemplate: TemplateRef;
/** Custom Preview Item template. Optional */
@Input() itemTemplate: TemplateRef;
/** Whether to show default files preview container. Default: true */
@Input() showPreviewContainer = true;
/** Custom validator function. Optional */
@Input() customValidator: (file: File) => Observable;
/** Custom captions input. Used for multi language support */
@Input() captions: UploaderCaptions;
/** Whether to auto upload file on file choose or not. Default: true. You can get files list by accessing component files. */
@Input() enableAutoUpload = true;
/** capture paramerter for file input such as user,environment*/
@Input() fileInputCapture: string;
```
## Output events
```typescript
/** Emitted when file upload via api success.
Emitted for every file */
@Output() uploadSuccess = new EventEmitter();
/** Emitted when file upload via api fails.
Emitted for every file */
@Output() uploadFail = new EventEmitter();
/** Emitted when file is removed via api successfully.
Emitted for every file */
@Output() removeSuccess = new EventEmitter();
/** Emitted on file validation fail */
@Output() validationError = new EventEmitter();
/** Emitted when file is added and passed validations. Not uploaded yet */
@Output() fileAdded = new EventEmitter();
/** Emitted when file is removed from fileList */
@Output() fileRemoved = new EventEmitter();
```
## File-Validation
### Built-in-validations
All validations are emitted through ValidationError event.
To listen to validation errors (in case you provided validations), validationError event is emitted. validationError event implements interface [ValidationError](https://github.com/vugar005/ngx-awesome-uploader/blob/master/projects/file-picker/src/lib/validation-error.model.ts)
and which emits failed file and error type.
Supported validations:
| **Validation Type** | **Description** | **Default** |
|----------------------------|---------------------------------------------------------------------------------------|----------------------------------------|
| fileMaxSize: number | Max size of selected file in MB. | No limit
| fileExtensions: String | Emitted when file does not satisfy provided extension | Any extension
| uploadType: String | Upload type. Values: 'single' and 'multi'. |multi
| totalMaxSize: number | Total Max size of files in MB. If cropper is enabled, the cropped image size is considered.| No limit
| fileMaxCount: number | Limit total files to upload by count | No limit
### Custom-validation
You can also provide your own custom validation along with built-in validations.
You custom validation takes `file: File` and returns `Observable`;
So that means you can provide sync and async validations.
```
public myCustomValidator(file: File): Observable {
if (file.name.includes('panda')) {
return of(true);
}
if (file.size > 50) {
return this.http.get('url').pipe(map((res) => res === 'OK' ));
}
return of(false);
}
```
and pass to Template:
```html
```
Check [Demo](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fadvanced-demo%2Fadvanced-demo.component.html)
## Cropper
Library uses cropperjs to crop images but you need import it to use it. Example: in index html
```html
```
>**Note**: To use cropper, you should set enableCropper to true. Look at API section above.
You can also provide your custom cropper options.
## Custom-Template
You can provide custom template to library.
I) To provide custom template for drag and drop zone, use content projection. Example:
```html
Custom
````
>**Note:** The wrapper of your custom template must have a class **dropzoneTemplate**.
[Checkout Demo](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fadvanced-demo%2Fadvanced-demo.component.html)
II) To use custom file preview template, pass your custom template as below:
```html
{{fileItem.file.size}}
{{fileItem.fileName}}
{{uploadProgress}}%
Remove
```
In custom template uploadProgress and fileItem (which implements [FilePrevieModel](https://github.com/vugar005/ngx-awesome-uploader/blob/master/projects/file-picker/src/lib/file-preview.model.ts) interface) are exposed .
## Multi Language
You can add multi language support for library by providing ***captions*** object (which implements [UploaderCaptions](https://github.com/vugar005/ngx-awesome-uploader/blob/master/projects/file-picker/src/lib/uploader-captions.ts) interface).
Check [Demo](https://stackblitz.com/edit/ngx-awesome-uploader?file=src%2Fapp%2Fadvanced-demo%2Fadvanced-demo.component.html)
## Edit Mode
You can show your files without uploading them
``` @ViewChild('uploader', { static: true }) uploader: FilePickerComponent; ```
```
public ngOnInit(): void {
const files = [
{
fileName: 'My File 1 for edit.png'
},
{
fileName: 'My File 2 for edit.xlsx'
}
] as FilePreviewModel[];
this.uploader.setFiles(files);
}
```
## Bonus
You can also check out library [router animations ](https://www.npmjs.com/package/ngx-router-animations)
## Contribution
You can fork project from github. Pull requests are kindly accepted.
1. Building library: ng build file-picker --prod
2. Running tests: ng test file-picker --browsers=ChromeHeadless
3. Run demo: ng serve