Skip to content

Commit 20ee360

Browse files
mmalerbajelbourn
mmalerba
authored and
jelbourn
committed
docs(input): update docs to describe md-input-container rather than md-input (#2256)
* Update input docs and add note that md-input and md-sidenav-layout are deprecated. * style fix * use bold since github doesn't like color
1 parent 2d24383 commit 20ee360

File tree

3 files changed

+140
-108
lines changed

3 files changed

+140
-108
lines changed

‎src/lib/input/README.md‎

Lines changed: 135 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,155 +1,183 @@
1-
# mdInput / mdTextarea
1+
**NOTE: The <code>md-input</code> element is deprecated. <code>md-input-container</code> should be
2+
used instead.**
23

3-
Inputs are the basic input component of Material 2. The spec can be found [here](https://www.google.com/design/spec/components/text-fields.html).
4+
# md-input-container
45

6+
Inputs are the basic input component of Material 2. The spec can be found
7+
[here](https://www.google.com/design/spec/components/text-fields.html). `md-input-container` acts as
8+
a wrapper for native `input` and `textarea` elements. The native element wrapped by the
9+
`md-input-container` must be marked with the `md-input` directive.
510

11+
Simple `input` example:
12+
```html
13+
<md-input-container>
14+
<input md-input>
15+
</md-input-container>
16+
```
617

7-
## Notes
8-
* The `<md-input>` / `<md-textarea>` component fully support two-way binding of `ngModel`, as if it was a normal `<input>` and `<textarea>`.
9-
10-
18+
Simple `textarea` example:
19+
```html
20+
<md-input-container>
21+
<textarea md-input></textarea>
22+
</md-input-container>
23+
```
1124

12-
## Type
25+
## Usage
1326

14-
At the time of writing this README, the `[type]` attribute is copied to the actual `<input>` element in the `<md-input>`.
27+
### `input` and `textarea` attributes
1528

16-
The valid `type` attribute values are any supported by your browser, with the exception of `file`, `checkbox` and `radio`. File inputs aren't supported for now, while check boxes and radio buttons have their own components.
29+
All of the attributes that can be used with normal `input` and `textarea` elements can be used on
30+
elements within the `md-input-container` as well. This includes angular specific ones such as
31+
`ngModel` and `formControl`.
1732

33+
The only limitations are that the `type` attribute can only be one of the values supported by
34+
`md-input-container` and the native element cannot specify a `placeholder` attribute if the
35+
`md-input-container` also contains a `md-placeholder` element.
1836

19-
## Placeholder
37+
#### Supported `input` types
2038

21-
A placeholder is an indicative text displayed in the input zone when the input does not contain text. When text is present, the indicative text will float above this input zone.
39+
The following [input types](http://www.w3schools.com/TAGs/att_input_type.asp) can be used with
40+
`md-input-container`:
41+
* date
42+
* datetime-local
43+
* email
44+
* month
45+
* number
46+
* password
47+
* search
48+
* tel
49+
* text
50+
* time
51+
* url
52+
* week
2253

23-
You can set the `floatingPlaceholder` attribute to `false` to hide the indicative text instead when text is present in the input.
54+
### Placeholder
2455

25-
You can specify a placeholder for the input in one of two ways; either using the `placeholder` attribute, or using an `<md-placeholder>` directive in the `<md-input>`. Using both will raise an error.
56+
A placeholder is an indicative text displayed in the input zone when the input does not contain
57+
text. When text is present, the indicative text will float above this input zone.
2658

59+
You can set the `floatingPlaceholder` attribute of `md-input-container` to `false` to hide the
60+
indicative text instead when text is present in the input.
2761

28-
## Prefix and Suffix
62+
You can specify a placeholder for the input in one of two ways; either using the `placeholder`
63+
attribute on the `input` or `textarea`, or using an `md-placeholder` element in the
64+
`md-input-container`. Using both will raise an error.
2965

30-
You can include HTML before, and after the input tag, as prefix or suffix. It will be underlined as per the Material specification, and clicking it will focus the input.
66+
### Prefix and Suffix
3167

32-
To add a prefix, use the `md-prefix` attribute on the element. Similarly, to add a suffix, use the `md-suffix` attribute. For example, in a template:
68+
You can include HTML before, and after the input tag, as prefix or suffix. It will be underlined as
69+
per the Material specification, and clicking it will focus the input.
3370

34-
#### Example
71+
To add a prefix, use the `md-prefix` attribute on the element. Similarly, to add a suffix, use the
72+
`md-suffix` attribute. For example, in a template:
3573

3674
```html
37-
<md-input placeholder="amount" align="end">
75+
<md-input-container align="end">
76+
<input md-input placeholder="amount">
3877
<span md-prefix>$&nbsp;</span>
3978
<span md-suffix>.00</span>
40-
</md-input>
79+
</md-input-container>
4180
```
4281

43-
Will result in this:
44-
4582
<img src="https://material.angularjs.org/material2_assets/input/prefix-suffix.png">
4683

84+
### Hint Labels
4785

86+
Hint labels are the labels that show below the underline. You can have up to two hint labels; one on
87+
the `start` of the line (left in an LTR language, right in RTL), and one on the `end`.
4888

49-
## Hint Labels
50-
51-
Hint labels are the labels that shows the underline. You can have up to two hint labels; one on the `start` of the line (left in an LTR language, right in RTL), or one on the `end`.
52-
53-
You specify a hint-label in one of two ways; either using the `hintLabel` attribute, or using an `<md-hint>` directive in the `<md-input>`, which takes an `align` attribute containing the side. The attribute version is assumed to be at the `start`.
54-
89+
You specify a hint label in one of two ways; either using the `hintLabel` attribute of
90+
`md-input-container`, or using an `md-hint` element inside the `md-input-container`, which takes an
91+
`align` attribute containing the side. The attribute version is assumed to be at the `start`.
5592
Specifying a side twice will result in an exception during initialization.
5693

57-
#### Example
58-
59-
A simple character counter can be made like the following:
60-
94+
For example, a simple character counter can be made like the following:
6195
```html
62-
<md-input placeholder="Character count (100 max)" maxlength="100" class="demo-full-width"
63-
value="Hello world. How are you?"
64-
#characterCountHintExample>
65-
<md-hint align="end">{{characterCountHintExample.characterCount}} / 100</md-hint>
66-
</md-input>
96+
<md-input-container>
97+
<input md-input
98+
placeholder="Character count (100 max)"
99+
maxlength="100"
100+
value="Hello world. How are you?"
101+
#characterCountHintExample>
102+
<md-hint align="end">{{characterCountHintExample.value.length}} / 100</md-hint>
103+
</md-input-container>
67104
```
68105

69106
<img src="https://material.angularjs.org/material2_assets/input/character-count.png">
70107

108+
### Divider Color
71109

72-
73-
## Divider Color
74-
75-
The divider (line under the `<md-input>` content) color can be changed by using the `dividerColor` attribute. A value of `primary` is the default and will correspond to your theme primary color. Alternatively, you can specify `accent` or `warn`.
76-
77-
#### Example
78-
79-
^((please note that this example has been doctored to show the colors; they would normally show only on focus)^)
80-
81-
<img src="https://material.angularjs.org/material2_assets/input/divider-colors.png">
82-
83-
84-
85-
## Labelling
86-
87-
You can label the `<md-input>` as you would a regular `<input>`.
88-
89-
## Focus
90-
91-
You can put the focus on an input component using the `focus()` method.
92-
93-
### Example
110+
The divider (line under the `input` content) color can be changed by using the `dividerColor`
111+
attribute of `md-input-container`. A value of `primary` is the default and will correspond to your
112+
theme primary color. Alternatively, you can specify `accent` or `warn`.
94113

95114
```html
96-
<md-input #nameInput placeholder="name"></md-input>
115+
<md-input-container>
116+
<input md-input placeholder="Default color" value="example">
117+
</md-input-container>
118+
<md-input-container dividerColor="accent">
119+
<input md-input placeholder="Accent color" value="example">
120+
</md-input-container>
121+
<md-input-container dividerColor="warn">
122+
<input md-input placeholder="Warn color" value="example">
123+
</md-input-container>
97124
```
98125

99-
```ts
100-
export class MyComponent implements AfterViewInit {
101-
@ViewChild('nameInput') nameInput: MdInput;
126+
_please note that this image has been doctored to show each `input` as if it were focused:_
127+
<img src="https://material.angularjs.org/material2_assets/input/divider-colors.png">
102128

103-
ngAfterViewInit() {
104-
this.nameInput.focus();
105-
}
106-
}
107-
```
129+
### Full Forms
108130

109-
## Textareas
131+
You can make a full form using inputs, and they will support autofill natively.
110132

111133
```html
112-
<md-textarea placeholder="Textarea with autosize"></md-textarea>
134+
<form>
135+
<md-input-container style="width: 100%">
136+
<input md-input placeholder="Company (disabled)" disabled value="Google">
137+
</md-input-container>
138+
139+
<table style="width: 100%" cellspacing="0"><tr>
140+
<td><md-input-container style="width: 100%">
141+
<input md-input placeholder="First name">
142+
</md-input-container></td>
143+
<td><md-input-container style="width: 100%">
144+
<input md-input placeholder="Long Last Name That Will Be Truncated">
145+
</md-input-container></td>
146+
</tr></table>
147+
148+
<p>
149+
<md-input-container width="100%">
150+
<textarea md-input placeholder="Address" value="1600 Amphitheatre Pkway"></textarea>
151+
</md-input-container>
152+
<md-input-container width="100%">
153+
<textarea md-input placeholder="Address 2"></textarea>
154+
</md-input-container>
155+
</p>
156+
157+
<table style="width: 100%" cellspacing="0"><tr>
158+
<td><md-input-container width="100%">
159+
<input md-input placeholder="City">
160+
</md-input-container></td>
161+
<td><md-input-container width="100%">
162+
<input md-input placeholder="State">
163+
</md-input-container></td>
164+
<td><md-input-container width="100%">
165+
<input md-input #postalCode maxlength="5" placeholder="Postal Code" value="94043">
166+
<md-hint align="end">{{postalCode.value.length}} / 5</md-hint>
167+
</md-input-container></td>
168+
</tr></table>
169+
</form>
113170
```
114171

115-
### Example
116-
117-
## Full Forms
118-
119-
You can make a full form using inputs, and it will support autofill natively.
120-
121-
#### Example
172+
<img src="https://material.angularjs.org/material2_assets/input/full-form.png">
122173

123-
```html
124-
<md-card class="demo-card demo-basic">
125-
<md-toolbar color="primary">Basic</md-toolbar>
126-
<md-card-content>
127-
<form>
128-
<md-input class="demo-full-width" placeholder="Company (disabled)" disabled value="Google">
129-
</md-input>
130-
131-
<table style="width: 100%" cellspacing="0"><tr>
132-
<td><md-input placeholder="First name" style="width: 100%"></md-input></td>
133-
<td><md-input placeholder="Long Last Name That Will Be Truncated" style="width: 100%"></md-input></td>
134-
</tr></table>
135-
<p>
136-
<md-textarea class="demo-full-width" placeholder="Address" value="1600 Amphitheatre Pkway"></md-textarea>
137-
<md-textarea class="demo-full-width" placeholder="Address 2"></md-textarea>
138-
</p>
139-
<table style="width: 100%" cellspacing="0"><tr>
140-
<td><md-input class="demo-full-width" placeholder="City"></md-input></td>
141-
<td><md-input class="demo-full-width" placeholder="State"></md-input></td>
142-
<td><md-input #postalCode class="demo-full-width" maxlength="5"
143-
placeholder="Postal Code"
144-
value="94043">
145-
<md-hint align="end">{{postalCode.characterCount}} / 5</md-hint>
146-
</md-input></td>
147-
</tr></table>
148-
</form>
149-
</md-card-content>
150-
</md-card>
151-
```
174+
## API Summary
152175

153-
Will result in this:
176+
### Inputs
154177

155-
<img src="https://material.angularjs.org/material2_assets/input/full-form.png">
178+
| Name | Type | Description |
179+
| --- | --- | --- |
180+
| `align` | `"start" | "end"` | The alignment of the `input` or `textarea`. Default = `"start"`. |
181+
| `dividerColor` | `"primary" | "accent" | "warn"` | The color of the placeholder and underline. Default = `"primary"`. |
182+
| `floatingPlaceholder` | boolean | Whether the placeholder should float above the input after text is entered. Default = `true`. |
183+
| `hintLabel` | string | The hint text to show on the start end of the `md-input-container`. |

‎src/lib/sidenav/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
**NOTE: The <code>md-sidenav-layout</code> element is deprecated. <code>md-sidenav-container</code>
2+
should be used instead.**
3+
4+
15
# MdSidenav
26

37
MdSidenav is the side navigation component for Material 2. It is composed of two components: `<md-sidenav-container>` and `<md-sidenav>`.

‎src/lib/slider/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ right-to-left languages.
132132
| `max` | number | Optional, the maximum number for the slider. Default = `100`. |
133133
| `step` | number | Optional, declares where the thumb will snap to. Default = `1`. |
134134
| `value` | number | Optional, the value to start the slider at. |
135-
| `tick-interval` | `"auto" | number` | Optional, how many steps between tick marks. |
135+
| `tick-interval` | `"auto"` \| number | Optional, how many steps between tick marks. |
136136
| `invert` | boolean | Optional, whether to invert the axis the thumb moves along. |
137137
| `vertical` | boolean | Optional, whether the slider should be oriented vertically. |
138138
| `disabled` | boolean | Optional, whether or not the slider is disabled. Default = `false`. |

0 commit comments

Comments
 (0)