You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
VueFire expects you to use the existing APIs from Firebase as much as possible. It doesn't expose any configs to initialize your app or get the database/firestore instances. You should follow the official Firebase documentation for that. We do have [some recommendations](#TODO) for a Vue project and [a Nuxt module](#TODO) to help you get started.
24
24
25
-
Most of the time, you should gather collection references in one of your files and export them but to keep examples short, we will always create the database references whenever necessary. We will also consider that we have access to some globals (you usually import them from the file where you initialize your Firebase app):
25
+
Most of the time, you should gather collection references in one of your files and export them but **to keep examples short, we will always create the database references whenever necessary** instead of gathering them in one place. We will also consider that we have access to some globals (you usually import them from the file where you initialize your Firebase app):
@@ -45,7 +46,9 @@ Note that we will refer to `database` and `firestore` as `db` in examples where
45
46
46
47
VueFire exposes a few [composables](https://vuejs.org/guide/reusability/composables.html#composables) to create reactive variables from Firebase references.
47
48
48
-
You can retrieve a reactive collection or list:
49
+
#### Collections/Lists
50
+
51
+
You can retrieve a reactive collection (Firestore) or list (Realtime Database) with the `useCollection()`/`useList()` composable:
49
52
50
53
<FirebaseExample>
51
54
@@ -85,9 +88,16 @@ const todos = useCollection(collection(db, 'todos'))
85
88
86
89
</FirebaseExample>
87
90
88
-
In both scenarios, `todos` will be a `ref()` of an array. You can use it as a readonly array, but it will be automatically updated when the data changes anywhere.
91
+
In both scenarios, `todos` will be a `ref()` of an array. Note **this is a readonly array**, but it will be automatically updated when the data changes anywhere.
92
+
93
+
If you want to change the data, you should use the Firebase API (e.g. `addDoc()`, `updateDoc()`, `push()` etc) to update the data:
In both scenarios, `settings` becomes a reactive object. Note **this is a readonly object**, but it will be automatically updated when the data changes anywhere.
125
+
126
+
If you want to change the data, you should use the Firebase API (e.g. `setDoc()`, `updateDoc()`, `set()` etc) to update the data:
TODO: complete this section. The composition API is the recommended way to use VueFire at the moment because its API is more stable and it's easier to use with TypeScript.
134
+
116
135
VueFire can also be used with the Options API, while less flexible, it's still a valid way to use VueFire. First, you need to install the options plugin:
117
136
118
137
- Install `firestorePlugin` to use _Firestore_
@@ -137,3 +156,7 @@ app.use(firestorePlugin)
137
156
```
138
157
139
158
</FirebaseExample>
159
+
160
+
### Which API should I use?
161
+
162
+
The composition API is the recommended way to use VueFire. At the moment its API is more stable and it's easier to use with TypeScript. However, the Options API is still a valid way to use VueFire. The main difference is that the Options API is more verbose and requires you to install the plugin, also being slightly heavier than the composables.
Copy file name to clipboardExpand all lines: docs/guide/old__binding-subscriptions.md
+13-13
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,13 @@
1
-
# Binding / Subscribing to changes
1
+
# Subscribing to firebase data changes
2
2
3
-
In Vuefire, subscriptions to changes are handled transparently. That's why we always talk about _binding_: you only provide the key of the state where to bind, and the _Source_(Collection, Query or Document), and Vuefire takes care of the rest!
3
+
In VueFire, subscriptions to data changes are handled transparently. That's why we always talk about _binding_: you only provide the _data source_(Collection, Query or Document), and VueFire takes care of the rest!
4
4
5
-
There are two ways of binding a Reference to the Database with Vuefire:
5
+
There are two ways of binding a Reference to the Database with VueFire:
6
6
7
7
- Declarative binding with the `firebase`/`firestore` option
8
8
- Programmatic binding with the injected methods `$rtdbBind`/`$firestoreBind`
9
9
10
-
Once a Reference is bound, Vuefire will keep the local version synchronized with the remote Database. However, this synchronisation **is only one-way**. Do not modify the local variable (e.g. doing `this.user.name = 'John'`), because (a) it will not change the remote Database and (b) it can be overwritten at any time by Vuefire. To [write changes to the Database](./writing-data.md), use the Firebase JS SDK.
10
+
Once a Reference is bound, VueFire will keep the local version synchronized with the remote Database. However, this synchronisation **is only one-way**. Do not modify the local variable (e.g. doing `this.user.name = 'John'`), because (a) it will not change the remote Database and (b) it can be overwritten at any time by VueFire. To [write changes to the Database](./writing-data.md), use the Firebase JS SDK.
Any document bound by Vuefire will retain it's _id_ in the Database as a non-enumerable, read-only property. This makes it easier to [write changes](./writing-data.md#updates-to-collection-and-documents) and allows you to copy the data only using the [spread operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax#Spread_in_object_literals) or [`Object.assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign).
156
+
Any document bound by VueFire will retain it's _id_ in the Database as a non-enumerable, read-only property. This makes it easier to [write changes](./writing-data.md#updates-to-collection-and-documents) and allows you to copy the data only using the [spread operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax#Spread_in_object_literals) or [`Object.assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign).
In Firestore you can store [Geopoints](https://firebase.google.com/docs/reference/js/firebase.firestore.GeoPoint). They are retrieved as-is by Vuefire, meaning that you can directly use methods like `isEqual` and access its properties `latitude` and `longitude`.
186
+
In Firestore you can store [Geopoints](https://firebase.google.com/docs/reference/js/firebase.firestore.GeoPoint). They are retrieved as-is by VueFire, meaning that you can directly use methods like `isEqual` and access its properties `latitude` and `longitude`.
187
187
188
188
> Refer to [Plugin installation](./getting-started.md#plugin) to retrieve the `Geopoint` class
In Firestore you can store [Timestamps](https://firebase.google.com/docs/reference/js/firebase.firestore.Timestamp). They are stored as-is by Vuefire, meaning that you can directly use methods like `isEqual`, `toDate` and access its properties `seconds` and `nanoseconds`.
219
+
In Firestore you can store [Timestamps](https://firebase.google.com/docs/reference/js/firebase.firestore.Timestamp). They are stored as-is by VueFire, meaning that you can directly use methods like `isEqual`, `toDate` and access its properties `seconds` and `nanoseconds`.
220
220
221
221
> Refer to [Plugin installation](./getting-started.md#plugin) to retrieve the `Timestamp` class
In Firestore you can store [References](https://firebase.google.com/docs/reference/js/firebase.firestore.DocumentReference) to other Documents in Documents. Vuefire automatically bind References found in Collections and documents. This also works for nested references (References found in bound References). By default, Vuefire will stop at that level (2 level nesting).
253
+
In Firestore you can store [References](https://firebase.google.com/docs/reference/js/firebase.firestore.DocumentReference) to other Documents in Documents. VueFire automatically bind References found in Collections and documents. This also works for nested references (References found in bound References). By default, VueFire will stop at that level (2 level nesting).
254
254
255
255
Given some _users_ with _documents_ that are being viewed by other _users_. This could be **users/1**:
256
256
@@ -275,7 +275,7 @@ Given some _users_ with _documents_ that are being viewed by other _users_. This
275
275
}
276
276
```
277
277
278
-
`sharedWith` is also an array of References, but those references are users. Users also contain references to documents, therefore, if we automatically bind every nested reference, we could end up with an infinite-memory-consumming binding. By default, if we bind `users/1` with Vuefire, this is what we end up having:
278
+
`sharedWith` is also an array of References, but those references are users. Users also contain references to documents, therefore, if we automatically bind every nested reference, we could end up with an infinite-memory-consumming binding. By default, if we bind `users/1` with VueFire, this is what we end up having:
279
279
280
280
```js
281
281
{
@@ -303,7 +303,7 @@ Given some _users_ with _documents_ that are being viewed by other _users_. This
303
303
}
304
304
```
305
305
306
-
`documents.sharedWith.documents` end up as arrays of strings. Those strings can be passed to `db.doc()` as in `db.doc('documents/robin-book')` to get the actual reference to the document. By being a string instead of a Reference, it is possibe to display a bound document with Vuefire as plain text.
306
+
`documents.sharedWith.documents` end up as arrays of strings. Those strings can be passed to `db.doc()` as in `db.doc('documents/robin-book')` to get the actual reference to the document. By being a string instead of a Reference, it is possibe to display a bound document with VueFire as plain text.
307
307
308
308
It is possible to customize this behaviour by providing a [`maxRefDepth` option](#TODO:) when invoking `$firestoreBind`:
309
309
@@ -316,7 +316,7 @@ Read more about [writing References to the Database](./writing-data.md#reference
316
316
317
317
## Unbinding / Unsubscribing to changes
318
318
319
-
While Vuefire will automatically unbind any reference bound in a component whenever needed, you may still want to do it on your own to stop displaying updates on a document or collection or because the user logged out and they do not have read-access to a resource anymore.
319
+
While VueFire will automatically unbind any reference bound in a component whenever needed, you may still want to do it on your own to stop displaying updates on a document or collection or because the user logged out and they do not have read-access to a resource anymore.
0 commit comments