Do an upload with Angular and ngx-upload

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. Default true.

 

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.