Skip to content

Commit 199404b

Browse files
iveysaurjelbourn
iveysaur
authored and
jelbourn
committed
chore(button-toggle): Add readme and package.json (#925)
* Add README to button toggle * Add dynamic example to README * Add package file * Reorganize readme and add more information * Add images * Add images the markdown way * Add a disabled example * Add disabled example image * Use ts and improve comments * Add fix missing space in sentence
1 parent 419208a commit 199404b

File tree

2 files changed

+184
-0
lines changed

2 files changed

+184
-0
lines changed

‎src/components/button-toggle/README.md

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# md-button-toggle
2+
3+
`MdButtonToggle` is a group of buttons that can be toggled.
4+
There are two modes, `multiple` and `exclusive`.
5+
When in 'exclusive' mode, only one button can be selected at a time (like radio buttons).
6+
When in 'multiple' mode, multiple buttons can be selected at once (like checkboxes).
7+
You can read more about button toggles in the
8+
[Material Design spec](https://material.google.com/components/buttons.html#buttons-toggle-buttons).
9+
10+
## Usage
11+
12+
### Setup
13+
14+
Importing the symbols:
15+
```ts
16+
import { MdUniqueSelectionDispatcher } from '@angular2-material/core';
17+
import { MD_BUTTON_TOGGLE_DIRECTIVES } from '@angular2-material/button-toggle'
18+
```
19+
20+
Adding providers and directives:
21+
```ts
22+
@Component({
23+
...
24+
directives: [MD_BUTTON_TOGGLE_DIRECTIVES],
25+
providers: [MdUniqueSelectionDispatcher]
26+
})
27+
```
28+
29+
### Basic Usage
30+
31+
`md-button-toggle` can be used on its own and acts as a checkbox.
32+
33+
```html
34+
<md-button-toggle>Bold</md-button-toggle>
35+
```
36+
37+
Output:
38+
39+
![Basic Toggle Button Example](https://material.angularjs.org/material2_assets/button-toggle/basic-toggle.png)
40+
41+
### Exclusive Selection
42+
43+
`md-button-toggle` can be used in an exclusive selection group when surrounded by
44+
`md-button-toggle-group`. This styles all buttons within the group to appear as a single
45+
group of button toggles and allows only one button toggle to be selected at a time.
46+
47+
```html
48+
<md-button-toggle-group name="alignment">
49+
<md-button-toggle value="left"><md-icon>format_align_left</md-icon></md-button-toggle>
50+
<md-button-toggle value="center"><md-icon>format_align_center</md-icon></md-button-toggle>
51+
<md-button-toggle value="right"><md-icon>format_align_right</md-icon></md-button-toggle>
52+
<md-button-toggle value="justify"><md-icon>format_align_justify</md-icon></md-button-toggle>
53+
</md-button-toggle-group>
54+
```
55+
56+
Output:
57+
58+
![Exclusive Toggle Button Example](https://material.angularjs.org/material2_assets/button-toggle/exclusive-toggle.png)
59+
60+
### Multiple Selection
61+
62+
`md-button-toggle` can be used in a multiple selection group when surrounded by
63+
`md-button-toggle-group multiple`. This styles all buttons within the group to appear as a single
64+
group of button toggles.
65+
66+
```html
67+
<md-button-toggle-group multiple>
68+
<md-button-toggle>Flour</md-button-toggle>
69+
<md-button-toggle>Eggs</md-button-toggle>
70+
<md-button-toggle>Sugar</md-button-toggle>
71+
<md-button-toggle>Milk</md-button-toggle>
72+
</md-button-toggle-group>
73+
```
74+
75+
Output:
76+
77+
![Multiple Toggle Button Example](https://material.angularjs.org/material2_assets/button-toggle/multi-toggle.png)
78+
79+
## Dynamic Exclusive Selection
80+
81+
`md-button-toggle`s can be used with `ngModel` to dynamically create groups and update the value for
82+
a group.
83+
84+
```html
85+
<md-button-toggle-group name="pies" [(ngModel)]="favoritePie">
86+
<md-button-toggle *ngFor="let pie of pieOptions" [value]="pie">
87+
{{pie}}
88+
</md-button-toggle>
89+
</md-button-toggle-group>
90+
<p>Your favorite type of pie is: {{favoritePie}}</p>
91+
```
92+
93+
### Disabled Button Toggle
94+
95+
`md-button-toggle-group` and `md-button-toggle` can both be disabled by adding a `disabled`
96+
attribute to either one. Adding `disabled` to an exclusive group or a multiple group will disable
97+
the entire group. Adding `disabled` to a single toggle will disable that toggle.
98+
99+
```html
100+
<md-button-toggle-group disabled>
101+
<md-button-toggle value="one">One</md-button-toggle>
102+
<md-button-toggle value="two">Two</md-button-toggle>
103+
<md-button-toggle value="three">Three</md-button-toggle>
104+
</md-button-toggle-group>
105+
106+
<md-button-toggle-group>
107+
<md-button-toggle value="red" disabled>Red</md-button-toggle>
108+
<md-button-toggle value="blue">Blue</md-button-toggle>
109+
</md-button-toggle-group>
110+
```
111+
112+
Output:
113+
114+
![Disabled Toggle Buttons Example](https://material.angularjs.org/material2_assets/button-toggle/disabled-toggles.png)
115+
116+
## `<md-button-toggle>`
117+
118+
### Bound Properties
119+
120+
| Name | Type | Description |
121+
| --- | --- | --- |
122+
| `id` | string | The unique ID of the toggle. IDs are generated by default when not specified. |
123+
| `name` | string | Optional, defaults to parent group name if one exists for exclusive selection toggles, otherwise null. This is used to differentiate between different groups. |
124+
| `value` | any | Value of the toggle. Only used when in a group to determine which are selected. |
125+
| `checked` | boolean | Optional, default = `false`. Whether or not the toggle is checked. |
126+
| `disabled` | boolean | Optional, default = `false`. Whether or not the toggle is disabled |
127+
128+
### Events
129+
130+
| Name | Description |
131+
| --- | --- |
132+
| `change` | Emitted when the `checked` value is changed. |
133+
134+
## `<md-button-toggle-group>`
135+
136+
### Bound Properties
137+
138+
| Name | Type | Description |
139+
| --- | --- | --- |
140+
| `name` | string | Optional, the name of the group. |
141+
| `disabled` | boolean | Optional, default = `false`. |
142+
| `value` | any | The current value for the group. Will be set to the value of the selected toggle or a list of values from the selected toggles. |
143+
| `selected` | `mdButtonToggle` | The current selected toggle or a list of the selected toggles. |
144+
145+
### Attributes
146+
147+
| Name | Type | Description |
148+
| --- | --- | --- |
149+
| `multiple` | boolean | Optional, default = `false`. Whether or not the group allows multiple selection. |
150+
151+
### Events
152+
153+
| Name | Description |
154+
| --- | --- |
155+
| `change` | Emitted when the `value` of the group changes. |

‎src/components/button-toggle/package.json

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"name": "@angular2-material/button-toggle",
3+
"version": "2.0.0-alpha.6-2",
4+
"description": "Angular 2 Material Button Toggle",
5+
"main": "./button-toggle.js",
6+
"typings": "./button-toggle.d.ts",
7+
"repository": {
8+
"type": "git",
9+
"url": "https://github.com/angular/material2.git"
10+
},
11+
"keywords": [
12+
"angular",
13+
"material",
14+
"material design",
15+
"components",
16+
"button-toggle",
17+
"button",
18+
"toggle"
19+
],
20+
"license": "MIT",
21+
"bugs": {
22+
"url": "https://github.com/angular/material2/issues"
23+
},
24+
"homepage": "https://github.com/angular/material2#readme",
25+
"peerDependencies": {
26+
"@angular2-material/core": "2.0.0-alpha.6-2",
27+
"@angular/forms": "^0.2.0"
28+
}
29+
}

0 commit comments

Comments
 (0)