angular-file

Easy to use Angular directives for file uploading (DEMO PAGE)

This package is to handle select/drag/drop of files. It is NOT a package to transmit files to a server (example page has transmit example).

Table of Contents

• Quick Start
• Examples
• API
  • ngf Directive
  • ngfDrop Directive
  • ngfBackground Directive
  • ngfSelect Directive
  • ngfUploadStatus Directive
• Troubleshooting
• Credits
• License

Quick Start

1. A recommended way to install angular-file is through npm package manager using the following command:

npm install angular-file --save-dev

Alternatively, you can download it in a ZIP file.

2. Currently angular-file contains three directives: ngf, ngfSelect, and ngfDrop. ngf and ngfSelect are quite the same with just different defaults and they both utilize <input type="file" /> functionality. ngfDrop is used to designate an area that will be used for dropping of file(s).

3. More information regarding using of angular-file is located in demo and demo sources.

Examples

Practical Example

An example intended to have every line needed to run an app with angular-file

import { ngfModule, ngf } from "angular-file"
import { Component, NgModule } from "@angular/core"
import { HttpClient, HttpRequest, HttpResponse, HttpEvent } from '@angular/common/http'
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'
import { BrowserModule } from '@angular/platform-browser'
import { Subscription } from 'rxjs'

//two ways to upload files
const template = `
<input
  ngf
  multiple
  type      = "file"
  accept    = "image/*"
  [(files)] = "files"
  maxSize   = "1024"
/>
<button *ngIf="files" (click)="uploadFiles(files)">send files</button>

<ngfFormData
  [files]      = "files"
  [(FormData)] = "myFormData"
  postName     = "file"
></ngfFormData>

<ngfUploadStatus
  [(percent)] = "uploadPercent"
  [httpEvent] = "httpEvent"
></ngfUploadStatus>

<div *ngIf="uploadPercent">
  Upload Progress: {{ uploadPercent }}%
</div>
`

@Component({
  selector: 'app',
  template: template
})
export class AppComponent {
  postUrl = '...'
  myFormData:FormData//populated by ngfFormData directive
  httpEvent:HttpEvent<Event>

  constructor(public HttpClient:HttpClient){}

  uploadFiles(files:File[]) : Subscription {
    const config = new HttpRequest('POST', this.postUrl, this.myFormData), {
      reportProgress: true
    })
    
    return this.HttpClient.request( config )
    .subscribe(event=>{
      this.httpEvent = event
      
      if (event instanceof HttpResponse) {
        alert('upload complete, old school alert used')
      }
    },
    error=>{
      alert('!failure beyond compare cause:' + error.toString())
    })
  }
}

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

platformBrowserDynamic().bootstrapModule(AppModule);

Select Files Examples

Examples of how to allow file selection

Multiple

<input type="file" ngf [(files)]="files" multiple  />

Single

<input type="file" ngf [(file)]="file" />

Element

<div ngfSelect multiple="1" [(files)]="files">
  Tap to Select
</div>

Images Only

<button ngfSelect [(file)]="userFile" accept="image/*" multiple="1">
  Tap to Select
</button>
<div [ngfBackground]="userFile"
  style="background-size:cover;background-repeat:no-repeat;width:50px;height:50px"
></div>

Drop Files Examples

Examples of how to allow file drag/drop

Basic

<div ngfDrop
  [(files)]="files"
  [(file)]="file"
  ([validDrag])="validDrag"
  ([invalidDrag])="invalidDrag"
  [ngClass]="{'myHoverClass': validDrag, 'myAntiHoverClass': validDrag}"
>
  Drop Files Here
</div>

Combo Drop Select

<div ngfDrop selectable="1" multiple="1"
  [(files)]="files"
  [(validDrag)]="validComboDrag"
  [(invalidDrag)]="invalidComboDrag"
  [ngClass]="{'goodDragClass':validComboDrag, 'badDragClass':invalidComboDrag}"
>
  Combo drop/select zone
</div>

API

• ngf Directive
• ngfDrop Directive
• ngfBackground Directive
• ngfSelect Directive
• ngfUploadStatus Directive

ngf Directive

[(ngf)]             : ngf//reference to directive class
[multiple]          : string
[accept]            : string
[maxSize]           : number//bytes . 1024 = 1k . 1048576 = 1mb
[forceFilename]     : string
[forcePostname]     : string//when FormData object created, sets name of POST input
[ngfFixOrientation] : boolean = true
[fileDropDisabled]  : any = false
[selectable]        : any = false
[(lastInvalids)]    : {file:File,type:string}[] = []
[(lastBaseUrl)]     : string//Base64 od last file uploaded url
[(file)]            : File//last file uploaded
[(files)]           : File[]
(init)              : EventEmitter<ngf>

ngfDrop Directive

This directive extends ngf

(fileOver)      :EventEmitter<any> = new EventEmitter()
[(validDrag)]   :any = false
[(invalidDrag)] :any = false

Supporting Internet Explorer 11 or less?

Only (fileOver) works accurately [(validDrag)] & [(invalidDrag)] should NOT be used as IE11 does not indicate the number of files NOR the types of files being dragged like other modern web browsers

ngfSelect Directive

This directive extends ngf

[selectable]:any = true

ngfBackground Directive

[ngfBackground]:File

ngfUploadStatus Directive

Does calculations of an upload event and provideds percent of upload completed

[(percent)]:number
[httpEvent]:Event

ngfFormData Directive

Converts files to FormData

[files]:File[]
[postName]:string = "file"
[fileName]:string//force file name
[(FormData)]:FormData

Troubleshooting

Please follow this guidelines when reporting bugs and feature requests:

1. Use GitHub Issues board to report bugs and feature requests (not our email address)
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.

Thanks for understanding!

Credits

• Current Author: Acker Apple
• Forked from outdated package: ng2-file-upload

License

The MIT License (see the LICENSE file for the full text)