Skip to content

Commit 8d46f95

Browse files
manughubandrewseguin
manughub
authored and
andrewseguin
committed
docs(Getting Started): Updated material Getting Started guide to use install schematics and simplify the overall process (#16654)
* docs: rewrite getting started guide to use CLI schematics * docs(Getting Started): Moving HammerJS install to appendix * docs(Getting Started): Moving HammerJS install to appendix * docs(Getting Started): Moving HammerJS install to appendix (cherry picked from commit ca7fff5)
1 parent 88872be commit 8d46f95

File tree

1 file changed

+51
-151
lines changed

1 file changed

+51
-151
lines changed

‎guides/getting-started.md

Lines changed: 51 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -1,196 +1,96 @@
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-
```
9+
For existing applications, follow the steps below to begin using Angular Material:
1810

1911

20-
#### Alternative 1: Snapshot Build
12+
### Step 1: Install Angular Material npm packages
2113

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.
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:
2415

25-
#### NPM
2616
```bash
27-
npm install --save angular/material2-builds angular/cdk-builds angular/animations-builds
17+
ng add @angular/material
2818
```
2919

30-
#### Yarn
31-
```bash
32-
yarn add angular/material2-builds angular/cdk-builds angular/animations-builds
33-
```
34-
#### Alternative 2: Angular Devkit 6+
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:
3521

36-
Using the Angular CLI `ng add` command will update your Angular project with the correct dependencies, perform configuration changes and execute initialization code.
22+
1. Choose a prebuilt theme name, or "custom" for a custom theme:
3723

38-
```bash
39-
ng add @angular/material
40-
```
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).
4125

42-
### Step 2: Configure animations
26+
2. Set up HammerJS for gesture recognition:
4327

44-
Once the animations package is installed, import `BrowserAnimationsModule` into your application to enable animations support.
28+
[HammerJS](http://hammerjs.github.io/) provides gesture recognition capabilities required by some components (`mat-slide-toggle`, `mat-slider`, `matToolTip`).
4529

46-
```ts
47-
import {BrowserAnimationsModule} from '@angular/platform-browser/animations';
30+
Please note, if you choose not to install HammerJS it can be installed later (see Appendix).
4831

49-
@NgModule({
50-
...
51-
imports: [BrowserAnimationsModule],
52-
...
53-
})
54-
export class PizzaPartyAppModule { }
55-
```
32+
3. Set up browser animations for Angular Material:
5633

57-
Alternatively, you can disable animations by importing `NoopAnimationsModule`.
34+
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.
5835

59-
```ts
60-
import {NoopAnimationsModule} from '@angular/platform-browser/animations';
36+
The `ng add` command will additionally perform the following configurations:
6137

62-
@NgModule({
63-
...
64-
imports: [NoopAnimationsModule],
65-
...
66-
})
67-
export class PizzaPartyAppModule { }
68-
```
38+
* Add project dependencies to `package.json`
39+
* Add the Roboto font to your `index.html`
40+
* Add the Material Design icon font to your `index.html`
41+
* Add a few global CSS styles to:
42+
* Remove margins from `body`
43+
* Set `height: 100%` on `html` and `body`
44+
* Set Roboto as the default application font
6945

70-
### Step 3: Import the component modules
46+
You're done! Angular Material is now configured to be used in your application.
7147

72-
Import the NgModule for each component you want to use:
7348

74-
```ts
75-
import {MatButtonModule} from '@angular/material/button';
76-
import {MatCheckboxModule} from '@angular/material/checkbox';
49+
### Step 2: Display an example Angular Material component
7750

78-
@NgModule({
79-
...
80-
imports: [MatButtonModule, MatCheckboxModule],
81-
...
82-
})
83-
export class PizzaPartyAppModule { }
84-
```
51+
Let's display a slider component in your app and verify that everything works.
8552

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).
53+
You need to import the `MatSliderModule` that you want to display by adding the following lines to your app.module.ts file.
8754

8855
```ts
89-
import {MatButtonModule} from '@angular/material/button';
90-
import {MatCheckboxModule} from '@angular/material/checkbox';
91-
92-
@NgModule({
93-
imports: [MatButtonModule, MatCheckboxModule],
94-
exports: [MatButtonModule, MatCheckboxModule],
56+
import { MatSliderModule } from '@angular/material';
57+
…
58+
@NgModule ({....
59+
imports: [...,
60+
MatSliderModule,
61+
…]
9562
})
96-
export class MyOwnCustomMaterialModule { }
9763
```
9864

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.
101-
102-
### Step 4: Include a theme
103-
104-
Including a theme is **required** to apply all of the core and theme styles to your application.
65+
Add the `<mat-slider>` tag to the `app.component.html` like so:
10566

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";
67+
```html
68+
<mat-slider min="1" max="100" step="1" value="1"></mat-slider>
11069
```
11170

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).
117-
118-
### Step 5: Gesture Support
119-
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.
123-
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.
127-
128-
To install via npm, use the following command:
71+
Run your local dev server:
12972

130-
#### NPM
13173
```bash
132-
npm install --save hammerjs
74+
ng serve
13375
```
13476

135-
#### Yarn
136-
```bash
137-
yarn add hammerjs
138-
```
77+
and point your browser to [http://localhost:4200](http://localhost:4200)
13978

140-
After installing, import it on your app's entry point (e.g. `src/main.ts`).
141-
```ts
142-
import 'hammerjs';
143-
```
79+
You should see the material slider component on the page.
14480

145-
### Step 6 (Optional): Add Material Icons
81+
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.
14682

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`.
14983

150-
```html
151-
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
152-
```
153-
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
84+
### Appendix: Installing [HammerJS](http://hammerjs.github.io/)
16185

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.
86+
HammerJS can be installed using the following npm command:
16487

165-
The `@angular/cdk` package is organized of multiple entry-points.
166-
Each of these entry-points must be registered individually with SystemJS.
167-
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-
});
191-
```
88+
```bash
89+
npm install --save hammerjs
90+
```
19291

92+
After installing, import it on your app's entry point (e.g. `src/main.ts`).
19393

194-
### Example Angular Material projects
195-
- [material.angular.io](https://material.angular.io) -
196-
We build our own documentation with Angular Material!
94+
```ts
95+
import 'hammer.js';
96+
```

0 commit comments

Comments
 (0)