Skip to content

Commit a89f3ff

Browse files
author
Gela
committed
Merge pull request #692 from bem/issues/#640@v2
checkbox-group block english description
2 parents 9ed9222 + 974b83c commit a89f3ff

File tree

2 files changed

+391
-15
lines changed

2 files changed

+391
-15
lines changed

‎common.blocks/checkbox-group/checkbox-group.en.md‎

Lines changed: 359 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,359 @@
1+
# checkbox-group
2+
3+
A `checkbox-group` block is a set of independed switches – checkboxes (a `checkbox` block). Any of group's switches can be either active or not regardless of other switches state.
4+
5+
The block allows to manage the appearance and state of a nested switches.
6+
7+
On a web page `checkbox-group` block will be rendered to `<span>` HTML element, with a nested set of checkboxes and their labels.
8+
9+
10+
## Valid block's attributes
11+
12+
Valid block's attributes could be specified in the corresponding fields of block BEMJSON declaration:
13+
14+
<table>
15+
<tr>
16+
<th align="center">Attributes</th>
17+
<th align="center">Type</th>
18+
<th align="center">Description</th>
19+
</tr>
20+
<tr>
21+
<td>name</td>
22+
<td><code>String</code></td>
23+
<td>The checkbox group name. Renders to nested <code>input</code> block's <code>name</code> HTML attribute.</td>
24+
</tr>
25+
<tr>
26+
<td>options</td>
27+
<td><code>Array</code></td>
28+
<td>The option objects array. Each object within the array corresponds to one switch and contains it's attributes set.</td>
29+
</tr>
30+
</table>
31+
32+
Following attributes should be passed in an `option` field for each switch:
33+
34+
* `val` (`String` | `Number`) – value returned by selected switcher (a 'checkbox__control' element);
35+
* `text` (`String`) – a text label for the current switch.
36+
37+
In an `options` array any valid `checkbox` block attributes can be passed. For example, a `_checked` or `_disabled` modifiers can be set for the `checkbox`.
38+
39+
40+
## Block's modifiers
41+
42+
### The themes `_theme`
43+
44+
* simple
45+
* normal
46+
47+
If a `_theme` modifier is not set, browser defaults (`default`) will be applied to the block.
48+
49+
For example:
50+
51+
#### default
52+
53+
```bemjson
54+
{
55+
block : 'checkbox-group',
56+
name : 'checkbox-default',
57+
options : [
58+
{ val : 1, text : 'first' },
59+
{ val : 2, text : 'second' }
60+
]
61+
}
62+
```
63+
64+
65+
#### simple
66+
67+
```bemjson
68+
{
69+
block : 'checkbox-group',
70+
mods : { theme : 'simple' },
71+
name : 'checkbox-simple',
72+
options : [
73+
{ val : 1, text : 'first' },
74+
{ val : 2, text : 'second' }
75+
]
76+
}
77+
```
78+
79+
80+
#### normal
81+
82+
```bemjson
83+
{
84+
block : 'checkbox-group',
85+
mods : { theme : 'normal', size : 'l' },
86+
name : 'checkbox-normal',
87+
options : [
88+
{ val : 1, text : 'first' },
89+
{ val : 2, text : 'second' }
90+
]
91+
}
92+
```
93+
94+
95+
### The sizes `_size`
96+
97+
Mandatory modifier. Available for *normal* theme only.
98+
Provides all types of checkbox groups with the size value.
99+
100+
There are four sizes available: **S**, **M**, **L**, **XL**.
101+
102+
Depending on a `_type` modifier value following sizes are available:
103+
104+
<table>
105+
<tr>
106+
<th>Size</th>
107+
<th>Normal checkbox group and <code>_type_line</code></th>
108+
<th>Button checkbox group (<code>_type_button</code>)</th>
109+
</tr>
110+
<tr>
111+
<th>s</th>
112+
<td>–</td>
113+
<td>+</td>
114+
</tr>
115+
<tr>
116+
<th>m</th>
117+
<td>+</td>
118+
<td>+</td>
119+
</tr>
120+
<tr>
121+
<th>l</th>
122+
<td>+</td>
123+
<td>+</td>
124+
</tr>
125+
<tr>
126+
<th>xl</th>
127+
<td>–</td>
128+
<td>+</td>
129+
</table>
130+
131+
132+
Here are some examples with *normal* theme and the `_type_button` modifier is set:
133+
134+
<table>
135+
<tr>
136+
<th>Size</th>
137+
<th>Example</th>
138+
</tr>
139+
<tr>
140+
<th>s</th>
141+
<td>
142+
<pre><code>
143+
{
144+
block : 'checkbox-group',
145+
mods : {
146+
theme : 'normal',
147+
size : 's',
148+
type : 'button'
149+
},
150+
name : 'checkbox-button',
151+
options : [
152+
{ val : 1, text : 'first' },
153+
{ val : 2, text : 'second' }
154+
]
155+
}
156+
</code></pre>
157+
</td>
158+
</tr>
159+
<tr>
160+
<th>m</th>
161+
<td>
162+
<pre><code>
163+
{
164+
block : 'checkbox-group',
165+
mods : {
166+
theme : 'normal',
167+
size : 'm',
168+
type : 'button'
169+
},
170+
name : 'checkbox-button',
171+
options : [
172+
{ val : 1, text : 'first' },
173+
{ val : 2, text : 'second' }
174+
]
175+
}
176+
</code></pre>
177+
</td>
178+
</tr>
179+
<tr>
180+
<th>l</th>
181+
<td>
182+
<pre><code>
183+
{
184+
block : 'checkbox-group',
185+
mods : {
186+
theme : 'normal',
187+
size : 'l',
188+
type : 'button'
189+
},
190+
name : 'checkbox-button',
191+
options : [
192+
{ val : 1, text : 'first' },
193+
{ val : 2, text : 'second' }
194+
]
195+
}
196+
</code></pre>
197+
</td>
198+
</tr>
199+
<tr>
200+
<th>xl</th>
201+
<td>
202+
<pre><code>
203+
{
204+
block : 'checkbox-group',
205+
mods : {
206+
theme : 'normal',
207+
size : 'xl',
208+
type : 'button'
209+
},
210+
name : 'checkbox-button',
211+
options : [
212+
{ val : 1, text : 'first' },
213+
{ val : 2, text : 'second' }
214+
]
215+
}
216+
</code></pre>
217+
</td>
218+
</tr>
219+
</table>
220+
221+
222+
### Checkbox group type `_type`
223+
224+
A `_type` modifier can have following values:
225+
226+
* `button`. It is used for creation of button checkbox group – a block of button switches;
227+
* `line`. It is used for line-aligned checkbox group creation. Right gap is automatically added after each switch of the group except the last one. Available only for *normal* theme.
228+
229+
Modifier is available for all block themes.
230+
231+
<table>
232+
<tr>
233+
<th>Type</th>
234+
235+
<th>Example</th>
236+
</tr>
237+
<tr>
238+
<td>Normal checkbox group</td>
239+
<td>
240+
<pre><code>
241+
{
242+
block : 'checkbox-group',
243+
mods : { theme : 'normal', size : 'l' },
244+
name : 'checkbox-normal',
245+
options : [
246+
{ val : 1, text : 'first' },
247+
{ val : 2, text : 'second' }
248+
]
249+
}
250+
</code></pre>
251+
</td>
252+
<tr>
253+
<td>Button checkbox group</td>
254+
<td>
255+
<pre><code>
256+
{
257+
block : 'checkbox-group',
258+
mods : {
259+
theme : 'normal',
260+
size : 'l',
261+
type : 'button'
262+
},
263+
name : 'checkbox-button',
264+
options : [
265+
{ val : 1, text : 'first' },
266+
{ val : 2, text : 'second' }
267+
]
268+
}
269+
</code></pre>
270+
</td>
271+
</tr>
272+
<tr>
273+
<td>Line-aligned checkbox group (<code>_type_line</code>)</td>
274+
<td>
275+
<pre><code>
276+
{
277+
block : 'checkbox-group',
278+
mods : {
279+
theme : 'normal',
280+
size : 'l',
281+
type : 'line'
282+
},
283+
name : 'checkbox-line',
284+
options : [
285+
{ val : 1, text : 'first' },
286+
{ val : 2, text : 'second' }
287+
]
288+
}
289+
</code></pre>
290+
</td>
291+
</tr>
292+
</table>
293+
294+
295+
### Inactive `_disabled`
296+
297+
A `_disabled` modifier helps to create an inactive menu item. Inactive menu item is displayed, but not available for user actions.
298+
299+
Such a group will not obtain a focus (`_focused` modifier will not be toggled).
300+
301+
When a `_disabled` modifier is set for the group, all it's switches also will be disabled. As a result, the following will not be performed on switches:
302+
303+
* state modifiers `_hovered`, `_pressed` and `_focused` toggling;
304+
* switching between `_checked` modifier's values.
305+
306+
Modifier is available for all block themes.
307+
308+
```bemjson
309+
{
310+
block : 'checkbox-group',
311+
mods : {
312+
theme : 'normal',
313+
size : 'l',
314+
type : 'button',
315+
disabled : true
316+
},
317+
name : 'checkbox-button',
318+
options : [
319+
{ val : 1, text : 'first' },
320+
{ val : 2, text : 'second', checked : true }
321+
]
322+
}
323+
```
324+
325+
326+
### Block's states
327+
328+
#### `_focused`
329+
330+
A `_focused`
331+
_focused modifier is automatically toggled when one of the block's elements is in focus. For example, on mouse click or by `Tab` key press.
332+
333+
Available for all block themes.
334+
335+
```bemjson
336+
{
337+
block : 'checkbox-group',
338+
mods : {
339+
theme : 'normal',
340+
size : 'l',
341+
type : 'button',
342+
focused : true
343+
},
344+
name : 'checkbox-button',
345+
options : [
346+
{ val : 1, text : 'first' },
347+
{ val : 2, text : 'second' }
348+
]
349+
}
350+
```
351+
352+
353+
## Dependencies
354+
355+
The block depends on:
356+
357+
* `i-bem__dom `
358+
* `checkbox`
359+
* `jquery`

0 commit comments

Comments
 (0)