Skip to content

docs(getting-started): revise docs #3523

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 10, 2017
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 38 additions & 43 deletions guides/getting-started.md
Original file line number Diff line number Diff line change
@@ -1,45 +1,42 @@
Get started with Angular Material using the Angular CLI.
For help getting started with a new Angular app, check out the [Angular CLI](https://cli.angular.io/).

## Install Angular CLI

```bash
npm install -g @angular/cli
```

## Create a new project

```bash
ng new my-project
```

The new command creates a project with a build system for your Angular app.
For existing apps, follow these steps to begin using Angular Material.

## Install Angular Material components
## Step 1: Install Angular Material

```bash
npm install --save @angular/material
```

## Import the Angular Material NgModule
## Step 2: Import the Module

Add MaterialModule as an import in your app's root NgModule.

**src/app/app.module.ts**
```ts
import { MaterialModule } from '@angular/material';
// other imports

@NgModule({
...
imports: [MaterialModule],
...
})
export class PizzaPartyAppModule { }
```

## Include the core and theme styles:
This is **required** to apply all of the core and theme styles to your application. You can either
use a pre-built theme, or define your own custom theme.
## Step 3: Include Theming

Including a theme is **required** to apply all of the core and theme styles to your application.

To get started with a prebuilt theme, include the following in your app's index.html:

```html
<link href="node_modules/@angular/material/core/theming/prebuilt/indigo-pink.css" rel="stylesheet">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One potential caveat is that node_modules might be in a different location relative to the serving root. Maybe it needs a small note like "Path may be different depending on your project structure".

```

For information on other prebuilt themes, or help building your own theme, check out the [theming guide](./theming.md).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about "For more information on theming and instructions on how to create a custom theme, see the [theming guide]"


:trident: See the [theming guide](./theming.md) for instructions.
## Step 4 (Optional): Gesture Support
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't explicitly mark this as optional since slider won't work at all without it. It's more "This is required for some components but we're tolerant of it being missing."


### Additional setup for gestures
Some components (`md-slide-toggle`, `md-slider`, `mdTooltip`) rely on
[HammerJS](http://hammerjs.github.io/) for gestures. In order to get the full feature-set of these
components, HammerJS must be loaded into the application.
Expand All @@ -48,42 +45,40 @@ You can add HammerJS to your application via [npm](https://www.npmjs.com/package
(such as the [Google CDN](https://developers.google.com/speed/libraries/#hammerjs)), or served
directly from your app.

#### If you want to include HammerJS from npm, you can install it:

```bash
npm install --save hammerjs
```

After installing, import HammerJS on your app's module.
**src/app/app.module.ts**
After installing HammerJS, import it on your app's root module.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the "If you want to use npm" qualification is important to keep

```ts
import 'hammerjs';
```

## Step 5 (Optional): Add Material Icons

If you want your `md-icon` components to use [Material Icons](https://material.io/icons/), load the font in your `index.html`.

```html
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
```

For more information on using Material Icons, check out the [Material Icons Guide](https://google.github.io/material-design-icons/).

Note that `md-icon` has support for any font or svg icons, so using Material Icons is just one option.


## Configuring SystemJS

If your project is using SystemJS for module loading, you will need to add `@angular/material`
to the SystemJS configuration:

```js
System.config({
// existing configuration options
map: {
...,
'@angular/material': 'npm:@angular/material/bundles/material.umd.js'
...
'@angular/material': 'npm:@angular/material/bundles/material.umd.js',
...
}
});
```

### [Optional] Using Material Design icons with `md-icon`:

- If you want to use Material Design icons in addition to Angular Material components,
load the Material Design font in your `index.html`.
`md-icon` supports any font icons or svg icons, so this is only one option for an icon source.

**src/index.html**
```html
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
```

## Sample Angular Material projects
- [Material Sample App](https://github.com/jelbourn/material2-app)
Expand Down