Skip to content

Commit 2fd6525

Browse files
author
Gela
committed
Merge pull request #610 from bem/issues/#572@v2
dropdown: block english description
2 parents c63f304 + 322c5fb commit 2fd6525

File tree

2 files changed

+231
-3
lines changed

2 files changed

+231
-3
lines changed

‎common.blocks/dropdown/dropdown.en.md‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
# dropdown
2+
3+
A `dropdown` block is used to create different types of dropdowns. It allows to manage state, behavior and appearance of dropdowns. Block consist of two components – the control component and the popup window (`popup` block). Popup window is displayed in front of all other page elements.
4+
5+
On mouse click over control component it shows the popup window (toggles `_visible` modifier for the `popup` block).
6+
7+
Depending on a `_switcher` modifier value, either link, pseudo link or button can be used as a control component.
8+
9+
10+
## Valid block's attributes
11+
12+
Valid block's attributes can be specified in a corresponding fields of block's 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>switcher</td>
22+
<td><code>String|BEMJSON</code></td>
23+
<td>Label for the control component. May contain a string with the text label or BEMJSON notation of nested BEM-entities. For example, it allows to wrap the control component with other block or pass it an additional attribute values.</td>
24+
</tr>
25+
<tr>
26+
<td>popup</td>
27+
<td><code>String|BEMJSON</code></td>
28+
<td>Text value or BEMJSON description of popup window content. In runtime BEMJSON entities will be rendered into HTML.</td>
29+
</tr>
30+
</table>
31+
32+
Also, BEMJSON declaration can contain an arbitrary fields used for templating.
33+
34+
35+
## Block's modifiers
36+
37+
### The themes `_theme`
38+
39+
* simple
40+
* normal
41+
42+
If a `_theme` modifier is not set, the browser defaults (`default`) will be applied to block.
43+
44+
#### default
45+
46+
```bemjson
47+
{
48+
block : 'dropdown',
49+
mods : { switcher : 'link' },
50+
switcher : 'link',
51+
popup : 'Hello, world!'
52+
}
53+
```
54+
55+
56+
#### simple
57+
58+
```bemjson
59+
{
60+
block : 'dropdown',
61+
mods : { switcher : 'link', theme : 'simple' },
62+
switcher : 'link',
63+
popup : 'Hello, world!'
64+
}
65+
```
66+
67+
68+
#### normal
69+
70+
```bemjson
71+
{
72+
block : 'dropdown',
73+
mods : { switcher : 'link', theme : 'normal' },
74+
switcher : 'link',
75+
popup : 'Hello, world!'
76+
}
77+
```
78+
79+
80+
### Control component type `_switcher`
81+
82+
Mandatory modifier. It specifies which block to use as a control component. Next types are available:
83+
84+
* `_switcher_link` - the pseudo link. `link` block is used as a base of the control component.
85+
* `_switcher_button` - the button. `button` block is used as a base of the control component.
86+
87+
Available for all block themes.
88+
89+
```bemjson
90+
{
91+
block : 'dropdown',
92+
mods : {
93+
switcher : 'button',
94+
theme : 'normal',
95+
size : 'xl'
96+
},
97+
switcher : 'button',
98+
popup : 'Hello, world!'
99+
}
100+
```
101+
102+
103+
### `_disabled`
104+
105+
If a `_disabled` modifier is set, the dropdown is displayed but not available for user's actions.
106+
107+
For such disabled block an `_opened` state will not be toggled on mouse click.
108+
109+
If a `_disabled` modifier set, it prevents the block components from the following actions:
110+
111+
* `popup` block – `_visible` modifier toggle;
112+
* `link` control component – `_focused` state toggle. Link does not obtain focus on mouse click or by `Tab` key press;
113+
* `button` control component:
114+
* `_focused` state toggle. Button will not obtain focus on mouse click or by `Tab` key press;
115+
* `_hovered` state toggle on mouse pointer hover.
116+
117+
Available for all block themes.
118+
119+
```bemjson
120+
{
121+
block : 'dropdown',
122+
mods : {
123+
switcher : 'button',
124+
theme : 'normal',
125+
size : 'xl',
126+
disabled : true
127+
},
128+
switcher : 'button',
129+
popup : 'Hello, world!'
130+
}
131+
```
132+
133+
134+
### dropdown's states
135+
136+
#### `_opened`
137+
138+
`_opened` modifier toggles automatically on mouse click on the control component.
139+
140+
```bemjson
141+
{
142+
block : 'dropdown',
143+
mods : {
144+
switcher : 'button',
145+
theme : 'normal',
146+
size : 'xl',
147+
opened : true
148+
},
149+
switcher : 'button',
150+
popup : 'Hello, world!'
151+
}
152+
```
153+
154+
155+
Modifier can be removed by re-clicking on the control component or outside popup's window (in case of `_autoclosable` modifier availability for `popup` block).
156+
157+
158+
## BEMJSON value of `switcher` and `popup` attributes
159+
160+
As the control component and the popup attributes can contain BEM-entities it can be used for different purposes such as:
161+
162+
* control component warping or modifying;
163+
* passing additional attribute values to control component;
164+
* creating nested content in popup window.
165+
166+
For example, you can make a control component's button toggleable:
167+
168+
```bemjson
169+
{
170+
block : 'dropdown',
171+
mods : {
172+
switcher : 'button',
173+
theme : 'normal',
174+
size : 'xl'
175+
},
176+
switcher : {
177+
block : 'button',
178+
mods : { togglable : 'true' },
179+
text : 'custom button'
180+
},
181+
popup : 'Popup message'
182+
}
183+
```
184+
185+
186+
Or make dropdown list selector based on block:
187+
188+
```bemjson
189+
{
190+
block : 'dropdown',
191+
mods : {
192+
switcher : 'button',
193+
theme : 'normal',
194+
size : 'xl'
195+
},
196+
switcher : 'Dropdown menu',
197+
popup : {
198+
block : 'menu',
199+
mods : {
200+
theme : 'normal',
201+
size : 'xl',
202+
select : 'check'
203+
},
204+
content : [
205+
{
206+
block : 'menu-item',
207+
val : 1,
208+
content : 'First item'
209+
},
210+
{
211+
block : 'menu-item',
212+
val : 2,
213+
content : 'Second item'
214+
}
215+
]
216+
}
217+
}
218+
```
219+
220+
221+
## Dependencies
222+
223+
The `dropdown` block depends on:
224+
225+
* `i-bem__dom`
226+
* `dom`
227+
* `popup`
228+
* `button`/`link` (depending on `_switcher` control component type)

‎common.blocks/dropdown/dropdown.ru.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
Управляющий компонент при щелчке мышью вызывает попап (устанавливает для блока `popup` модификатор `_visible`).
66

7-
В зависимости от значения модификатора `_switcher`, управляющим компонентом может служить ссылка, псевдоссылка или кнопка.
7+
В зависимости от значения модификатора `_switcher` управляющим компонентом может служить ссылка, псевдоссылка или кнопка.
88

99

1010
## Допустимые параметры блока
@@ -40,7 +40,7 @@
4040

4141
Без указания темы к блоку применяются значения по умолчанию (*default*), установленные браузером.
4242

43-
Наглядно видно на примерах ниже:
43+
Наглядно показано на примерах ниже:
4444

4545
#### default
4646

@@ -110,7 +110,7 @@
110110

111111
Для такого блока не будет устанавливаться состояние `_opened` при щелчке мышью по управляющему компоненту.
112112

113-
При установке для блока модификатора `_disabled`, для компонентов блока не будут производиться следующие действия:
113+
При установке для блока модификатора `_disabled` для компонентов блока не будут производиться следующие действия:
114114

115115
* Блок </code>popup – установка модификатора `_visible`;
116116
* Управляющий компонент `link` – установка состояния `_focused`. Ссылка не получает фокус по щелчку мышью или по нажатию клавиши `Tab`;

0 commit comments

Comments
 (0)