Ngx-file-upload-selector NPM

ngx-file-upload-selector

The Angular 9 component enables file selection and validation.

Installation

npm install ngx-file-upload-selector --save

Usage

Install the library via npm

Import NgxFileUploadSelectorModule into your AppModule:

```
import {BrowserModule} from '@angular/platform-browser';
import {NgModule} from '@angular/core';
import {NgxFileUploadSelectorModule} from 'ngx-file-upload-selector';

import {AppComponent} from './app.component';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        NgxFileUploadSelectorModule
    ],
    providers: [],
    bootstrap: [AppComponent]
})
export class AppModule {
}
```

Use in your component's template:

<div class="file-uploader-container">
    <ngx-file-upload-selector
        [fileTypePackage]="fileTypePackage"
        [uploadedFiles]="uploadedFiles"
        [uploadFeedback]="uploadFeedback"
        [deleteFeedback]="deleteFeedback"
        (validationSuccess)="onValidationSuccess($event)"
        (fileDeletion)="onDeleteFile($event)">
    </ngx-file-upload-selector>
</div>

Public API

The component accepts an object called fileTypePackage, which contains the allowed number of files, the allowed file types and validation rules for each file type. By default, all the texts are displayed in English, so to use the library with another language, one must also provide "uploadTexts" and "errorMessages", in the required language. (The lib does not provide internationalization services.)
This object needs to be structured like this:
```
```
{
    id: string,
    maxNumberOfFiles: number,
    uploadTexts:
    {
        uploadMessage: string,
        filesInProgress: string,
        uploadSuccess: string,
        uploadFailure: string,
        uploadButton: string,
        okButton: string,
    },
    errorMessages:
    {
        alreadyUploaded: string,
        fileNumber: string,
        mimeType: string,
        fileName: string,
        fileSize: string
    },
    uploaderFileTypes: [
        {
            labelId: string,
            allowedMimeTypes: string[],
            allowedFilenameAndExtension: string,
            allowedExtensions: string[],
            maxFileSize: number,
            label: string,
            commentExists: boolean,
            itemMandatory: boolean,
            appearanceOrder: number
        }
    ]
};
```
```
- the fields of uploadTexts and errorMessages contain the texts displayed in the (drag & drop) file upload area, and the upload progress modal
- uploaderFileTypes is an array that consists of the allowed file types with their respective validation rules
- maxFileSize: given in bytes
- allowedFilenameAndExtension contains a regular expression as a string, while allowedExtensions is a string array
- label stands for the text users will see regarding the given file type, e.g. 'image'
- appearanceOrder: the component displays the file types sorted along this property
The second necessary input is uploadedFiles, an array containing the data of those files that have already been successfully uploaded to the backend server.
An item of this array - the uploadedFile object needs to look like this:
```
```
{
    fileId: string;
    packageId: string;
    sourceURL: string;
    thumbnail: string;
    fileMetaData: 
        {
            labelId: string;
            label: string;
            mimeType: string;
            fullFileName: string;
            fileSize: number;
            comment: string;
        }
};
```
```
- fileId, packageId and sourceUrl are received from the backend; sourceURL is needed to display the uploaded images within the component
The third input is uploadFeedback, an Observable which, during the upload process of a file, emits regular "feedback" data to update the progress bar and finally, to set success or failure status for the upload process. The feedback object has the following structure:
```
{
     progress: number;
     errors: string[];
 }
```
When the upload has finished, the last emitted value must have progress: null, errors: null on success and progress: null, errors: [list of errors] on failure. The list of errors may contain any of the built-in validation error types or custom error messages alike.
Built-in validation types:
```
 - ALREADY_UPLOADED,
 - FILE_NUMBER,
 - MIME_TYPE,
 - FILE_NAME,
 - FILE_SIZE
```
If, regarding these built-in validation types, the file fails to pass the validation rules received in the fileTypePackage already within the lib, the error message(s) is(/are) displayed immediately, and no validationSuccess event is emitted. (That is, the file will never be sent to the backend server.) Otherwise, it is up to the backend logic to decide whether the file that has passed front end validation can be saved or any error message is sent back.
At last, the library requires an input object called deleteFeedback, which is an Observable emitting a boolean on receiving the result of a file deletion request: true if deletion was successful, false otherwise.
The component can emit 2 types of events:
1. validationSuccess: the file has passed all validation rules successfully, and it is emitted to the host component.
  The object, validatedFile, contains the file itself in base64 encoded form and its thumbnail together with its metadata, and is of the following structure:
```
{ 
    thumbnail: string;
    fileBase64String: string;
    fileMetaData: 
        {
            labelId: string;
            label: string;
            mimeType: string;
            fullFileName: string;
            fileSize: number;
            comment: string;
        }
}
```
2. fileDeletion: if the user chooses to delete one of the previously successfully uploaded files, this event is emitted with the uploadedFile object.

The library does not handle the actual uploading of the files to a server, it only aids selection and validation. Sending the upload request to a server is the host application's responsibility.

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago