Today, I'm going to tell you about doing an upload with Angular. To do that, we are going to use the library ngx-upload. it allows to do an upload with drag & drop and to handle events easily. Ngx-upload is distinguished by its agnostic character; in other words it can be integrated into anyone presentation framework.
Setup
The best way to install ngx-upload is through npm or yarn like this:
npm install @wkoza/ngx-upload
or
yarn add @wkoza/ngx-upload
Now, you have to add the module named NgxUploadModule
in your AppModule
which is often the case:
I have also to add the module HttpClientModule
in order to perform the upload.
Create a drag and drop zone
With ngx-upload, create a drag&drop zone is straightforward through the ngxDragAndDrop
directive. A simple <div>
with this directive allows to drag&drop a file in the upload queue.
The css class is here to specifiy the size, the style of cursor, the opacity :
So, you just have to add this <div>
in your template component and a css class which defines the size of your drop zone; usually, we want to react, with a css style, when the file is in the drop zone and when the file is dropped. With ngx-upload, it is configurable with when the help of DropTargetOptions
. This object has 3 propeties to change the css class regarding the drop event:
-
When you drag a file in the zone with the propety
dropZoneColorDrag
-
When you drop a file with the property
dropZoneColorDrop
-
In other cases with the propety
dropZoneColor
For instance, you can use the 3 css classes:
For link these classes to ngx-upload on a global basis, you have to create an objet of type DropTargetOptions
like this:
and add this object to the static forRoot()
method :
You can also give this object to the ngxDragAndDrop
directive like that:
Add a file explorer
Ngx-upload offers one structural directive which allows the user to choose one or more files from their device storage. This structural directive can be use directly on the drop zone element :
In this case, the file explorer will open when the user will click on the drop zone; If you prefer, you can use this structural directive with a button. The implementation depends on your UI framework.
With bootstrap, you have a straightforward implementation:
With material, it's a little more complex but nothing serious:
*ngxInputFile
supports a configuration object of type InputFileOptions
. For instance:
There are 3 properties:
-
accept
One or more unique file type specifiers describing file types to allow. you can see the complet list here -
capture
What source to use for capturing image or video data. The values are 'user' or 'environment'. -
multiple
A Boolean which, if present, indicates that the user may choose more than one file. Defaulttrue
.
Upload queue
Each file is added to a queue that you can handle with HttpClientUploadService
. This service offers 7 Observable
to handle a specific behavior :
-
onCancel$
: This Observable emits when upload is canceled. -
onError$<{ item: FileItem, body: any, status: number, headers: any }>
: This Observable emits on error during the upload process. -
onSuccess$<{ item: FileItem, body: any, status: number, headers: any }>
: This Observable emits on success. -
onBeforeUploadItem$
: This Observable emits just before the upload process. -
onProgress$<{ item: FileItem, progress: number }>
: This Observable emits during the upload process. -
onAddToQueue$<>
: This Observable is trigged when a file is added in the queue. -
onDropError$<{ item?: File, errorAccept: boolean, errorMultiple: boolean }>
: This Observable is trigged when a file is not accepted in the queue.
Here is an example:
It's the good way to handle error, or to warn the user.
Now, the last step is the creation of your HTML template where we can see the content of your queue and how to can launch the upload; This is an example which can help you to figure out the API:
One must remember that HttpClientUploadService
offers a property named queue
where are stored the files; So, you can define the number of files in the queue or list the file with a simple *ngFor. queue
contents a list of FileItem
objects. FileItem
has an API similar to HttpClientUploadService
. You can upload, cancel or remove this file of the queue. HttpClientUploadService
handles all the file in a same time.
Finally, the project proposes two implementations with Bootstrap and Material; It's a good source of inspiration.