Skip to content

Commit c2d67be

Browse files
manughubmanughub
committed
docs: rewrite getting started guide to use CLI schematics
1 parent 2d976a9 commit c2d67be

File tree

1 file changed

+55
-152
lines changed

1 file changed

+55
-152
lines changed

‎guides/getting-started.md

Lines changed: 55 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -1,196 +1,99 @@
1-
For help getting started with a new Angular app, check out the
2-
[Angular CLI](https://cli.angular.io/).
1+
# Getting Started with Angular Material
32

4-
For existing apps, follow these steps to begin using Angular Material.
3+
This guide explains how to setup your Angular project to begin using Angular Material. It includes information on prerequisites, installing Angular Material, and optionally displaying a sample material component in your application to verify your setup.
54

6-
### Step 1: Install Angular Material, Angular CDK and Angular Animations
5+
### New to Angular ?
76

8-
You can use either the npm or yarn command-line tool to install packages. Use whichever is appropriate for your project in the examples below.
7+
If you are new to Angular or getting started with a new Angular application, see [Angular's full Getting Started Guide](https://angular.io/start) and [Setting up your environment](https://angular.io/guide/setup-local).
98

10-
#### NPM
11-
```bash
12-
npm install --save @angular/material @angular/cdk @angular/animations
13-
```
14-
#### Yarn
15-
```bash
16-
yarn add @angular/material @angular/cdk @angular/animations
17-
```
18-
19-
20-
#### Alternative 1: Snapshot Build
9+
For existing applications, follow the steps below to begin using Angular Material:
2110

22-
A snapshot build with the latest changes from master is also available. Note that this snapshot
23-
build should not be considered stable and may break between releases.
2411

25-
#### NPM
26-
```bash
27-
npm install --save angular/material2-builds angular/cdk-builds angular/animations-builds
28-
```
29-
30-
#### Yarn
31-
```bash
32-
yarn add angular/material2-builds angular/cdk-builds angular/animations-builds
33-
```
34-
#### Alternative 2: Angular Devkit 6+
12+
### Step 1: Install Angular Material npm packages
3513

36-
Using the Angular CLI `ng add` command will update your Angular project with the correct dependencies, perform configuration changes and execute initialization code.
14+
Use the Angular CLI's install [schematic](https://material.angular.io/guide/schematics) to set up your Angular Material project by running the following command:
3715

3816
```bash
3917
ng add @angular/material
4018
```
4119

42-
### Step 2: Configure animations
20+
The `ng add` command will install Angular Material, the [Component Dev Kit (CDK)](https://material.angular.io/cdk/categories), [Angular Animations](https://angular.io/guide/animations) and ask you the following questions to determine which features to include:
4321

44-
Once the animations package is installed, import `BrowserAnimationsModule` into your application to enable animations support.
22+
1. Choose a prebuilt theme name, or "custom" for a custom theme:
4523

46-
```ts
47-
import {BrowserAnimationsModule} from '@angular/platform-browser/animations';
24+
You can choose from [prebuilt material design themes](https://material.angular.io/guide/theming#using-a-pre-built-theme) or set up an extensible [custom theme](https://material.angular.io/guide/theming#defining-a-custom-theme).
4825

49-
@NgModule({
50-
...
51-
imports: [BrowserAnimationsModule],
52-
...
53-
})
54-
export class PizzaPartyAppModule { }
55-
```
26+
2. Set up HammerJS for gesture recognition:
5627

57-
Alternatively, you can disable animations by importing `NoopAnimationsModule`.
28+
[HammerJS](http://hammerjs.github.io/) provides gesture recognition capabilities required by some components (`mat-slide-toggle`, `mat-slider`, `matToolTip`).
5829

59-
```ts
60-
import {NoopAnimationsModule} from '@angular/platform-browser/animations';
30+
Please note, if you choose not to install HammerJS it can be installed later via npm using the following command:
6131

62-
@NgModule({
63-
...
64-
imports: [NoopAnimationsModule],
65-
...
66-
})
67-
export class PizzaPartyAppModule { }
68-
```
32+
#### NPM
6933

70-
### Step 3: Import the component modules
34+
```bash
35+
npm install --save hammerjs
36+
```
7137

72-
Import the NgModule for each component you want to use:
38+
#### Yarn
7339

74-
```ts
75-
import {MatButtonModule} from '@angular/material/button';
76-
import {MatCheckboxModule} from '@angular/material/checkbox';
40+
```bash
41+
yarn add hammerjs
42+
```
7743

78-
@NgModule({
79-
...
80-
imports: [MatButtonModule, MatCheckboxModule],
81-
...
82-
})
83-
export class PizzaPartyAppModule { }
84-
```
44+
After installing, import it on your app's entry point (e.g. `src/main.ts`).
8545

86-
Alternatively, you can create a separate NgModule that imports and then re-exports all of the Angular Material components that you will use in your application. By exporting them again, other modules can simply include your `CustomMaterialModule` wherever Material components are needed, and automatically get all of the exported Material modules. A good place for importing/exporting the application-wide Material modules is the [SharedModule](https://angular.io/guide/ngmodule-faq#sharedmodule).
46+
```ts
47+
import 'hammer.js';
48+
```
8749

88-
```ts
89-
import {MatButtonModule} from '@angular/material/button';
90-
import {MatCheckboxModule} from '@angular/material/checkbox';
50+
3. Set up browser animations for Angular Material:
9151

92-
@NgModule({
93-
imports: [MatButtonModule, MatCheckboxModule],
94-
exports: [MatButtonModule, MatCheckboxModule],
95-
})
96-
export class MyOwnCustomMaterialModule { }
97-
```
52+
Importing the [`BrowserAnimationsModule`](https://angular.io/api/platform-browser/animations/BrowserAnimationsModule) into your application enables Angular's [animation system](https://angular.io/guide/animations). Declining this will disable most of Angular Material's animations.
9853

99-
Whichever approach you use, be sure to import the Angular Material modules _after_ Angular's
100-
`BrowserModule`, as the import order matters for NgModules.
54+
The `ng add` command will additionally perform the following configurations:
10155

102-
### Step 4: Include a theme
56+
* Add project dependencies to `package.json`
57+
* Add the Roboto font to your `index.html`
58+
* Add the Material Design icon font to your `index.html`
59+
* Add a few global CSS styles to:
60+
* Remove margins from `body`
61+
* Set `height: 100%` on `html` and `body`
62+
* Set Roboto as the default application font
10363

104-
Including a theme is **required** to apply all of the core and theme styles to your application.
64+
You're done! Angular Material is now configured to be used in your application.
10565

106-
To get started with a prebuilt theme, include one of Angular Material's prebuilt themes globally
107-
in your application. If you're using the Angular CLI, you can add this to your `styles.css`:
108-
```css
109-
@import "~@angular/material/prebuilt-themes/indigo-pink.css";
110-
```
111-
112-
If you are not using the Angular CLI, you can include a prebuilt theme via a `<link>` element in
113-
your `index.html`.
114-
115-
For more information on theming and instructions on how to create a custom theme, see the
116-
[theming guide](./theming.md).
11766

118-
### Step 5: Gesture Support
67+
### Step 2: Display an example Angular Material component
11968

120-
Some components (`mat-slide-toggle`, `mat-slider`, `matTooltip`) rely on
121-
[HammerJS](http://hammerjs.github.io/) for gestures. In order to get the full feature-set of these
122-
components, HammerJS must be loaded into the application.
69+
Let's display a slider component in your app and verify that everything works.
12370

124-
You can add HammerJS to your application via [npm](https://www.npmjs.com/package/hammerjs), a CDN
125-
(such as the [Google CDN](https://developers.google.com/speed/libraries/#hammerjs)), or served
126-
directly from your app.
71+
You need to import the `MatSliderModule` that you want to display by adding the following lines to your app.module.ts file.
12772

128-
To install via npm, use the following command:
129-
130-
#### NPM
131-
```bash
132-
npm install --save hammerjs
133-
```
134-
135-
#### Yarn
136-
```bash
137-
yarn add hammerjs
138-
```
139-
140-
After installing, import it on your app's entry point (e.g. `src/main.ts`).
14173
```ts
142-
import 'hammerjs';
74+
import { MatSliderModule } from '@angular/material';
75+
…
76+
@NgModule ({....
77+
imports: [...,
78+
MatSliderModule,
79+
…]
80+
})
14381
```
14482

145-
### Step 6 (Optional): Add Material Icons
146-
147-
If you want to use the `mat-icon` component with the official
148-
[Material Design Icons](https://material.io/icons/), load the icon font in your `index.html`.
83+
Add the `<mat-slider>` tag to the `app.component.html` like so:
14984

15085
```html
151-
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
86+
<mat-slider min="1" max="100" step="1" value="1"></mat-slider>
15287
```
15388

154-
For more information on using Material Icons, check out the
155-
[Material Icons Guide](https://google.github.io/material-design-icons/).
156-
157-
Note that `mat-icon` supports any font or svg icons; using Material Icons is one of many options.
158-
159-
160-
### Appendix: Configuring SystemJS
161-
162-
If your project is using SystemJS for module loading, you will need to add `@angular/material` and
163-
`@angular/cdk` to the SystemJS configuration.
164-
165-
The `@angular/cdk` package is organized of multiple entry-points.
166-
Each of these entry-points must be registered individually with SystemJS.
89+
Run your local dev server:
16790

168-
Here is a example configuration where `@angular/material`, `@angular/cdk/platform` and
169-
`@angular/cdk/a11y` are used:
170-
171-
172-
```js
173-
System.config({
174-
// Existing configuration options
175-
map: {
176-
// ...
177-
'@angular/material': 'npm:@angular/material/bundles/material.umd.js',
178-
179-
// CDK individual packages
180-
'@angular/cdk/platform': 'npm:@angular/cdk/bundles/cdk-platform.umd.js',
181-
'@angular/cdk/a11y': 'npm:@angular/cdk/bundles/cdk-a11y.umd.js',
182-
// ...
183-
'hammerjs': 'npm:hammerjs',
184-
},
185-
packages: {
186-
//...
187-
hammerjs: {main: './hammer.min.js', defaultExtension: 'js'}
188-
//...
189-
}
190-
});
91+
```bash
92+
ng serve
19193
```
19294

95+
and point your browser to [http://localhost:4200](http://localhost:4200)
96+
97+
You should see the material slider component on the page.
19398

194-
### Example Angular Material projects
195-
- [material.angular.io](https://material.angular.io) -
196-
We build our own documentation with Angular Material!
99+
In addition to the install schematic, Angular Material comes with [several schematics](https://material.angular.io/guide/schematics) (like nav, table, address-form, etc.) that can be used to easily generate pre-built components in your application.

0 commit comments

Comments
 (0)