docs

README.md

@@ -1,5 +1,5 @@
 # angular-file
-Easy to use Angular directives for files upload ([demo](http://ackerapple.github.io/angular-file/))
+Easy to use Angular directives for file uploading ([demo](http://ackerapple.github.io/angular-file/))
 
 [![npm version](https://badge.fury.io/js/angular-file.svg)](http://badge.fury.io/js/angular-file)
 [![npm downloads](https://img.shields.io/npm/dm/angular-file.svg)](https://npmjs.org/angular-file)
@@ -10,32 +10,42 @@ Easy to use Angular directives for files upload ([demo](http://ackerapple.github
 <details>
   <summary>Table of Contents</summary>
 
+- [Compare](#compare)
 - [Quick Start](#quick-start)
 - [Examples](#examples)
 - [API](#api)
+- [Upgrading from ng2-file-upload](#upgrading-from-ng2-file-upload)
 - [Troubleshooting](#troubleshooting)
 - [Credits](#credits)
 - [License](#license)
 
 </details>
 
+## Compare
+Before even getting started, gage this package against others
+
+> Currently, September of 2017, [ng2-file-upload](https://www.npmjs.com/package/ng2-file-upload) is the most trending Angular file upload package. This package, **angular-file**, is a much improved fork of ng2-file-upload. Use angular-file **NOT** the outdated ng2-file-upload
+
+[TAP here for npmtrends of Angular file uploaders](http://www.npmtrends.com/angular2-http-file-upload-vs-angular2-file-uploader-vs-ng2-file-upload-vs-angular-file)
+
+
 ## Quick Start
 
 1. A recommended way to install ***angular-file*** is through [npm](https://www.npmjs.com/search?q=angular-file) package manager using the following command:
 
-  `npm i angular-file --save-dev`
+  `npm install angular-file --save-dev`
 
   Alternatively, you can [download it in a ZIP file](https://github.com/ackerapple/angular-file/archive/master.zip).
 
-2. Currently `angular-file` contains two directives: `ngfSelect` and `ngFileDrop`. `ngfSelect` is used for 'file-input' field of form and
-  `ngfDrop` is used for area that will be used for dropping of file or files.
+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](http://ackerapple.github.io/angular-file/) and [demo sources](https://github.com/ackerapple/angular-file/tree/master/demo).
 
 ## Examples
 
 ### Quickest Dirty Example
+Showing off. This is NOT the best approach but sure does get a lot done for a little
 ```html
 <input
   type="file"
@@ -48,6 +58,7 @@ Easy to use Angular directives for files upload ([demo](http://ackerapple.github
 ```
 
 ### Practical Example
+An example intended to have every line needed to run an app with angular-file
 ```typescript
 import { ngfModule, FileUploader, ngf } from "angular-file"
 import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
@@ -56,12 +67,25 @@ import { Component, NgModule } from "@angular/core"
 import { Http, Response, Request } from '@angular/http';
 import 'rxjs/add/operator/toPromise';
 
+//two ways to upload files
 const template = `
 <input
   type="file"
   multiple
   accept="image/*"
   [(ngf)]="ngfVar"
+  [(file)]="file"
+  [(files)]="files"
+  maxSize="1024"
+/>
+<button *ngIf="file" (click)="sendByModel(file)">send one file</button>
+<button *ngIf="file" (click)="uploadFiles(files)">send multi file</button>
+
+<input
+  type="file"
+  multiple
+  accept="image/*"
+  ngf
   (filesChange)="uploadFiles($event)"
   maxSize="1024"
 />
@@ -72,15 +96,17 @@ const template = `
   template: template
 })
 export class AppComponent {
-  ngfVar:ngf
+  ngfVar:ngf//becomes populated by template [(ngf)]="ngfVar"
 
   constructor(public Http:Http){}
 
   // takes array of HTML5 Files and uploads
   uploadFiles(files:File[]):Promise<number>{
-    const uploader:FileUploader = ngfVar.uploader
+    const uploader:FileUploader = this.ngfVar.uploader
 
-    //to HTML5 FormData for transmission
+    //uploader.options.forcePostname = 'POST-NameIfNotJust-FILE'
+
+    //to HTML5 FormData for transmission (hint: post name defaults to "file")
     const formData:FormData = uploader.getFormData(files)
 
     const config = new Request({
@@ -89,11 +115,33 @@ export class AppComponent {
       body:formData
     })
 
+    return this.postRequest(config)
+  }
+
+  postRequest( config:Request ){
     return this.Http.request( config )
     .toPromise()
     .then( ()=>alert('upload complete, old school alert used') )
     .catch( e=>alert('!failure beyond compare cause:' + e.toString()) )
   }
+
+  // takes HTML5 File and uploads
+  sendByModel(file:File){
+    const uploader:FileUploader = this.ngfVar.uploader
+
+    //uploader.options.forcePostname = 'POST-NameIfNotJust-FILE'
+
+    //to HTML5 FormData for transmission
+    const formData:FormData = uploader.getFormData( [file] )
+
+    const config = new Request({
+      url:'...',
+      method:'POST',
+      body:formData
+    })
+
+    return this.postRequest( config )
+  }
 }
 
 @NgModule({
@@ -177,7 +225,7 @@ Combo Drop Select
 [accept]:string
 [maxSize]:number
 [forceFilename]:string
-[forcePostname]:string
+[forcePostname]:string//when FormData object created, sets name of POST input
 [ngfFixOrientation]:boolean = true
 [fileDropDisabled] = false
 [selectable] = false
@@ -220,6 +268,28 @@ import { FileUploader } from "angular-file";
 - `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.
 - `itemAlias` - item alias (form name redefenition)
 
+## Upgrading from ng2-file-upload
+This package is a fork with a complete overhaul of [ng2-file-upload](https://www.npmjs.com/package/ng2-file-upload)
+
+- Breaking Changes
+  - ng2FileSelect becomes ngfSelect
+  - ng2FileDrop becomes ngfDrop
+  - Import Module
+    - Deprecated `import { FileUploadModule } from "ng2-file-upload"`
+    - **Update** `import { ngfModule } from "angular-file"`
+
+> More breaking changes may exist in upgrading including file naming conventions. This list is to be updated
+
+- Recommended Changes
+  - Use `ngf` selectable="1" instead of `ngfSelect`
+  - [uploader] was not to my liking
+    - I think this was a poor design
+    - Use `[(file)]` and `[(files)]` as models and then wrap them in HTML5 FormData for transmission
+      - Tools included to help do this
+  - `(fileOver)` is better suited as:
+    - `[(validDrag)]="validDragVar"`
+    - `[(invalidDrag)]="invalidDragVar"`
+
 ## Troubleshooting
 Please follow this guidelines when reporting bugs and feature requests:
 

package.json

@@ -1,6 +1,6 @@
 {
   "main": "index.js",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Angular file upload directives",
   "module": "index.js",
   "typings": "index.d.ts",