Skip to content
This repository was archived by the owner on Oct 7, 2020. It is now read-only.

Commit f6cdba1

Browse files
trimoxtrimox
authored
docs: Add getting started walkthrough + developer guide (#41)
* Add `developer.md` guide * Update `getting-started.md` * Update `README.md`
1 parent 8e1272a commit f6cdba1

File tree

3 files changed

+139
-33
lines changed

3 files changed

+139
-33
lines changed

‎README.md

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,28 @@
99
Our Angular library integrates with [Google's Material Design Components](https://material.io/components/), providing a faithful and accurate representation of Material Design as it is envisioned on the web platform by Google's Material Design team. Our goal is to equip Angular developers with modular, straightforward and production-ready Material Design components.
1010

1111
### Quick Links
12-
* [Contributing](https://github.com/trimox/angular-mdc-web/blob/master/CONTRIBUTING.md)
1312
* [Changelog](https://github.com/trimox/angular-mdc-web/blob/master/CHANGELOG.md)
13+
* [Contributing](https://github.com/trimox/angular-mdc-web/blob/master/CONTRIBUTING.md)
14+
* [Developer guide](https://github.com/trimox/angular-mdc-web/blob/master/docs/developer.md)
15+
* [Demo App](https://trimox.github.io/angular-mdc-web/)
16+
* [Getting Started guide](https://github.com/trimox/angular-mdc-web/blob/master/docs/getting-started.md)
1417
* [Gitter Chat](https://gitter.im/angular-mdc/Lobby)
18+
* [StackOverflow](https://stackoverflow.com/questions/tagged/angular-mdc) `tag: angular-mdc`
1519

16-
## Installation
20+
## Install Angular MDC
1721
```
1822
npm install --save @angular-mdc/web
1923
```
2024

25+
## Updating Angular MDC version
26+
```
27+
npm update
28+
```
29+
2130
## Getting started
2231
Check out our [Getting Started guide](https://github.com/trimox/angular-mdc-web/blob/master/docs/getting-started.md) to begin adopting Angular MDC in your project.
2332

24-
### Material Design Components
33+
## Material Design Components
2534
* WIP = work in progress
2635
* TBI = to be implemented
2736

@@ -30,13 +39,13 @@ Check out our [Getting Started guide](https://github.com/trimox/angular-mdc-web/
3039
| button | Available |
3140
| card | Available |
3241
| checkbox | Available |
33-
| dialog | TBI |
34-
| drawer | TBI |
42+
| dialog | WIP |
43+
| drawer | WIP |
3544
| elevation | Available |
3645
| fab | Available |
3746
| form-field | Available |
3847
| grid-list | TBI |
39-
| icon-toggle | TBI |
48+
| icon-toggle | WIP |
4049
| linear-progress | Available |
4150
| list | TBI |
4251
| menu | Available |
@@ -52,18 +61,15 @@ Check out our [Getting Started guide](https://github.com/trimox/angular-mdc-web/
5261
| toolbar | Available |
5362
| typography | Available |
5463

55-
## Running the demo app
56-
57-
Clone and install repo:
58-
```
59-
git clone https://github.com/trimox/angular-mdc-web.git && cd angular-mdc-web
60-
npm i
61-
```
62-
63-
Run the webpack development server (content served from `src/demo-app/`):
64-
```
65-
cd /path/to/angular-mdc-web
66-
npm run start
67-
open http://localhost:4000
68-
```
64+
## Developing Angular MDC
65+
Want to develop your own components or change existing ones? Check out our [Developer guide](https://github.com/trimox/angular-mdc-web/blob/master/docs/developer.md).
6966

67+
## Browser Support
68+
We officially support the last two versions of every major browser.
69+
* Chrome
70+
* Safari
71+
* Firefox
72+
* IE 11/Edge
73+
* Opera
74+
* Mobile Safari
75+
* Chrome on Android

‎docs/developer.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Developing for Angular MDC
2+
3+
- [Infrastructure and Tooling](#tools)
4+
- [Setup your development environment](#setup)
5+
- [Running the Development Server](#dev-server)
6+
- [Linting / Testing](#lint)
7+
- [Building](#build)
8+
- [Code Style](#code-style)
9+
- [Submit Pull Request](#pull-req)
10+
11+
## <a name="tools"></a> Infrastructure and Tooling
12+
13+
Build System
14+
- [Rollup](https://github.com/rollup/rollup)
15+
* Provides next-generation ES6 module bundling.
16+
17+
Development Server
18+
- [WebPack](https://webpack.js.org/)
19+
- Fast, modern development environment (incremental compilation, source maps, live reloading, etc.)
20+
21+
## <a name="setup"></a> Setup up your development environment
22+
You'll need a recent version of nodejs.
23+
```
24+
npm i npm@latest -g
25+
```
26+
Once node is installed, simply clone our repo (or your fork of it) and install developer dependencies.
27+
```
28+
git clone https://github.com/trimox/angular-mdc-web.git # or a path to your fork
29+
cd angular-mdc-web
30+
npm i # Install developer dependencies
31+
```
32+
33+
## <a name="dev-server"></a> Running the development server
34+
Run a webpack-dev-server instance that should assist with initial development. (content served from `src/demo-app/`)
35+
```
36+
cd /path/to/angular-mdc-web
37+
npm run start
38+
```
39+
Open your browser to http://localhost:4000
40+
41+
## <a name="lint"></a> Linting / Testing
42+
```
43+
npm run lint:ts # Lints typescript using tslint
44+
npm run lint:css # Lints (S)CSS using stylelint
45+
npm run lint # Runs both of the above commands in parallel
46+
```
47+
48+
## <a name="build"></a> Building Angular MDC
49+
```
50+
npm run build # Builds Angular MDC inside of dist/
51+
```
52+
53+
## <a name="code-style"></a> Code Style
54+
Our entire coding style is enforced automatically through the use of linters. We also follow [Google's JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html).
55+
* [tslint rules](https://github.com/trimox/angular-mdc-web/blob/master/tslint.json)
56+
* [stylelint config](https://github.com/trimox/angular-mdc-web/blob/master/.stylelint-config.yaml)
57+
58+
## <a name="pull-req"></a> Submit a Pull Request
59+
When submitting PRs, make sure you're following our commit message conventions; our commit-msg hook should automatically enforce this. We also use [commitizen](https://www.npmjs.com/package/commitizen), which you can use to auto-format commit messages for you.
60+
61+
When submitting PRs for large changes, be sure to include an adequate background in the description so that reviewers of the PR know what the changes entail at a high-level, the motivations for making these changes, and what they affect.

‎docs/getting-started.md

Lines changed: 52 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,21 @@
1-
# Getting Started
1+
Follow these steps to begin begin adopting Angular MDC.
22

3-
### Install Angular MDC
3+
- [Step 1 - Install Angular MDC](#step1)
4+
- [Step 2 - Import Components](#step2)
5+
- [Step 3 - MDC Theme](#step3)
6+
- [Step 4 - Material Design Icons](#step4)
7+
- [Step 5 - Roboto Font](#step5)
8+
- [Step 6 - Typography](#step6)
9+
- [Appendix - Sample index.html](#sample-html)
10+
- [Appendix - Configuring SystemJS](#config-systemjs)
11+
12+
## <a name="step1"></a> Step 1: Install Angular MDC
413
```
514
npm install --save @angular-mdc/web
615
```
716

8-
### Include all components
17+
## <a name="step2"></a> Step 2: Import Components
18+
### All components
919
```ts
1020
import { MaterialModule } from '@angular-mdc/web';
1121

@@ -17,7 +27,7 @@ import { MaterialModule } from '@angular-mdc/web';
1727
export class ExampleModule { }
1828
```
1929

20-
### Or choose individual components
30+
### Or individual components
2131
```ts
2232
import { FabModule, MenuModule } from '@angular-mdc/web';
2333

@@ -29,43 +39,72 @@ import { FabModule, MenuModule } from '@angular-mdc/web';
2939
export class ExampleModule { }
3040
```
3141

32-
### Include Material Design Components Theme (required)
33-
Apply the MDC theme to all core components.
42+
## <a name="step3"></a> Step 3: MDC Theme
43+
Including the MDC theme is required to apply all of the core and theme styles to your application.
44+
45+
If you're using the Angular CLI, you can add this to your styles.css:
3446
```ts
3547
@import "material-components-web/material-components-web";
3648
```
3749

38-
### Use Material Design Icons
50+
Alternatively, you can use a CDN.
51+
```html
52+
<link href="https://unpkg.com/material-components-web/dist/material-components-web.css" rel="stylesheet">
53+
```
54+
Or link directly to the node_modules file.
55+
```html
56+
<link href="node_modules/material-components-web/dist/material-components-web.css" rel="stylesheet">
57+
```
58+
59+
## <a name="step4"></a> Step 4: Material Design Icons
3960
Add the [Material Design Icons](https://material.io/icons/) collection to your `index.html`.
4061

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

45-
### Use Roboto Font
66+
## <a name="step5"></a> Step 5: Roboto Font
4667
Add the Roboto font with 300, 400 and 500 weights to your `index.html`.
4768

4869
```html
4970
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500" rel="stylesheet">
50-
```
51-
52-
### Apply MDC Typography
53-
Add the `mdc-typography` directive to your body element to define basic properties for text, such as the Roboto typeface and antialiasing settings.
71+
```
72+
73+
## <a name="step6"></a> Step 6: Typography (optional)
74+
Add the `mdc-typography` directive to your body element to define basic properties for text, such as the Roboto typeface and antialiasing settings throughout your app.
5475

5576
```html
5677
<body mdc-typography>
5778
```
5879

59-
### Sample index.html
80+
## <a name="sample-html"></a> Appendix: Sample index.html
6081
```html
6182
<!DOCTYPE html>
6283
<html>
6384
<head>
6485
<title>Angular MDC</title>
6586
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500" rel="stylesheet">
6687
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
88+
<link href="https://unpkg.com/material-components-web/dist/material-components-web.css" rel="stylesheet">
6789
</head>
6890
<body mdc-typography>
91+
<!--page content-->
6992
</body>
7093
</html>
7194
```
95+
96+
## <a name="config-systemjs"></a> Appendix: Configuring SystemJS
97+
98+
If your project is using SystemJS for module loading, you will need to add `@angular-mdc/web`
99+
to the SystemJS configuration:
100+
101+
```js
102+
System.config({
103+
// existing configuration options
104+
map: {
105+
// ...
106+
'@angular-mdc/web': 'npm:@angular-mdc/web/bundles/material.umd.js',
107+
// ...
108+
}
109+
});
110+
```

0 commit comments

Comments
 (0)