From c2d67be07d2a73cc1fc8a81463339370128bdf70 Mon Sep 17 00:00:00 2001 From: Manu Murthy Date: Wed, 31 Jul 2019 13:31:44 -0700 Subject: [PATCH 1/4] docs: rewrite getting started guide to use CLI schematics --- guides/getting-started.md | 207 ++++++++++---------------------------- 1 file changed, 55 insertions(+), 152 deletions(-) diff --git a/guides/getting-started.md b/guides/getting-started.md index 0ecbbcf670ea..281f1358866a 100644 --- a/guides/getting-started.md +++ b/guides/getting-started.md @@ -1,196 +1,99 @@ -For help getting started with a new Angular app, check out the -[Angular CLI](https://cli.angular.io/). +# Getting Started with Angular Material -For existing apps, follow these steps to begin using Angular Material. +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. -### Step 1: Install Angular Material, Angular CDK and Angular Animations +### New to Angular ? -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. +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). -#### NPM -```bash -npm install --save @angular/material @angular/cdk @angular/animations -``` -#### Yarn -```bash -yarn add @angular/material @angular/cdk @angular/animations -``` - - -#### Alternative 1: Snapshot Build +For existing applications, follow the steps below to begin using Angular Material: -A snapshot build with the latest changes from master is also available. Note that this snapshot -build should not be considered stable and may break between releases. -#### NPM -```bash -npm install --save angular/material2-builds angular/cdk-builds angular/animations-builds -``` - -#### Yarn -```bash -yarn add angular/material2-builds angular/cdk-builds angular/animations-builds -``` -#### Alternative 2: Angular Devkit 6+ +### Step 1: Install Angular Material npm packages -Using the Angular CLI `ng add` command will update your Angular project with the correct dependencies, perform configuration changes and execute initialization code. +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: ```bash ng add @angular/material ``` -### Step 2: Configure animations +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: -Once the animations package is installed, import `BrowserAnimationsModule` into your application to enable animations support. +1. Choose a prebuilt theme name, or "custom" for a custom theme: -```ts -import {BrowserAnimationsModule} from '@angular/platform-browser/animations'; + 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). -@NgModule({ - ... - imports: [BrowserAnimationsModule], - ... -}) -export class PizzaPartyAppModule { } -``` +2. Set up HammerJS for gesture recognition: -Alternatively, you can disable animations by importing `NoopAnimationsModule`. + [HammerJS](http://hammerjs.github.io/) provides gesture recognition capabilities required by some components (`mat-slide-toggle`, `mat-slider`, `matToolTip`). -```ts -import {NoopAnimationsModule} from '@angular/platform-browser/animations'; + Please note, if you choose not to install HammerJS it can be installed later via npm using the following command: -@NgModule({ - ... - imports: [NoopAnimationsModule], - ... -}) -export class PizzaPartyAppModule { } -``` + #### NPM -### Step 3: Import the component modules + ```bash + npm install --save hammerjs + ``` -Import the NgModule for each component you want to use: + #### Yarn -```ts -import {MatButtonModule} from '@angular/material/button'; -import {MatCheckboxModule} from '@angular/material/checkbox'; + ```bash + yarn add hammerjs + ``` -@NgModule({ - ... - imports: [MatButtonModule, MatCheckboxModule], - ... -}) -export class PizzaPartyAppModule { } -``` + After installing, import it on your app's entry point (e.g. `src/main.ts`). -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). + ```ts + import 'hammer.js'; + ``` -```ts -import {MatButtonModule} from '@angular/material/button'; -import {MatCheckboxModule} from '@angular/material/checkbox'; +3. Set up browser animations for Angular Material: -@NgModule({ - imports: [MatButtonModule, MatCheckboxModule], - exports: [MatButtonModule, MatCheckboxModule], -}) -export class MyOwnCustomMaterialModule { } -``` + 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. -Whichever approach you use, be sure to import the Angular Material modules _after_ Angular's -`BrowserModule`, as the import order matters for NgModules. +The `ng add` command will additionally perform the following configurations: -### Step 4: Include a theme +* Add project dependencies to `package.json` +* Add the Roboto font to your `index.html` +* Add the Material Design icon font to your `index.html` +* Add a few global CSS styles to: + * Remove margins from `body` + * Set `height: 100%` on `html` and `body` + * Set Roboto as the default application font -Including a theme is **required** to apply all of the core and theme styles to your application. +You're done! Angular Material is now configured to be used in your application. -To get started with a prebuilt theme, include one of Angular Material's prebuilt themes globally -in your application. If you're using the Angular CLI, you can add this to your `styles.css`: -```css -@import "~@angular/material/prebuilt-themes/indigo-pink.css"; -``` - -If you are not using the Angular CLI, you can include a prebuilt theme via a `` element in -your `index.html`. - -For more information on theming and instructions on how to create a custom theme, see the -[theming guide](./theming.md). -### Step 5: Gesture Support +### Step 2: Display an example Angular Material component -Some components (`mat-slide-toggle`, `mat-slider`, `matTooltip`) 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. +Let's display a slider component in your app and verify that everything works. -You can add HammerJS to your application via [npm](https://www.npmjs.com/package/hammerjs), a CDN -(such as the [Google CDN](https://developers.google.com/speed/libraries/#hammerjs)), or served -directly from your app. +You need to import the `MatSliderModule` that you want to display by adding the following lines to your app.module.ts file. -To install via npm, use the following command: - -#### NPM -```bash -npm install --save hammerjs -``` - -#### Yarn -```bash -yarn add hammerjs -``` - -After installing, import it on your app's entry point (e.g. `src/main.ts`). ```ts -import 'hammerjs'; +import { MatSliderModule } from '@angular/material'; +… +@NgModule ({.... + imports: [..., + MatSliderModule, +…] +}) ``` -### Step 6 (Optional): Add Material Icons - -If you want to use the `mat-icon` component with the official -[Material Design Icons](https://material.io/icons/), load the icon font in your `index.html`. +Add the `` tag to the `app.component.html` like so: ```html - + ``` -For more information on using Material Icons, check out the -[Material Icons Guide](https://google.github.io/material-design-icons/). - -Note that `mat-icon` supports any font or svg icons; using Material Icons is one of many options. - - -### Appendix: Configuring SystemJS - -If your project is using SystemJS for module loading, you will need to add `@angular/material` and -`@angular/cdk` to the SystemJS configuration. - -The `@angular/cdk` package is organized of multiple entry-points. -Each of these entry-points must be registered individually with SystemJS. +Run your local dev server: -Here is a example configuration where `@angular/material`, `@angular/cdk/platform` and -`@angular/cdk/a11y` are used: - - -```js -System.config({ - // Existing configuration options - map: { - // ... - '@angular/material': 'npm:@angular/material/bundles/material.umd.js', - - // CDK individual packages - '@angular/cdk/platform': 'npm:@angular/cdk/bundles/cdk-platform.umd.js', - '@angular/cdk/a11y': 'npm:@angular/cdk/bundles/cdk-a11y.umd.js', - // ... - 'hammerjs': 'npm:hammerjs', - }, - packages: { - //... - hammerjs: {main: './hammer.min.js', defaultExtension: 'js'} - //... - } -}); +```bash +ng serve ``` +and point your browser to [http://localhost:4200](http://localhost:4200) + +You should see the material slider component on the page. -### Example Angular Material projects -- [material.angular.io](https://material.angular.io) - -We build our own documentation with Angular Material! +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. From 452cb59afe218ebdddd4248a2b20bcdd6a3f95f0 Mon Sep 17 00:00:00 2001 From: Manu Murthy Date: Thu, 22 Aug 2019 11:45:54 -0700 Subject: [PATCH 2/4] docs(Getting Started): Moving HammerJS install to appendix --- guides/getting-started.md | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/guides/getting-started.md b/guides/getting-started.md index 281f1358866a..2bafe533fc99 100644 --- a/guides/getting-started.md +++ b/guides/getting-started.md @@ -27,25 +27,7 @@ The `ng add` command will install Angular Material, the [Component Dev Kit (CDK) [HammerJS](http://hammerjs.github.io/) provides gesture recognition capabilities required by some components (`mat-slide-toggle`, `mat-slider`, `matToolTip`). - Please note, if you choose not to install HammerJS it can be installed later via npm using the following command: - - #### NPM - - ```bash - npm install --save hammerjs - ``` - - #### Yarn - - ```bash - yarn add hammerjs - ``` - - After installing, import it on your app's entry point (e.g. `src/main.ts`). - - ```ts - import 'hammer.js'; - ``` + Please note, if you choose not to install HammerJS it can be installed later (see Appendix). 3. Set up browser animations for Angular Material: @@ -97,3 +79,18 @@ and point your browser to [http://localhost:4200](http://localhost:4200) You should see the material slider component on the page. 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. + + +Appendix: Installing [HammerJS](http://hammerjs.github.io/) + +HammerJS can be installed using the following npm command: + + ```bash + npm install --save hammerjs + ``` + + After installing, import it on your app's entry point (e.g. `src/main.ts`). + + ```ts + import 'hammer.js'; + ``` \ No newline at end of file From 60efb40e90a2f2ecc3c4cb2fb9b3792dea1da0b6 Mon Sep 17 00:00:00 2001 From: Manu Murthy Date: Thu, 22 Aug 2019 11:49:20 -0700 Subject: [PATCH 3/4] docs(Getting Started): Moving HammerJS install to appendix --- guides/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/getting-started.md b/guides/getting-started.md index 2bafe533fc99..165dc67ffc93 100644 --- a/guides/getting-started.md +++ b/guides/getting-started.md @@ -81,7 +81,7 @@ You should see the material slider component on the page. 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. -Appendix: Installing [HammerJS](http://hammerjs.github.io/) +###Appendix: Installing [HammerJS](http://hammerjs.github.io/) HammerJS can be installed using the following npm command: From 22c0fa418ce2350d04ca6a8ef0e8d57570856b69 Mon Sep 17 00:00:00 2001 From: Manu Murthy Date: Thu, 22 Aug 2019 11:49:48 -0700 Subject: [PATCH 4/4] docs(Getting Started): Moving HammerJS install to appendix --- guides/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/getting-started.md b/guides/getting-started.md index 165dc67ffc93..7c0ba38342c3 100644 --- a/guides/getting-started.md +++ b/guides/getting-started.md @@ -81,7 +81,7 @@ You should see the material slider component on the page. 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. -###Appendix: Installing [HammerJS](http://hammerjs.github.io/) +### Appendix: Installing [HammerJS](http://hammerjs.github.io/) HammerJS can be installed using the following npm command: