docs(afs): AngularFire docs and more (angular#2)

* docs(db): updating the querying docs for the new API (angular#1170)

* docs(db): updating the querying docs for the new API

* docs(db): cleanup some of the formatting

* docs(db): kill unneeded quote character

* docs(db): adding a clear filter + show all results first

* docs(db): allow null in the filterBy example

* docs(readme): Callout 5.0 docs

* docs(): Update Auth-with-Ionic3-Augular4.md (angular#1171)

Fix promise-polyfill instruction and make tutorial less verbose

* Rearranging the docs a bit

* Fixes

* Moved Ionic CLI

* AngularFireDatabase/store headers

* Rearrange docs and lists

* Split querying collections into its own doc

* Databases as h4 and getting started with auth

* Right auth link

* Add a choose a database header

* Reformatting that a bit more

* Rarranged those, change header numbers

* Fixing syntax and app-root issues

* Cleaner

* Drop the 5.0@next note and 2 from more AF2 refs

* Removing the meta section from RTDB

* Querying example and doc titles

* Revamp firestore dynamic querying

* Adding an offline data doc

* Small language / typos

* Type

Author: jamesdaniels

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to AngularFire2
+# Contributing to AngularFire
 
-We would love for you to contribute to AngularFire2 and help make it even better than it is
+We would love for you to contribute to AngularFire and help make it even better than it is
 today! As a contributor, here are the guidelines we would like you to follow:
 
  - [Code of Conduct](#coc)
@@ -50,7 +50,7 @@ and help you to craft the change so that it is successfully accepted into the pr
 
 ## <a name="setup"></a> Initial Setup
 
-1) Create a fork of AngularFire2 (See [Forking a Project][github-fork])
+1) Create a fork of AngularFire (See [Forking a Project][github-fork])
 
 2) CD into your clone and install dependencies
 

README.md

@@ -36,7 +36,7 @@ import { AngularFirestore } from 'angularfire2/firestore';
 import { Observable } from 'rxjs/Observable';
 
 @Component({
-  selector: 'project-name-app',
+  selector: 'app-root',
   template: `
   <ul>
     <li *ngFor="let item of items | async">
@@ -56,23 +56,40 @@ export class MyApp {
 ## Developer Guide
 
 ### Getting started
+
 - [Installation & Setup](docs/1-install-and-setup.md)
 
-### AngularFirestore
-- [Using collections](docs/firestore/collections.md)
-- [Using documents](docs/firestore/documents.md)
+### Interacting with your database(s)
+
+Firebase offers two cloud-based, client-accessible database solutions that support realtime data syncing. [Learn about the differences between them in the Firebase Documentation](https://firebase.google.com/docs/firestore/rtdb-vs-firestore).
+
+#### Cloud Firestore
+
+> `AngularFirestore` allows you to work with Cloud Firestore, the new flagship database for mobile app development. It improves on the successes of Realtime Database with a new, more intuitive data model. Cloud Firestore also features richer, faster queries and scales better than Realtime Database.
+
+- [Documents](docs/firestore/documents.md)
+- [Collections](docs/firestore/collections.md)
+- [Querying Collections](docs/firestore/querying-collections.md)
+- [Offline data](docs/firestore/offline-data.md)
 
-### AngularFireAuth
-- [User Authentication](docs/5-user-authentication.md)
+#### Realtime Database
 
-### AngularFireDatabase
-- [Retrieving data as objects](docs/2-retrieving-data-as-objects.md)
-- [Retrieving data as lists](docs/3-retrieving-data-as-lists.md)
-- [Querying lists](docs/4-querying-lists.md)
+> `AngularFireDatabase` allows you to work with the Realtime Database, Firebase's original database. It's an efficient, low-latency solution for mobile apps that require synced states across clients in realtime.
+
+- [Objects](docs/rtdb/objects.md)
+- [Lists](docs/rtdb/lists.md)
+- [Querying lists](docs/rtdb/querying-lists.md)
+
+### Authenticate users
+
+- [Getting started with Firebase Authentication](docs/auth/getting-started.md)
 
 ### Deploy to Firebase Hosting
-- [Deploying AngularFire to Firebase Hosting](docs/7-deploying-angularfire-to-firebase.md)
+
+- [Deploying AngularFire to Firebase Hosting](docs/deploying-angularfire-to-firebase.md)
 
 ### Ionic
-- [Using AngularFire with Ionic 2](docs/Auth-with-Ionic2.md)
-- [Using AngularFire with Ionic 3 and Angular 4](docs/Auth-with-Ionic3-Angular4.md)
+
+- [Installation and Setup with Ionic CLI](docs/ionic/cli.md)
+- [Using AngularFire with Ionic 2](docs/ionic/v2.md)
+- [Using AngularFire with Ionic 3](docs/ionic/v3.md)

docs/5-user-authentication.md docs/auth/getting-started.mddocs/5-user-authentication.md renamed to docs/auth/getting-started.md

@@ -1,4 +1,4 @@
-# 5. User authentication
+# 5. Getting started with Firebase Authentication
 
 `AngularFireAuth.authState` provides you an `Observable<firebase.User>` to monitor your application's authentication State.
 

…s/7-deploying-angularfire-to-firebase.md docs/deploying-angularfire-to-firebase.mddocs/7-deploying-angularfire-to-firebase.md renamed to docs/deploying-angularfire-to-firebase.md docs/7-deploying-angularfire-to-firebase.md renamed to docs/deploying-angularfire-to-firebase.md

@@ -1,4 +1,4 @@
-# 7. Deploy AngularFire2 to Firebase
+# 7. Deploy AngularFire to Firebase
 
 ### 0. Build your Angular project for prod
 

docs/firestore/collections.md

@@ -1,33 +1,33 @@
-# Using Collections with AngularFirestore
+# 3. Collections in AngularFirestore
 
-## Understanding Collections
-Every Firestore application starts with a collection. Firestore is structured in a `Collection > Document > Collection > Document` manner. This provides you with a flexible data structure. When you query a collection you only pull back the documents and not their collections. This is different from the Firebase Realtime Database where a query at a top-level location pulls back the entire tree. No more worrying about pulling back all the way down the tree 😎.
+> Cloud Firestore is a NoSQL, document-oriented database. Unlike a SQL database, there are no tables or rows. Instead, you store data in *documents*, which are organized into *collections*.
+Each *document* contains a set of key-value pairs. Cloud Firestore is optimized for storing large collections of small documents.
 
-## Using an AngularFirestoreCollection
+## Using `AngularFirestoreCollection`
 
-The `AngularFirestoreCollection` service is a wrapper around the native Firestore SDK's `CollectionReference` and `Query` types. It is a generic service that provides you with a strongly typed set of methods for manipulating and streaming data. This service is designed for use as an `@Injectable()`.
+The `AngularFirestoreCollection` service is a wrapper around the native Firestore SDK's [`CollectionReference`](https://firebase.google.com/docs/reference/js/firebase.firestore.CollectionReference) and [`Query`](https://firebase.google.com/docs/reference/js/firebase.firestore.Query) types. It is a generic service that provides you with a strongly typed set of methods for manipulating and streaming data. This service is designed for use as an `@Injectable()`.
 
 ```ts
 import { Component } from '@angular/core';
 import { AngularFirestore, AngularFirestoreCollection } from 'angularfire2/firestore';
 import { Observable } from 'rxjs/Observable';
 
 @Component({
-  selector: 'afs-app',
+  selector: 'app-root',
   template: `
     <ul>
-      <li *ngFor="item of items | async">
+      <li *ngFor="let item of items | async">
         {{ item.name }}
       </li>
     </ul>
   `
 })
 export class AppComponent {
-  private itemsCollection: AngularFirestoreCollection<Item>: 
+  private itemsCollection: AngularFirestoreCollection<Item>;
   items: Observable<Item[]>;
-  constructor(private afs: AngularFirestore): {
+  constructor(private afs: AngularFirestore) {
     this.itemsCollection = afs.collection<Item>('items');
-    this.items = this.itemsCollection.snapshotChanges(['added', 'removed']);
+    this.items = this.itemsCollection.valueChanges();
   }
   addItem(item: Item) {
     this.itemsCollection.add(item);
@@ -118,93 +118,25 @@ import { AngularFirestore, AngularFirestoreCollection } from 'angularfire2/fires
 import { Observable } from 'rxjs/Observable';
 
 @Component({
-  selector: 'afs-app',
+  selector: 'app-root',
   template: `
     <ul>
-      <li *ngFor="item of items | async">
+      <li *ngFor="let item of items | async">
         {{ item.name }}
       </li>
     </ul>
   `
 })
 export class AppComponent {
-  private itemsCollection: AngularFirestoreCollection<Item>: 
+  private itemsCollection: AngularFirestoreCollection<Item>;
   items: Observable<Item[]>;
-  constructor(private afs: AngularFirestore): {
+  constructor(private afs: AngularFirestore) {
     this.itemsCollection = afs.collection<Item>('items');
-    this.items = this.itemsCollection.snapshotChanges(['added', 'removed']);
+    this.items = this.itemsCollection.valueChanges();
   }
 }
 ```
 
-### Querying
-
-Firestore has powerful querying syntax and the `AngularFirestoreCollection` provides a thin wrapper around it. This keeps you from having to learn two query syntax systems. If you know the Firestore query API then you know it for AngularFirestore ‼
-
-When creating an `AngularFirestoreCollection`, use the optional callback to create a queried reference.
-
-#### Basic Sample
-```ts
-  constructor(private afs: AngularFirestore): {
-    this.itemsCollection = afs.collection<Item>('items', ref => ref.where('size', '==', 'large'));
-    this.items = this.itemsCollection.snapshotChanges();
-  }
-```
-
-#### Component Sample
-```ts
-import { Component } from '@angular/core';
-import { AngularFirestore, AngularFirestoreCollection } from 'angularfire2/firestore';
-import { Observable } from 'rxjs/Observable';
-
-@Component({
-  selector: 'afs-app',
-  template: `
-    <ul>
-      <li *ngFor="item of items | async">
-        {{ item.name }}
-      </li>
-    </ul>
-  `
-})
-export class AppComponent {
-  private itemsCollection: AngularFirestoreCollection<Item>: 
-  items: Observable<Item[]>;
-  constructor(private afs: AngularFirestore): {
-    this.itemsCollection = afs.collection<Item>('items', ref => {
-      return ref.where('size', '==', 'large').where('price', '>', 10);
-    });
-    this.items = this.itemsCollection.snapshotChanges(['added', 'removed']);
-  }
-}
-```
-
-### Dynamic querying
-
-Imagine you're querying a list of T-Shirts. Every facet of the query should be parameterized. Sometimes the user will search small sizes, prices less than $20, or by a specific brand. AngularFirestore intergrates with RxJS to make this easy.
-
-#### Basic Sample
-```ts
-  constructor(private afs: AngularFirestore): {
-    // import { of } from 'rxjs/observable/of;
-    // You'll use an Observable source from a ReactiveForm control or even
-    // an AngularFirestoreDocument
-    const criteria$ = of({ 
-      size: 'large', 
-      price: 10
-    });
-    this.items = criteria$.switchMap(criteria => {
-      return this.afs
-        .collection<Item>('tshirts', ref => {
-          return ref
-                  .where('size', '==', criteria.size)
-                  .where('price', '>', criteria.price)
-        })
-        .snapshotChanges();
-    });
-  }
-```
-
 ## Adding documents to a collection
 
 To add a new document to a collection with a generated id use the `add()` method. This method uses the type provided by the generic class to validate it's type structure.
@@ -219,6 +151,6 @@ To add a new document to a collection with a generated id use the `add()` method
 
 ## Manipulating individual documents
 
-To retrieve, update, or delete an individual document you can use the `doc()` method. This method returns an `AngularFirestoreDocument`, which provides methods for streaming, updating, and deleting. 
+To retrieve, update, or delete an individual document you can use the `doc()` method. This method returns an `AngularFirestoreDocument`, which provides methods for streaming, updating, and deleting. [See Using Documents with AngularFirestore for more information on how to use documents](documents.md).
 
-See the [Documents page for complete documentation]((docs/firestore/documents.md).
+### [Next Step: Querying Collections in AngularFirestore](querying-collections.md)

docs/firestore/documents.md

@@ -1,30 +1,29 @@
-# Using Documents with Firestore
+# 2. Documents in AngularFirestore
 
-## Understanding Documents
+> Cloud Firestore is a NoSQL, document-oriented database. Unlike a SQL database, there are no tables or rows. Instead, you store data in *documents*, which are organized into *collections*.
+Each *document* contains a set of key-value pairs. Cloud Firestore is optimized for storing large collections of small documents.
 
-A Document is apart of a Collection. Firestore follows a `Collection > Document > Collection > Document` structure. Collections nested under a Document are not retrieved with a Document. You must explicitly retrieve the Collection underneath that path. This gives you a much more flexible structure. Gone are the days of worrying about pulling back the whole tree.
+## Using `AngularFirestoreDocument`
 
-## Using an AngularFirestoreDocument
-
-The `AngularFirestoreDocument` service is a wrapper around the native Firestore SDK's `DocumentReference` type. It is a generic service that provides you with a strongly typed set of methods for manipulating and streaming data. This service is designed for use as an `@Injectable()`.
+The `AngularFirestoreDocument` service is a wrapper around the native Firestore SDK's [`DocumentReference` type](https://firebase.google.com/docs/reference/js/firebase.firestore.DocumentReference). It is a generic service that provides you with a strongly typed set of methods for manipulating and streaming data. This service is designed for use as an `@Injectable()`.
 
 ```ts
 import { Component } from '@angular/core';
 import { AngularFirestore, AngularFirestoreDocument } from 'angularfire2/firestore';
 import { Observable } from 'rxjs/Observable';
 
 @Component({
-  selector: 'afs-app',
+  selector: 'app-root',
   template: `
     <div>
       {{ (item | async)?.name }}
     </div>
   `
 })
 export class AppComponent {
-  private itemDoc: AngularFirestoreDocument<Item>: 
+  private itemDoc: AngularFirestoreDocument<Item>;
   item: Observable<Item>;
-  constructor(private afs: AngularFirestore): {
+  constructor(private afs: AngularFirestore) {
     this.itemDoc = afs.doc<Item>('items/1');
     this.item = this.itemDoc.valueChanges();
   }
@@ -101,10 +100,10 @@ Nesting collections is a great way to structure your data. This allows you to gr
 To retrieve a nested collection use the `collection(path: string)` method.
 
 ```ts
-  constructor(private afs: AngularFirestore): {
+  constructor(private afs: AngularFirestore) {
     this.userDoc = afs.doc<Item>('user/david');
     this.tasks = this.userDoc.collection<Task>('tasks').valueChanges();
   }
 ```
 
-For more information about using collections read the [collection documentation](docs/firestore/collection.md).
+### [Next Step: Collections in AngularFirestore](collections.md)

docs/firestore/ngrx.md

@@ -0,0 +1,37 @@
+# Offline Data in Firestore
+
+> Cloud Firestore supports offline data persistence. This feature caches a copy of the Cloud Firestore data that your app is actively using, so your app can access the data when the device is offline. You can write, read, listen to, and query the cached data. When the device comes back online, Cloud Firestore synchronizes any local changes made by your app to the data stored remotely in Cloud Firestore.
+
+**Offline persistence is an experimental feature that is supported only by the Chrome, Safari, and Firefox web browsers.** If a user opens multiple browser tabs that point to the same Cloud Firestore database, and offline persistence is enabled, Cloud Firestore will work correctly only in the first tab.
+
+## Enable Offline Data in AngularFirestore
+
+To enable offline persistence in your AngularFire application, call `enablePersistence()` when you are importing `AngularFirestoreModule` into your `@NgModule`:
+
+```ts
+import { BrowserModule } from '@angular/platform-browser';
+import { NgModule } from '@angular/core';
+import { AppComponent } from './app.component';
+import { AngularFireModule } from 'angularfire2';
+import { AngularFirestoreModule } from 'angularfire2/firestore';
+import { AngularFireAuthModule } from 'angularfire2/auth';
+import { environment } from '../environments/environment';
+
+@NgModule({
+  imports: [
+    BrowserModule,
+    AngularFireModule.initializeApp(environment.firebase),
+    AngularFirestoreModule.enablePersistence(),
+  ],
+  declarations: [ AppComponent ],
+  bootstrap: [ AppComponent ]
+})
+export class AppModule {}
+
+```
+
+While offline your listeners will receive listen events when the locally cached data changes. You can use to Documents and Collections normally.
+
+To check whether you're receiving data from the server or the cache, use the `fromCache` property on the `SnapshotMetadata` in your snapshot event. If `fromCache` is true, the data came from the cache and might be stale or incomplete. If `fromCache` is false, the data is complete and current with the latest updates on the server.
+
+[To learn more about Offline Persistence in Firestore, check out the Firebase documentation](https://firebase.google.com/docs/firestore/enable-offline).