1 | # ng2-file-upload [![npm version](https://badge.fury.io/js/ng2-file-upload.svg)](http://badge.fury.io/js/ng2-file-upload) [![npm downloads](https://img.shields.io/npm/dm/ng2-file-upload.svg)](https://npmjs.org/ng2-file-upload)
|
2 | Easy to use Angular2 directives for files upload ([demo](http://valor-software.github.io/ng2-file-upload/))
|
3 |
|
4 | [![Angular 2 Style Guide](https://mgechev.github.io/angular2-style-guide/images/badge.svg)](https://github.com/mgechev/angular2-style-guide)
|
5 | [![Build Status](https://travis-ci.org/valor-software/ng2-file-upload.svg?branch=development)](https://travis-ci.org/valor-software/ng2-file-upload)
|
6 |
|
7 |
|
8 | ## Quick start
|
9 |
|
10 | 1. A recommended way to install ***ng2-file-upload*** is through [npm](https://www.npmjs.com/search?q=ng2-file-upload) package manager using the following command:
|
11 |
|
12 | `npm i ng2-file-upload`
|
13 |
|
14 | Alternatively, you can [download it in a ZIP file](https://github.com/valor-software/ng2-file-upload/archive/master.zip).
|
15 |
|
16 | 2. Currently `ng2-file-upload` contains two directives: `ng2-file-select` and `ng2-file-drop`. `ng2-file-select` is used for 'file-input' field of form and
|
17 | `ng2-file-drop` is used for area that will be used for dropping of file or files.
|
18 |
|
19 | 3. More information regarding using of ***ng2-file-upload*** is located in
|
20 | [demo](http://valor-software.github.io/ng2-file-upload/) and [demo sources](https://github.com/valor-software/ng2-file-upload/tree/master/demo).
|
21 |
|
22 | ## Using ***ng2-file-upload*** in a project
|
23 |
|
24 | 1. Install as shown in the above section.
|
25 |
|
26 | 2. Import `FileUploadModule` into the module that declares the component using ***ng2-file-upload***:
|
27 |
|
28 | ```import { FileUploadModule } from 'ng2-file-upload';```
|
29 |
|
30 | 3. Add it to `[imports]` under `@NgModule`:
|
31 |
|
32 | ```imports: [ ... FileUploadModule, ... ]```
|
33 |
|
34 | 4. Import `FileUploader` into the component:
|
35 |
|
36 | ```import { FileUploader } from 'ng2-file-upload';```
|
37 |
|
38 | 5. Create a variable for the API url:
|
39 |
|
40 | ```const URL = 'path_to_api';```
|
41 |
|
42 | 6. Initialize it:
|
43 |
|
44 | ```public uploader:FileUploader = new FileUploader({url: URL}); ```
|
45 |
|
46 | ## API for `ng2FileSelect`
|
47 |
|
48 | ### Properties
|
49 |
|
50 | - `uploader` - (`FileUploader`) - uploader object. See using in [demo](https://github.com/valor-software/ng2-file-upload/blob/master/demo/components/file-upload/simple-demo.ts)
|
51 |
|
52 | ### Events
|
53 | - `onFileSelected` - fires when files are selected and added to the uploader queue
|
54 |
|
55 | ## API for `ng2FileDrop`
|
56 |
|
57 | ### Properties
|
58 |
|
59 | - `uploader` - (`FileUploader`) - uploader object. See using in [demo](https://github.com/valor-software/ng2-file-upload/blob/master/demo/components/file-upload/simple-demo.ts)
|
60 |
|
61 | Parameters supported by this object:
|
62 |
|
63 | 1. `url` - URL of File Uploader's route
|
64 | 2. `authToken` - Auth token that will be applied as 'Authorization' header during file send.
|
65 | 3. `disableMultipart` - If 'true', disable using a multipart form for file upload and instead stream the file. Some APIs (e.g. Amazon S3) may expect the file to be streamed rather than sent via a form. Defaults to false.
|
66 | 4. `itemAlias` - item alias (form name redefinition)
|
67 | 5. `formatDataFunction` - Function to modify the request body. 'DisableMultipart' must be 'true' for this function to be called.
|
68 | 6. `formatDataFunctionIsAsync` - Informs if the function sent in 'formatDataFunction' is asynchronous. Defaults to false.
|
69 | 7. `parametersBeforeFiles` - States if additional parameters should be appended before or after the file. Defaults to false.
|
70 |
|
71 | ### Events
|
72 |
|
73 | - `fileOver` - it fires during 'over' and 'out' events for Drop Area; returns `boolean`: `true` if file is over Drop Area, `false` in case of out.
|
74 | See using in [ts demo](https://github.com/valor-software/ng2-file-upload/blob/master/demo/components/file-upload/simple-demo.ts) and
|
75 | [html demo](https://github.com/valor-software/ng2-file-upload/blob/master/demo/components/file-upload/simple-demo.html)
|
76 | - `onFileDrop` - it fires after a file has been dropped on a Drop Area; you can pass in `$event` to get the list of files that were dropped. i.e. `(onFileDrop)="dropped($event)"`
|
77 |
|
78 | # Troubleshooting
|
79 |
|
80 | Please follow these guidelines when reporting bugs and feature requests:
|
81 |
|
82 | 1. Use [GitHub Issues](https://github.com/valor-software/ng2-file-upload/issues) board to report bugs and feature requests (not our email address)
|
83 | 2. Please **always** write steps to reproduce the error. That way we can focus on fixing the bug, not scratching our heads trying to reproduce it.
|
84 |
|
85 | Thanks for understanding!
|
86 |
|
87 | ### License
|
88 |
|
89 | The MIT License (see the [LICENSE](https://github.com/valor-software/ng2-file-upload/blob/master/LICENSE) file for the full text)
|
90 |
|
\ | No newline at end of file |