docs(storage): put, putString, upload, and downloadURL docs (angular#1650)

Author: renansigolo

docs/storage/storage.md

@@ -45,13 +45,62 @@ export class AppComponent {
 
 ### Uploading blobs
 
-There are two options for uploading files. 
+There are three options for uploading files.
 
 
-| method   |                    | 
-| ---------|--------------------| 
-| `put(data: Blob, metadata?: storage.UploadMetadata): AngularFireUploadTask` | Starts the upload of the blob to the storage reference's path. Returns an `AngularFireUploadTask` for upload monitoring. | 
+| method   |                    |
+| ---------|--------------------|
+| `put(data: Blob, metadata?: storage.UploadMetadata): AngularFireUploadTask` | Starts the upload of the blob to the storage reference's path. Returns an `AngularFireUploadTask` for upload monitoring. |
 | `putString(data: string, format?: StringFormat, metadata?: UploadMetadata): AngularFireUploadTask` | Updates an existing item in the array. Accepts a key, database reference, or an unwrapped snapshot. |
+| `upload(path: string, data: StringFormat, metadata?: UploadMetadata): AngularFireUploadTask` | Upload or update a new file to the storage reference's path. Returns an `AngularFireUploadTask` for upload monitoring. |
+
+#### Uploading blobs with put
+
+```ts
+import { Component } from '@angular/core';
+import { AngularFireStorage } from 'angularfire2/storage';
+
+@Component({
+  selector: 'app-root',
+  template: `
+  <input type="file" (change)="uploadFile($event)">
+  `
+})
+export class AppComponent {
+  constructor(private storage: AngularFireStorage) { }
+  uploadFile(event) {
+    const file = event.target.files[0];
+    const filePath = 'name-your-file-path-here';
+    const ref = this.storage.ref(filePath);
+    const task = ref.put(file);
+  }
+}
+```
+
+#### Uploading blobs with putString
+
+```ts
+import { Component } from '@angular/core';
+import { AngularFireStorage } from 'angularfire2/storage';
+
+@Component({
+  selector: 'app-root',
+  template: `
+  <input type="file" (change)="uploadFile($event)">
+  `
+})
+export class AppComponent {
+  constructor(private storage: AngularFireStorage) { }
+  uploadFile(event) {
+    const file = event.target.files[0];
+    const filePath = 'name-your-file-path-here';
+    const ref = this.storage.ref(filePath);
+    const task = ref.putString(file);
+  }
+}
+```
+
+#### Uploading files with upload
 
 ```ts
 import { Component } from '@angular/core';
@@ -77,15 +126,19 @@ export class AppComponent {
 
 An `AngularFireUploadTask` has methods for observing upload percentage as well as the final download URL.
 
-| method   |                    | 
-| ---------|--------------------| 
-| `snapshotChanges(): Observable<FirebaseStorage.UploadTaskSnapshot>` | Emits the raw `UploadTaskSnapshot` as the file upload progresses. | 
-| `percentageChanges(): Observable<number>` | Emits the upload completion percentage. | 
-| `downloadURL(): Observable<string>` | Emits the download url when available |
+| method   |                    |
+| ---------|--------------------|
+| `snapshotChanges(): Observable<FirebaseStorage.UploadTaskSnapshot>` | Emits the raw `UploadTaskSnapshot` as the file upload progresses. |
+| `percentageChanges(): Observable<number>` | Emits the upload completion percentage. |
+| `getDownloadURL(): Observable<any>` | Emits the download url when available |
 
 #### Example Usage
 
+The method `getDownloadURL()` doesn't rely on the task anymore, hence, in order to get the url we should use the finalize method from RxJS on top of the storage ref.
+
 ```ts
+import { finalize } from 'rxjs/operators';
+
 @Component({
   selector: 'app-root',
   template: `
@@ -101,12 +154,16 @@ export class AppComponent {
   uploadFile(event) {
     const file = event.target.files[0];
     const filePath = 'name-your-file-path-here';
+    const fileRef = this.storage.ref(filePath);
     const task = this.storage.upload(filePath, file);
-    
+
     // observe percentage changes
     this.uploadPercent = task.percentageChanges();
     // get notified when the download URL is available
-    this.downloadURL = task.downloadURL();
+    task.snapshotChanges().pipe(
+        finalize(() => this.downloadURL = fileRef.getDownloadURL() )
+     )
+    .subscribe()
   }
 }
 ```