Skip to content

Commit 4af253a

Browse files
karakara
committed
docs(starter): added getting-started guide
Closes #383
1 parent 06aa3f1 commit 4af253a

File tree

2 files changed

+154
-23
lines changed

2 files changed

+154
-23
lines changed

‎GETTING_STARTED.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
This guide will take you through building your first project with Angular Material 2. We'll be using
2+
the Angular CLI, but you can also accomplish this with other build tools like Webpack or Gulp.
3+
4+
### Globally install the CLI
5+
6+
```bash
7+
npm install -g angular-cli
8+
```
9+
10+
### Create a new project
11+
12+
```bash
13+
ng new my-project
14+
```
15+
16+
This will create a starter repo under the name you specified with the files and folders
17+
you'd need for any Angular 2 app: a root component, a main.ts to bootstrap your root component, an
18+
index.html, etc. It also sets up build rules to transpile your Typescript into Javascript and sets
19+
some initial config for the SystemJS module loader.
20+
21+
### Install Angular Material 2 components
22+
23+
Now that your project has been created, you can install any Angular Material 2 components you'd like
24+
to use through npm. You can see our [list of published packages here](https://www.npmjs.com/~angular2-material).
25+
26+
```bash
27+
npm install --save @angular2-material/{core,button,card}
28+
```
29+
Note: the core module is required as a peer dependency of other components.
30+
31+
### Add components to vendor bundle
32+
33+
Next, you'll need to build the `@angular2-material` folder out of `node_modules` and into
34+
`dist/vendor`, so that it's served with the rest of the vendor files. You can easily configure this by
35+
editing the `angular-cli-build.js` file in the root of your project. Simply add a glob for all
36+
@angular2-material files to the end of the existing `vendorNpmFiles` array.
37+
38+
**angular-cli-build.js**
39+
```js
40+
module.exports = function(defaults) {
41+
return new Angular2App(defaults, {
42+
vendorNpmFiles: [
43+
'systemjs/dist/system-polyfills.js',
44+
'systemjs/dist/system.src.js',
45+
'zone.js/dist/**/*.+(js|js.map)',
46+
'es6-shim/es6-shim.js',
47+
'reflect-metadata/**/*.+(js|js.map)',
48+
'rxjs/**/*.+(js|js.map)',
49+
'@angular/**/*.+(js|js.map)',
50+
'@angular2-material/**/*'
51+
]
52+
});
53+
};
54+
```
55+
56+
You can see an example `angular-cli-build.js` file [here](https://github.com/kara/puppy-love/blob/master/angular-cli-build.js).
57+
58+
### Configure SystemJS
59+
60+
First, you need to let SystemJS know where to look when you import `@angular2-material`. You can do
61+
this by adding the path to the Material folder to the `maps` object.
62+
63+
**src/system-config.ts**
64+
```ts
65+
const map: any = {
66+
'@angular2-material': 'vendor/@angular2-material'
67+
};
68+
```
69+
70+
This says something like "when you look for an @angular2-material import, look inside the vendor
71+
folder" (the base folder will already be `dist`).
72+
73+
Next, you need to let SystemJS know how to process the new modules. Specifically, you need to point
74+
to the main files of each of the packages. You can also set the format to `cjs` and the
75+
defaultExtension to `js`, but it's not required.
76+
77+
**src/system-config.ts**
78+
```ts
79+
const packages:any = {};
80+
81+
// put the names of any of your Material components here
82+
const materialPkgs:string[] = [
83+
'core',
84+
'button',
85+
'card',
86+
];
87+
88+
materialPkgs.forEach((pkg) => {
89+
packages[`@angular2-material/${pkg}`] = {main: `${pkg}.js`};
90+
});
91+
```
92+
93+
You can see an example `system-config.ts` [here](https://github.com/kara/puppy-love-io/blob/master/src/system-config.ts).
94+
95+
### Import and use the components
96+
97+
Now you should be able to import the components normally wherever you'd like to use them.
98+
99+
**src/app/my-project.component.ts**
100+
```ts
101+
import { MD_CARD_DIRECTIVES } from '@angular2-material/card';
102+
import { MD_BUTTON_DIRECTIVES } from '@angular2-material/button';
103+
```
104+
105+
And don't forget to add the directives to your directives array:
106+
107+
**src/app/my-project.component.ts**
108+
```ts
109+
directives: [MD_CARD_DIRECTIVES, MD_BUTTON_DIRECTIVES]
110+
```
111+
112+
### Sample Angular Material 2 projects
113+
114+
- [Puppy Love (ng-conf 2016)](https://github.com/kara/puppy-love) - see live demo [here](https://youtu.be/rRiV_b3WsoY?t=4m20s)
115+
- [Puppy Love Mobile (Google IO 2016)](https://github.com/kara/puppy-love-io)
116+
- [Material 2 Sample App](https://github.com/jelbourn/material2-app)
117+
118+
### Additional steps for `md-icon` setup:
119+
120+
- If you want to use Material Design icons, load the Material Design font in your `index.html`. `md-icon` supports any font icons or svg icons,
121+
so this is only one potential option.
122+
123+
**src/index.html**
124+
```html
125+
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
126+
```
127+
128+
- Include http providers in your `main.ts`:
129+
130+
**src/main.ts**
131+
```ts
132+
import { HTTP_PROVIDERS } from '@angular/http';
133+
...
134+
bootstrap(MyAppComponent, [
135+
HTTP_PROVIDERS
136+
]);
137+
```
138+
139+
- Provide the icon registry at or above the component where you're using the icon:
140+
141+
**src/app/my-project.component.ts**
142+
```ts
143+
import {MdIcon, MdIconRegistry} from '@angular2-material/icon';
144+
...
145+
directives: [MD_CARD_DIRECTIVES, MD_BUTTON_DIRECTIVES, MdIcon],
146+
providers: [MdIconRegistry]
147+
```
148+
149+
150+
151+
152+

‎README.md

Lines changed: 2 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -8,29 +8,8 @@ This is the home for the Angular team's Material Design components built on top
88
### Project status
99
The alpha has begun! See the [changelog](CHANGELOG.md) for more information.
1010

11-
Individual components can be installed with `npm`:
12-
```bash
13-
# The core module is required as a peerDependency for other components
14-
npm install --save @angular2-material/core @angular2-material/checkbox
15-
```
16-
17-
You can see our [list of published packages on npm](https://www.npmjs.com/~angular2-material).
18-
19-
If you're using SystemJS as your module loader, your configuration for the angular-material
20-
packages should look like:
21-
```js
22-
// The core package is required as a peerDependency for other components.
23-
'@angular2-material/core': {
24-
format: 'cjs',
25-
defaultExtension: 'js',
26-
main: 'core.js'
27-
},
28-
'@angular2-material/checkbox': {
29-
format: 'cjs',
30-
defaultExtension: 'js',
31-
main: 'checkbox.js'
32-
},
33-
```
11+
You also might want to check out our [Getting Started Guide](https://github.com/angular/material2/blob/master/GETTING_STARTED.md) if you're
12+
building your first project with Angular Material 2.
3413

3514
During alpha, breaking API and behavior changes will be occurring regularly.
3615

0 commit comments

Comments
 (0)