Skip to content

Commit 86041ab

Browse files
Manu Murthymanughub
Manu Murthy
authored and
manughub
committed
docs: rewrite getting started guide to use CLI schematics
1 parent 3ec531b commit 86041ab

File tree

1 file changed

+40
-163
lines changed

1 file changed

+40
-163
lines changed

‎guides/getting-started.md

Lines changed: 40 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -1,196 +1,73 @@
1-
For help getting started with a new Angular app, check out the
2-
[Angular CLI](https://cli.angular.io/).
1+
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.
32

4-
For existing apps, follow these steps to begin using Angular Material.
3+
### New to Angular ?
54

6-
### Step 1: Install Angular Material, Angular CDK and Angular Animations
5+
If you are new to Angular or getting started with a new Angular application, see [Getting Started](https://angular.io/start) and [Setting up your environment](https://angular.io/guide/setup-local
6+
).
77

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.
8+
For existing applications, follow the steps below to begin using Angular Material:
99

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
21-
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.
10+
### Step 1: Install Angular Material npm packages
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+
35-
36-
Using the Angular CLI `ng add` command will update your Angular project with the correct dependencies, perform configuration changes and execute initialization code.
12+
Use the Angular CLI's install [schematic](https://material.angular.io/guide/schematics) to setup your Angular Material project by running the following command:
3713

3814
```bash
3915
ng add @angular/material
4016
```
4117

42-
### Step 2: Configure animations
18+
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:
4319

44-
Once the animations package is installed, import `BrowserAnimationsModule` into your application to enable animations support.
20+
1. Choose a prebuilt theme name, or "custom" for a custom theme ?
21+
You can choose from [prebuilt material design themes](https://material.angular.io/guide/theming#using-a-pre-built-theme) or define an extensible custom theme.
4522

46-
```ts
47-
import {BrowserAnimationsModule} from '@angular/platform-browser/animations';
23+
2. Set up HammerJS for gesture recognition ?
24+
HammerJS provides [gesture recognition capabilities](https://material.angular.io/guide/getting-started#step-5-gesture-support) you can use in your apps. Angular Material requires HammerJS only for the mat-slider component.
4825

49-
@NgModule({
50-
...
51-
imports: [BrowserAnimationsModule],
52-
...
53-
})
54-
export class PizzaPartyAppModule { }
55-
```
26+
3. Set up browser animations for Angular Material?
27+
Importing the BrowserAnimationsModule into your application enables Angular's animation system. Omitting this will disable most of Angular Material's animations.
5628

57-
Alternatively, you can disable animations by importing `NoopAnimationsModule`.
29+
The ng add command will additionally perform the following configurations:
5830

59-
```ts
60-
import {NoopAnimationsModule} from '@angular/platform-browser/animations';
31+
* Ensure project dependencies are placed in package.json
32+
* Add Roboto fonts to your index.html
33+
* Add the Material Icon font to your index.html
34+
* Add global styles to:
35+
* Remove margins from body
36+
* Set height: 100% on html and body
37+
* Set Roboto as default application font
6138

62-
@NgModule({
63-
...
64-
imports: [NoopAnimationsModule],
65-
...
66-
})
67-
export class PizzaPartyAppModule { }
68-
```
39+
That's it. Angular Material is now configured to be used in your application.
6940

70-
### Step 3: Import the component modules
41+
### Step 2: Display an example Angular Material component
7142

72-
Import the NgModule for each component you want to use:
43+
Let's display a material slider component in your app and verify that everything works.
7344

74-
```ts
75-
import {MatButtonModule} from '@angular/material/button';
76-
import {MatCheckboxModule} from '@angular/material/checkbox';
77-
78-
@NgModule({
79-
...
80-
imports: [MatButtonModule, MatCheckboxModule],
81-
...
82-
})
83-
export class PizzaPartyAppModule { }
84-
```
85-
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).
45+
You need to import the material slider that you want to display by adding the following lines to your app.module.ts file.
8746

8847
```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],
48+
import { MatSliderModule } from '@angular/material';
49+
…
50+
@NgModule ({....
51+
Imports: [...,
52+
MatSliderModule,
53+
…]
9554
})
96-
export class MyOwnCustomMaterialModule { }
9755
```
9856

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.
57+
Add the <mat-slider> tag to the app.component.html like so:
10558

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";
59+
```html
60+
<mat-slider min="1"max="100"step="1"value="1"></mat-slider>
11061
```
11162

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:
129-
130-
#### NPM
131-
```bash
132-
npm install --save hammerjs
133-
```
63+
Run the following command:
13464

135-
#### Yarn
13665
```bash
137-
yarn add hammerjs
66+
ng serve
13867
```
13968

140-
After installing, import it on your app's entry point (e.g. `src/main.ts`).
141-
```ts
142-
import 'hammerjs';
143-
```
144-
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`.
149-
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
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.
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-
```
69+
and point your browser to [http://localhost:4200](http://localhost:4200)
19270

71+
You should see the material slider component on the page.
19372

194-
### Example Angular Material projects
195-
- [material.angular.io](https://material.angular.io) -
196-
We build our own documentation with Angular Material!
73+
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 components in your apps.

0 commit comments

Comments
 (0)