From d5aece4f1c884eb2fbab9c4f78cafeff4c8ce26e Mon Sep 17 00:00:00 2001 From: EddyVerbruggen Date: Tue, 28 Nov 2017 11:24:30 +0100 Subject: [PATCH] Firestore anytime soon? #507 (doc) --- README.md | 2 +- demo-ng/app/item/items.component.ts | 18 +-- docs/DATABASE.md | 5 +- docs/FIRESTORE.md | 176 ++++++++++++++++++++++++++++ 4 files changed, 188 insertions(+), 13 deletions(-) create mode 100644 docs/FIRESTORE.md diff --git a/README.md b/README.md index 146cace4..8c661a33 100755 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ ## Features * [Realtime Database](docs/DATABASE.md) -* Firestore (work in progress) +* [Firestore](docs/FIRESTORE.md) * [Authentication](docs/AUTHENTICATION.md) * [Remote Config](docs/REMOTECONFIG.md) * [Cloud Messaging](docs/MESSAGING.md) diff --git a/demo-ng/app/item/items.component.ts b/demo-ng/app/item/items.component.ts index 82e06e42..1932ef52 100644 --- a/demo-ng/app/item/items.component.ts +++ b/demo-ng/app/item/items.component.ts @@ -42,9 +42,9 @@ export class ItemsComponent implements OnInit { // example from https://firebase.google.com/docs/firestore/query-data/get-data - const citiesRef = firebase.firestore().collection("cities"); + const citiesCollection = firebase.firestore().collection("cities"); - citiesRef.doc("SF").set({ + citiesCollection.doc("SF").set({ name: "San Francisco", state: "CA", country: "USA", @@ -52,7 +52,7 @@ export class ItemsComponent implements OnInit { population: 860000 }); - citiesRef.doc("LA").set({ + citiesCollection.doc("LA").set({ name: "Los Angeles", state: "CA", country: "USA", @@ -60,7 +60,7 @@ export class ItemsComponent implements OnInit { population: 3900000 }); - citiesRef.doc("SAC").set({ + citiesCollection.doc("SAC").set({ name: "Sacramento", state: "CA", country: "USA", @@ -68,7 +68,7 @@ export class ItemsComponent implements OnInit { population: 500000 }); - citiesRef.doc("DC").set({ + citiesCollection.doc("DC").set({ name: "Washington, D.C.", state: "WA", country: "USA", @@ -76,7 +76,7 @@ export class ItemsComponent implements OnInit { population: 680000 }); - citiesRef.doc("TOK").set({ + citiesCollection.doc("TOK").set({ name: "Tokyo", state: null, country: "Japan", @@ -84,7 +84,7 @@ export class ItemsComponent implements OnInit { population: 9000000 }); - citiesRef.doc("BJ").set({ + citiesCollection.doc("BJ").set({ name: "Beijing", state: null, country: "China", @@ -144,7 +144,7 @@ export class ItemsComponent implements OnInit { .get() .then((querySnapshot: firestore.QuerySnapshot) => { querySnapshot.forEach(doc => { - console.log(`Capital: ${doc.id} => ${JSON.stringify(doc.data())}`); + console.log(`Relatively small Californian city: ${doc.id} => ${JSON.stringify(doc.data())}`); }); }) .catch(err => console.log("Where-get failed, error" + err)); @@ -160,7 +160,7 @@ export class ItemsComponent implements OnInit { .get() .then((querySnapshot: firestore.QuerySnapshot) => { querySnapshot.forEach(doc => { - console.log(`${JSON.stringify(doc.data())}`); + console.log(`Large Californian city: ${doc.id} => ${JSON.stringify(doc.data())}`); }); }) .catch(err => console.log("firestoreWhereOrderLimit failed, error" + err)); diff --git a/docs/DATABASE.md b/docs/DATABASE.md index 4313422f..0140173e 100644 --- a/docs/DATABASE.md +++ b/docs/DATABASE.md @@ -4,7 +4,7 @@ If you can spare 41 seconds, check (an older version of) this plugin's [demo app [![YouTube demo, 41 sec](images/yt-thumb-database.png)](https://youtu.be/7zYU5e0Djkw "YouTube demo, 41 sec") ## Enabling the database features -Since this is the most likely feature you'll use with this plugin it has already been properly configured to interact with the database, so nothing to do here on top of the stuff in the main readme. +*Only* if you choose to use **Firestore** (instead of the default DB) these features won't be available. ## Functions @@ -32,8 +32,7 @@ You can optionally pass `persist` to the [`init` function](../README.md#init) to ### setValue -Data is stored as JSON data at a specific path (which is appended to the URL you passed to `init`). -If you want to add data to a known path use this, otherwise use `push` (see below). +Data is stored as JSON data at a specific path. If you want to add data to a known path use this, otherwise use `push` (see below). The plugin will take care of serializing JSON data to native data structures. diff --git a/docs/FIRESTORE.md b/docs/FIRESTORE.md new file mode 100644 index 00000000..9d98c9b7 --- /dev/null +++ b/docs/FIRESTORE.md @@ -0,0 +1,176 @@ +Cloud Firestore + +## Enabling the database features +During plugin installation you'll be prompted to use either Firestore or the default DB. + +In case you're upgrading and you have the `firebase.nativescript.json` file in your project root, +you can edit it and add: `"firestore": true`. Then do `rm -rf platforms/ios && rm -rf platforms/android && rm -rf node_modules && npm i`. + +## Functions +All of these are 100% compatible with the Firestore Web API to make it easy to share code between web and native, and you can +refer to the [Firestore web api docs](https://firebase.google.com/docs/firestore/data-model) (make sure to look at the 'WEB' tab of those code samples). + +> The plugin will take care of serializing JSON data to and from native data structures. + +### `init` / `initializeApp` +By default Firestore on iOS and Android persists data locally for offline usage (web doesn't by default, and the regular Firebase DB doesn't either on any platform). +If you don't like that awesome feature, you can pass `persist: false` to the [`init` function](../README.md#init). + +> Note that `initializeApp` is simply an alias for `init` to make the plugin compatible with the web API. + +```typescript +const firebase = require("nativescript-plugin-firebase/app"); + +firebase.initializeApp({ + persist: false +}); +``` + +### `collection` +A 'collection' is at the root of any Firestore interaction. Data is stored as 'documents' in a 'collection'. + +```typescript +const citiesCollection = firebase.firestore().collection("cities"); +``` + +### `collection.get()` +To get all documents inside a collection: + +```typescript +const citiesCollection = firebase.firestore().collection("cities"); + +citiesCollection.get().then(querySnapshot => { + querySnapshot.forEach(doc => { + console.log(`${doc.id} => ${JSON.stringify(doc.data())}`); + }); +}); +``` + +### `collection.doc()` +A 'document' lives inside a 'collection' and contains the actual data: + +```typescript +const sanFranciscoDocument = firebase.firestore().collection("cities").doc("SF"); +``` + +### `collection.doc().get()` +To get the data inside a document: + +```typescript +const sanFranciscoDocument = firebase.firestore().collection("cities").doc("SF"); + +sanFranciscoDocument.get().then(doc => { + if (doc.exists) { + console.log("Document data:", JSON.stringify(doc.data())); + } else { + console.log("No such document!"); + } +}); +``` + +### `collection.add()` +If you want to add a document with an auto-generated ID, use `add` on a *collection*: + +```typescript +const citiesCollection = firebase.firestore().collection("cities"); + +citiesCollection.add({ + name: "San Francisco", + state: "CA", + country: "USA", + capital: false, + population: 860000 +}).then(documentRef => { + console.log("San Francisco added with auto-generated ID: " + documentRef.id); +}); +``` + +### `collection.doc().set()` +If you want to specify an ID yourself, use `set` on a *document*: + +```typescript +const citiesCollection = firebase.firestore().collection("cities"); + +citiesCollection.doc("SF").set({ + name: "San Francisco", + state: "CA", + country: "USA", + capital: false, + population: 860000 +}); + +citiesCollection.doc("LA").set({ + name: "Los Angeles", + state: "CA", + country: "USA", + capital: false, + population: 3900000 +}); +``` + +### `collection.doc().update()` +Update any number of properties of a document: + +```typescript +const sanFranciscoDocument = firebase.firestore().collection("cities").doc("SF"); + +sanFranciscoDocument.update({ + population: 860001 +}).then(() => { + console.log("SF population updated"); +}); +``` + +### `collection.doc().delete()` +Entirely remove a document from a collection: + +```typescript +const sanFranciscoDocument = firebase.firestore().collection("cities").doc("SF"); + +sanFranciscoDocument.delete().then(() => { + console.log("SF was erased from the face of the earth!"); +}); +``` + +### `collection.where()` +Firestore supports advanced querying with the `where` function. Those `where` clauses can be chained to form logical 'AND' queries: + +```typescript +const citiesCollection = firebase.firestore().collection("cities"); + +// "Gimme all cities in California with a population below 550000" +const query = citiesCollection + .where("state", "==", "CA") + .where("population", "<", 550000); + +query + .get() + .then(querySnapshot => { + querySnapshot.forEach(doc => { + console.log(`Relatively small Californian city: ${doc.id} => ${JSON.stringify(doc.data())}`); + }); + }); +``` + +### Ordering and limiting results of `collection.where()` +Return data sorted (asc or desc), or limit to a certain number of results: + +```typescript +const citiesCollection = firebase.firestore().collection("cities"); + +// "Gimme the two largest cities in California, the largest first please" +const query = citiesCollection + .where("state", "==", "CA") + .orderBy("population", "desc") + .limit(2); + +query + .get() + .then(querySnapshot => { + querySnapshot.forEach(doc => { + console.log(`Large Californian city: ${doc.id} => ${JSON.stringify(doc.data())}`); + }); + }); +``` + +> Need something that's not supported yet? Please open an Issue or PR 😚 \ No newline at end of file