Skip to content

Commit 8920b10

Browse files
davideastdavideast
authored
feat(docs): Docs for RC5 (#455)
* chore(docs): Update README for next releases * feat(docs): Docs for RC5 * fix(tests): FirebaseListObservable tests * fix(tests): Don't throw a fit
1 parent 13a5e1e commit 8920b10

File tree

4 files changed

+232
-103
lines changed

4 files changed

+232
-103
lines changed

‎docs/1-install-and-setup.md

+21-99
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,21 @@
1+
# These instructions are for the @next RC5 setup
2+
We have yet to release the RC5 version to the main package because we are still testing it out. We recommend you try it by following the steps below. However, if you are still on RC4, you can refer to the older docs here: https://github.com/angular/angularfire2/blob/5720ebc48fddb2d1e75cd905fb534c4ed2e5c286/docs/1-install-and-setup.md
3+
14
# 1. Installation and Setup
25

36
> Getting started with AngularFire2 is easy with the [Angular CLI](https://github.com/angular/angular-cli). Follow the 10 steps below to get started. Don't worry, we're always working to make this shorter.
47
5-
**The setups below use the [Angular CLI](https://github.com/angular/angular-cli).**
8+
**The setups below use the Webpack branch of the [Angular CLI](https://github.com/angular/angular-cli).**
9+
10+
**For the Broccoli/System.js branch [see this set up guide](broccoli-system-js-cli-setup.md)**
611

712
### 0. Prerequisites
813

914
```bash
10-
npm install -g angular-cli
15+
npm install -g angular-cli@webpack
16+
# or install locally
17+
npm install angular-cli@webpack --save-dev
18+
# make sure you have typings installed
1119
npm install -g typings
1220
```
1321

@@ -28,125 +36,39 @@ npm install angularfire2 firebase --save
2836

2937
Now that you have a new project setup, install AngularFire 2 and Firebase from npm.
3038

31-
### 3. Include Firebase SDK typings
32-
33-
```bash
34-
typings install file:node_modules/angularfire2/firebase3.d.ts --save --global && typings install
35-
```
36-
37-
This saves the typings reference into `typings.json` and installs it.
38-
39-
Note: for typings < 1, use the `--ambient` flag instead of `--global`.
40-
41-
Unless you're targeting ES6 output in tsconfig.json, you'll also need to install
42-
typings for the global Promise constructor. Run this command:
43-
44-
`$ typings install --save --global es6-promise`
45-
46-
If you're using Angular CLI, the typings will automatically be added to your
47-
tsconfig since there is already a reference to `"typings.d.ts"` which transitively
48-
includes `es6-promise`. If you're using a different seed project, or managing your
49-
build yourself, just add the reference to your tsconfig files array:
50-
51-
```json
52-
"files": [
53-
"node_modules/angularfire2/firebase3.d.ts",
54-
"typings/main.d.ts"
55-
]
56-
```
57-
58-
59-
### 4. Include AngularFire 2 and Firebase in the vendor files
60-
61-
Open `angular-cli-build.js`.
62-
63-
Include AngularFire2 and Firebase in the `vendorNpmFiles` array:
64-
65-
```js
66-
/* global require, module */
67-
68-
var Angular2App = require('angular-cli/lib/broccoli/angular2-app');
69-
70-
module.exports = function(defaults) {
71-
return new Angular2App(defaults, {
72-
vendorNpmFiles: [
73-
'systemjs/dist/system-polyfills.js',
74-
'systemjs/dist/system.src.js',
75-
'zone.js/dist/**/*.+(js|js.map)',
76-
'es6-shim/es6-shim.js',
77-
'reflect-metadata/**/*.+(js|js.map)',
78-
'rxjs/**/*.+(js|js.map)',
79-
'@angular/**/*.+(js|js.map)',
80-
// above are the existing entries
81-
// below are the AngularFire entries
82-
'angularfire2/**/*.js',
83-
'firebase/*.js'
84-
]
85-
});
86-
};
87-
```
88-
89-
### 5. Build
90-
91-
```bash
92-
ng build
93-
```
94-
95-
Run a build and check the `/dist/vendor` folder for the `angularfire2` and `firebase` folders.
96-
97-
### 6. System.js
98-
99-
Open `/src/system-config.ts`. Modify the file like below:
100-
101-
```js
102-
/** Map relative paths to URLs. */
103-
const map: any = {
104-
'firebase': 'vendor/firebase/firebase.js',
105-
'angularfire2': 'vendor/angularfire2'
106-
};
107-
108-
/** User packages configuration. */
109-
const packages: any = {
110-
angularfire2: {
111-
defaultExtension: 'js',
112-
main: 'angularfire2.js'
113-
}
114-
};
115-
```
116-
117-
AngularFire 2 and Firebase need to be mapped with System.js for module loading.
118-
119-
### 7. Bootstrap
39+
### 3. Setup @NgModule
12040

12141
Open `/src/main.ts`, inject the Firebase providers, and specify your Firebase configuration.
12242
This can be found in your project at [the Firebase Console](https://console.firebase.google.com):
12343

12444
```ts
12545
import { BrowserModule } from '@angular/platform-browser';
46+
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
12647
import { enableProdMode, NgModule } from '@angular/core';
127-
import { <MyApp>, environment } from './app/';
48+
import { AppComponent, environment } from './app/';
12849
import { AngularFireModule } from 'angularfire2';
12950

130-
const firebaseConfig = {
51+
// Must export the config
52+
export const firebaseConfig = {
13153
apiKey: "<your-key>",
13254
authDomain: "<your-project-authdomain>",
13355
databaseURL: "<your-database-URL>",
13456
storageBucket: "<your-storage-bucket>"
135-
}
57+
};
13658

13759
@NgModule({
13860
imports: [
13961
BrowserModule,
14062
AngularFireModule.initializeApp(firebaseConfig)
14163
],
142-
declarations: [ MyComponent ],
143-
Bootstrap: [ MyComponent ]
64+
declarations: [ AppComponent ],
65+
Bootstrap: [ AppComponent ]
14466
})
14567
export class MyAppModule {}
14668

14769
```
14870

149-
### 8. Inject AngularFire
71+
### 4. Inject AngularFire
15072

15173
Open `/src/app/<my-app>.component.ts`, and make sure to modify/delete any tests to get the sample working (tests are still important, you know):
15274

@@ -168,7 +90,7 @@ export class <MyApp>Component {
16890

16991
```
17092

171-
### 9. Bind to a list
93+
### 5. Bind to a list
17294

17395
In `/src/app/<my-app>.component.ts`:
17496

@@ -215,7 +137,7 @@ observable as they arrive. Also the array that is received through the `items` o
215137
]
216138
```
217139

218-
### 10. Serve
140+
### 6. Serve
219141

220142
```bash
221143
ng serve

‎docs/broccoli-system-js-cli-setup.md

+207
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# These instructions are for the @next RC5 setup
2+
We have yet to release the RC5 version to the main package because we are still testing it out. We recommend you try it by following the steps below. However, if you are still on RC4, you can refer to the older docs here: https://github.com/angular/angularfire2/blob/5720ebc48fddb2d1e75cd905fb534c4ed2e5c286/docs/1-install-and-setup.md
3+
4+
# 1. Installation and Setup
5+
6+
> Getting started with AngularFire2 is easy with the [Angular CLI](https://github.com/angular/angular-cli). Follow the 10 steps below to get started. Don't worry, we're always working to make this shorter.
7+
8+
**The setups below use the [Angular CLI](https://github.com/angular/angular-cli).**
9+
10+
**We recommend using the Webpack branch, [which you can see the guide here.](1-install-and-setup.md)**
11+
12+
### 0. Prerequisites
13+
14+
```bash
15+
npm install -g angular-cli
16+
npm install -g typings
17+
```
18+
19+
### 1. Create a new project
20+
21+
```bash
22+
ng new <project-name>
23+
cd <project-name>
24+
```
25+
26+
The Angular CLI's `new` command will set up the latest Angular build in a new project structure.
27+
28+
### 2. Install AngularFire 2 and Firebase
29+
30+
```bash
31+
npm install angularfire2 firebase --save
32+
```
33+
34+
Now that you have a new project setup, install AngularFire 2 and Firebase from npm.
35+
36+
### 3. Include AngularFire 2 and Firebase in the vendor files
37+
38+
Open `angular-cli-build.js`.
39+
40+
Include AngularFire2 and Firebase in the `vendorNpmFiles` array:
41+
42+
```js
43+
/* global require, module */
44+
45+
var Angular2App = require('angular-cli/lib/broccoli/angular2-app');
46+
47+
module.exports = function(defaults) {
48+
return new Angular2App(defaults, {
49+
vendorNpmFiles: [
50+
'systemjs/dist/system-polyfills.js',
51+
'systemjs/dist/system.src.js',
52+
'zone.js/dist/**/*.+(js|js.map)',
53+
'es6-shim/es6-shim.js',
54+
'reflect-metadata/**/*.+(js|js.map)',
55+
'rxjs/**/*.+(js|js.map)',
56+
'@angular/**/*.+(js|js.map)',
57+
// above are the existing entries
58+
// below are the AngularFire entries
59+
'angularfire2/**/*.js',
60+
'firebase/*.js'
61+
]
62+
});
63+
};
64+
```
65+
66+
### 4. Build
67+
68+
```bash
69+
ng build
70+
```
71+
72+
Run a build and check the `/dist/vendor` folder for the `angularfire2` and `firebase` folders.
73+
74+
### 5. System.js
75+
76+
Open `/src/system-config.ts`. Modify the file like below:
77+
78+
```js
79+
/** Map relative paths to URLs. */
80+
const map: any = {
81+
'firebase': 'vendor/firebase/firebase.js',
82+
'angularfire2': 'vendor/angularfire2'
83+
};
84+
85+
/** User packages configuration. */
86+
const packages: any = {
87+
angularfire2: {
88+
defaultExtension: 'js',
89+
main: 'angularfire2.js'
90+
}
91+
};
92+
```
93+
94+
AngularFire 2 and Firebase need to be mapped with System.js for module loading.
95+
96+
### 6. Set up @NgModule
97+
98+
Open `/src/main.ts`, inject the Firebase providers, and specify your Firebase configuration.
99+
This can be found in your project at [the Firebase Console](https://console.firebase.google.com):
100+
101+
```ts
102+
import { BrowserModule } from '@angular/platform-browser';
103+
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
104+
import { enableProdMode, NgModule } from '@angular/core';
105+
import { AppComponent, environment } from './app/';
106+
import { AngularFireModule } from 'angularfire2';
107+
108+
// Must export the config
109+
export const firebaseConfig = {
110+
apiKey: "<your-key>",
111+
authDomain: "<your-project-authdomain>",
112+
databaseURL: "<your-database-URL>",
113+
storageBucket: "<your-storage-bucket>"
114+
};
115+
116+
@NgModule({
117+
imports: [
118+
BrowserModule,
119+
AngularFireModule.initializeApp(firebaseConfig)
120+
],
121+
declarations: [ AppComponent ],
122+
Bootstrap: [ AppComponent ]
123+
})
124+
export class MyAppModule {}
125+
126+
```
127+
128+
### 7. Inject AngularFire
129+
130+
Open `/src/app/<my-app>.component.ts`, and make sure to modify/delete any tests to get the sample working (tests are still important, you know):
131+
132+
```ts
133+
import { Component } from '@angular/core';
134+
import { AngularFire, FirebaseListObservable } from 'angularfire2';
135+
136+
@Component({
137+
moduleId: module.id,
138+
selector: '<my-app>-app',
139+
templateUrl: '<my-app>.component.html',
140+
styleUrls: ['<my-app>.component.css']
141+
})
142+
export class <MyApp>Component {
143+
constructor(af: AngularFire) {
144+
145+
}
146+
}
147+
148+
```
149+
150+
### 8. Bind to a list
151+
152+
In `/src/app/<my-app>.component.ts`:
153+
154+
```ts
155+
import { Component } from '@angular/core';
156+
import { AngularFire, FirebaseListObservable } from 'angularfire2';
157+
158+
@Component({
159+
moduleId: module.id,
160+
selector: '<my-app>-app',
161+
templateUrl: '<my-app>.component.html',
162+
styleUrls: ['<my-app>.component.css']
163+
})
164+
export class <MyApp>Component {
165+
items: FirebaseListObservable<any[]>;
166+
constructor(af: AngularFire) {
167+
this.items = af.database.list('items');
168+
}
169+
}
170+
```
171+
172+
Open `/src/app/<my-app>.component.html`:
173+
174+
```html
175+
<ul>
176+
<li class="text" *ngFor="let item of items | async">
177+
{{item.$value}}
178+
</li>
179+
</ul>
180+
```
181+
182+
The `async` pipe unwraps the each item in the people observable as they arrive. The observable emits an array of items that automatically unwraps A structure like this:
183+
184+
```json
185+
[
186+
{
187+
"$value": 'something',
188+
"$key": '<the-key>'
189+
},
190+
{
191+
"$value": 'something else',
192+
(...)
193+
},
194+
]
195+
```
196+
197+
### 9. Serve
198+
199+
```bash
200+
ng serve
201+
```
202+
203+
Run the serve command and go to `localhost:4200` in your browser.
204+
205+
And that's it! If it totally borke, file an issue and let us know.
206+
207+
###[Next Step: Retrieving data as objects](2-retrieving-data-as-objects.md)

‎src/database/firebase_list_observable.spec.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ describe('FirebaseObservable', () => {
144144

145145
it('should throw an exception if input is not supported', () => {
146146
var input = (<any>{lol:true});
147-
expect(() => O.remove(input)).toThrowError(`FirebaseListObservable.remove requires a key, snapshot, reference, or unwrapped snapshot. Got: ${typeof input}`);
147+
expect(() => O.remove(input)).toThrowError(`Method requires a key, snapshot, reference, or unwrapped snapshot. Got: ${typeof input}`);
148148
})
149149
});
150150

0 commit comments

Comments
 (0)