Skip to content
This repository was archived by the owner on Apr 4, 2023. It is now read-only.

Commit 82e99b9

Browse files
EddyVerbruggenEddyVerbruggen
committed
Docs++
1 parent 4a4f44a commit 82e99b9

File tree

8 files changed

+457
-418
lines changed

8 files changed

+457
-418
lines changed

‎README.md‎

Lines changed: 30 additions & 418 deletions
Large diffs are not rendered by default.

‎docs/AUTHENTICATION.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
<table>
2+
<tr style="border:none">
3+
<td style="border:none; padding:0"><img src="images/firebase.png" width="154px" height="43px" alt="Firebase"/></td>
4+
<td style="border:none; padding:4">Authentication</td>
5+
</tr>
6+
</table>
7+
8+
## Enabling Authentication
9+
Version 1.1.0 of this plugin added the capability to log your users in, either
10+
11+
* anonymously,
12+
* by email and password,
13+
* using a custom token,
14+
* using Facebook (iOS: solid, Android: experimental).
15+
16+
Each of these login mechanisms need to be enabled in your Firebase console at the 'Login & Auth' tab.
17+
18+
## Functions
19+
20+
### Listening to auth state changes
21+
As stated [here](https://firebase.google.com/docs/auth/ios/manage-users#get_the_currently_signed-in_user):
22+
23+
> The recommended way to get the current user is by setting a listener on the Auth object
24+
25+
To listen to auth state changes you can register a listener during `init`:
26+
27+
```js
28+
firebase.init({
29+
onAuthStateChanged: function(data) { // optional but useful to immediately re-logon the user when he re-visits your app
30+
console.log(data.loggedIn ? "Logged in to firebase" : "Logged out from firebase");
31+
if (data.loggedIn) {
32+
console.log("user's email address: " + (data.user.email ? data.user.email : "N/A"));
33+
}
34+
}
35+
});
36+
```
37+
38+
If - for some reason - you want more control over the listener you can use these methods after you ran `init`:
39+
40+
```js
41+
// configure a listener:
42+
var listener = {
43+
onAuthStateChanged: function(data) {
44+
console.log(data.loggedIn ? "Logged in to firebase" : "Logged out from firebase");
45+
if (data.loggedIn) {
46+
console.log("User info", data.user);
47+
}
48+
},
49+
thisArg: this
50+
};
51+
52+
// add the listener:
53+
firebase.addAuthStateListener(listener);
54+
55+
// stop listening to auth state changes:
56+
firebase.removeAuthStateListener(listener);
57+
58+
// check if already listening to auth state changes
59+
firebase.hasAuthStateListener(listener);
60+
```
61+
62+
63+
### Anonymous login
64+
Don't forget to enable anonymous login in your firebase instance.
65+
66+
```js
67+
firebase.login({
68+
type: firebase.LoginType.ANONYMOUS
69+
}).then(
70+
function (result) {
71+
// the result object has these properties: uid, provider, expiresAtUnixEpochSeconds, profileImageURL, token
72+
JSON.stringify(result);
73+
},
74+
function (errorMessage) {
75+
console.log(errorMessage);
76+
}
77+
)
78+
```
79+
80+
### Email-Password login
81+
Don't forget to enable email-password login in your firebase instance.
82+
83+
```js
84+
firebase.login({
85+
type: firebase.LoginType.PASSWORD,
86+
email: '[email protected]',
87+
password: 'theirpassword'
88+
}).then(
89+
function (result) {
90+
// the result object has these properties: uid, provider, expiresAtUnixEpochSeconds, profileImageURL, token
91+
JSON.stringify(result);
92+
},
93+
function (errorMessage) {
94+
console.log(errorMessage);
95+
}
96+
)
97+
```
98+
99+
#### Managing email-password accounts
100+
##### Creating a Password account
101+
```js
102+
firebase.createUser({
103+
email: '[email protected]',
104+
password: 'firebase'
105+
}).then(
106+
function (result) {
107+
dialogs.alert({
108+
title: "User created",
109+
message: "userid: " + result.key,
110+
okButtonText: "Nice!"
111+
})
112+
},
113+
function (errorMessage) {
114+
dialogs.alert({
115+
title: "No user created",
116+
message: errorMessage,
117+
okButtonText: "OK, got it"
118+
})
119+
}
120+
)
121+
```
122+
123+
#### Resetting a password
124+
```js
125+
firebase.resetPassword({
126+
email: '[email protected]'
127+
}).then(
128+
function () {
129+
// called when password reset was successful,
130+
// you could now prompt the user to check his email
131+
},
132+
function (errorMessage) {
133+
console.log(errorMessage);
134+
}
135+
)
136+
```
137+
138+
#### Changing a password
139+
```js
140+
firebase.changePassword({
141+
email: '[email protected]',
142+
oldPassword: 'myOldPassword',
143+
newPassword: 'myNewPassword'
144+
}).then(
145+
function () {
146+
// called when password change was successful
147+
},
148+
function (errorMessage) {
149+
console.log(errorMessage);
150+
}
151+
)
152+
```
153+
154+
### Custom login
155+
Use this login type to authenticate against firebase using a token generated by your own backend server. See these [instructions on how to generate the authentication token](https://firebase.google.com/docs/auth/server).
156+
157+
```js
158+
var token = "myBackendToken";
159+
160+
firebase.login({
161+
type: firebase.LoginType.CUSTOM,
162+
token: token
163+
}).then(
164+
function (result) {
165+
// the result object has these properties: uid, provider, expiresAtUnixEpochSeconds, profileImageURL, token
166+
JSON.stringify(result);
167+
},
168+
function (errorMessage) {
169+
console.log(errorMessage);
170+
}
171+
)
172+
```
173+
174+
### Facebook login
175+
On iOS this is rock solid, but on Android it's work in progress. If you want to use it for iOS open the `Podfile` in the plugin's `platforms/ios` folder and uncomment the Facebook line (you can't miss it).
176+
177+
Don't forget to enable Facebook login in your firebase instance.
178+
179+
```js
180+
firebase.login({
181+
type: firebase.LoginType.FACEBOOK
182+
}).then(
183+
function (result) {
184+
JSON.stringify(result);
185+
},
186+
function (errorMessage) {
187+
console.log(errorMessage);
188+
}
189+
)
190+
```
191+
192+
And also, add [this bit to `app.js`](https://github.com/EddyVerbruggen/nativescript-plugin-firebase-demo/blob/master/Firebase/app/app.js#L5-L34) to give control back to your app after Facebook's auth UI finished.
193+
194+
195+
### logout
196+
Shouldn't be more complicated than:
197+
198+
```js
199+
firebase.logout();
200+
```
201+
202+

‎docs/DATABASE.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
<table>
2+
<tr style="border:none">
3+
<td style="border:none; padding:0"><img src="images/firebase.png" width="154px" height="43px" alt="Firebase"/></td>
4+
<td style="border:none; padding:4">Database</td>
5+
</tr>
6+
</table>
7+
8+
## Enabling the database features
9+
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.
10+
11+
## Functions
12+
13+
### init
14+
Optionally you can pass `persist` to the `init` function to make Firebase save data to the local disc so it will work in offline scenario's. Defaul false.
15+
16+
```js
17+
var firebase = require("nativescript-plugin-firebase");
18+
19+
firebase.init({
20+
persist: true
21+
}).then(
22+
function (instance) {
23+
console.log("firebase.init done");
24+
},
25+
function (error) {
26+
console.log("firebase.init error: " + error);
27+
}
28+
);
29+
```
30+
31+
All further examples assume `firebase` has been required.
32+
Also, all functions support promises, but we're leaving out the `.then()` stuff for brevity where it doesn't add value.
33+
34+
### setValue
35+
Data is stored as JSON data at a specific path (which is appended to the URL you passed to `init`).
36+
If you want to add data to a known path use this, otherwise use `push` (see below).
37+
38+
The plugin will take care of serializing JSON data to native data structures.
39+
40+
```js
41+
42+
// to store a JSON object
43+
firebase.setValue(
44+
'/companies',
45+
{'foo':'bar'}
46+
);
47+
48+
// to store an array of JSON objects
49+
firebase.setValue(
50+
'/companies',
51+
[
52+
{name: 'Telerik', country: 'Bulgaria'},
53+
{name: 'Google', country: 'USA'}
54+
]
55+
);
56+
```
57+
58+
### push
59+
This function will store a JSON object at path `<Firebase URL>/users/<Generated Key>`
60+
61+
```js
62+
firebase.push(
63+
'/users',
64+
{
65+
'first': 'Eddy',
66+
'last': 'Verbruggen',
67+
'birthYear': 1977,
68+
'isMale': true,
69+
'address': {
70+
'street': 'foostreet',
71+
'number': 123
72+
}
73+
}
74+
).then(
75+
function (result) {
76+
console.log("created key: " + result.key);
77+
}
78+
);
79+
```
80+
81+
### query
82+
Firebase supports querying data and this plugin does too, since v2.0.0.
83+
84+
Let's say we have the structure as defined at `setValue`, then use this query to retrieve the companies in country 'Bulgaria':
85+
86+
```js
87+
var onQueryEvent = function(result) {
88+
// note that the query returns 1 match at a time
89+
// in the order specified in the query
90+
if (!result.error) {
91+
console.log("Event type: " + result.type);
92+
console.log("Key: " + result.key);
93+
console.log("Value: " + JSON.stringify(result.value));
94+
}
95+
};
96+
97+
firebase.query(
98+
onQueryEvent,
99+
"/companies",
100+
{
101+
// set this to true if you want to check if the value exists or just want the event to fire once
102+
// default false, so it listens continuously
103+
singleEvent: true,
104+
// order by company.country
105+
orderBy: {
106+
type: firebase.QueryOrderByType.CHILD,
107+
value: 'country' // mandatory when type is 'child'
108+
},
109+
// but only companies named 'Telerik'
110+
// (this range relates to the orderBy clause)
111+
range: {
112+
type: firebase.QueryRangeType.EQUAL_TO,
113+
value: 'Bulgaria'
114+
},
115+
// only the first 2 matches
116+
// (note that there's only 1 in this case anyway)
117+
limit: {
118+
type: firebase.QueryLimitType.LAST,
119+
value: 2
120+
}
121+
}
122+
);
123+
```
124+
125+
For supported values of the orderBy/range/limit's `type` properties, take a look at the [`firebase-common.d.ts`](firebase-common.d.ts) TypeScript definitions in this repo.
126+
127+
### update
128+
Changes the values of the keys specified in the dictionary without overwriting other keys at this location.
129+
130+
```js
131+
firebase.update(
132+
'/companies',
133+
{'foo':'baz'}
134+
);
135+
```
136+
137+
### addChildEventListener
138+
To listen for changes in your database you can pass in a listener callback function.
139+
You get to control which path inside you database you want to listen to, by default it's `/` which is the entire database.
140+
141+
The plugin will take care of serializing native data structures to JSON data.
142+
143+
```js
144+
var onChildEvent = function(result) {
145+
console.log("Event type: " + result.type);
146+
console.log("Key: " + result.key);
147+
console.log("Value: " + JSON.stringify(result.value));
148+
};
149+
150+
// listen to changes in the /users path
151+
firebase.addChildEventListener(onChildEvent, "/users");
152+
```
153+
154+
### addValueEventListener
155+
The difference with `addChildEventListener` is [explained here](https://www.firebase.com/docs/ios/guide/retrieving-data.html).
156+
The link is for the iOS SDK, but it's the same for Android.
157+
158+
```js
159+
var onValueEvent = function(result) {
160+
console.log("Event type: " + result.type);
161+
console.log("Key: " + result.key);
162+
console.log("Value: " + JSON.stringify(result.value));
163+
};
164+
165+
// listen to changes in the /companies path
166+
firebase.addValueEventListener(onValueEvent, "/companies");
167+
```
168+
169+
### remove
170+
You can remove the entire database content by passing `/` as param,
171+
but if you only want to wipe everything at `/users`, do this:
172+
173+
```js
174+
firebase.remove("/users");
175+
```

‎docs/NOTIFICATIONS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
W.I.P.

0 commit comments

Comments
 (0)