Skip to content

Commit c63f304

Browse files
author
Gela
committed
Merge pull request #634 from bem/issues/#600@v2
popup block english description
2 parents c42af1b + ed10398 commit c63f304

File tree

2 files changed

+190
-4
lines changed

2 files changed

+190
-4
lines changed

‎common.blocks/popup/popup.en.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# popup
2+
3+
A `popup` block is used for popups creation. It allows to manage state, behavior and appearance of popups. Block is displayed in front of all other page elements.
4+
5+
Popup can be displayed by different page elements like pseudo links or buttons.
6+
7+
At the moment of first display (`_visible` modifier toggle) block's DOM element is created in the end of document `<body>`.
8+
9+
10+
## Block's modifiers
11+
12+
### The themes `_theme`
13+
14+
* simple
15+
* normal
16+
17+
If a `_theme` modifier is not set, browser defaults (`default`) will be applied to block.
18+
19+
#### default
20+
```bemjson
21+
{
22+
block : 'popup',
23+
content : 'default'
24+
}
25+
```
26+
27+
28+
#### simple
29+
30+
```bemjson
31+
{
32+
block : 'popup',
33+
mods : { theme : 'simple' },
34+
content : 'simple'
35+
}
36+
```
37+
38+
39+
#### normal
40+
41+
```bemjson
42+
{
43+
block : 'popup',
44+
mods : { theme : 'normal' },
45+
content : 'normal'
46+
}
47+
```
48+
49+
### Visibility `_visible`
50+
51+
A `_visible` modifier allow to control block visibility. If it's not set, block will not be displayed.
52+
53+
```bemjson
54+
{
55+
block : 'popup',
56+
mods : { theme : 'normal', visible : true },
57+
content : 'normal'
58+
}
59+
```
60+
61+
62+
### Alignment respect to its parent `_direction`
63+
64+
Modifier controls the position of popup window relative to the block which opened it – popup's alignment. Popup window's position is detected automatically basing on the admissible directions array and the parent block's position.
65+
66+
Chosen alignment will affect the opening animation direction.
67+
68+
By default following admissible directions array is used:
69+
70+
71+
<table>
72+
<tr>
73+
<th> Direction </td>
74+
<th> Index in array </td>
75+
</tr>
76+
<td> bottom-left </td>
77+
<td> 0 </td>
78+
</tr>
79+
<tr>
80+
<td> bottom-center </td>
81+
<td> 1 </td>
82+
</tr>
83+
<tr>
84+
<td> bottom-right</td>
85+
<td> 2 </td>
86+
</tr>
87+
<tr>
88+
<td> top-left </td>
89+
<td> 3 </td>
90+
</tr>
91+
<tr>
92+
<td> top-center </td>
93+
<td> 4 </td>
94+
</tr>
95+
<tr>
96+
<td> top-right </td>
97+
<td> 5 </td>
98+
</tr>
99+
<tr>
100+
<td> right-top </td>
101+
<td> 6 </td>
102+
</tr>
103+
<tr>
104+
<td> right-center </td>
105+
<td> 7 </td>
106+
</tr>
107+
<tr>
108+
<td> right-bottom </td>
109+
<td> 8 </td>
110+
</tr>
111+
<tr>
112+
<td> left-top </td>
113+
<td> 9 </td>
114+
</tr>
115+
<tr>
116+
<td> left-center </td>
117+
<td> 10 </td>
118+
</tr>
119+
<tr>
120+
<td> left-bottom </td>
121+
<td> 11 </td>
122+
</tr>
123+
</table>
124+
125+
To control the popup window position you can provide directions array with desired directions set only. According to parent block's position on a page the most suitable directions will be chosen among the provided values.
126+
127+
For example, if the popup window should be opened at the top of the parent block:
128+
129+
```bemjson
130+
{
131+
block : 'popup',
132+
mods : { autoclosable : true, theme: 'simple' },
133+
js : { directions : ['top-left', 'top-center', 'top-right'] },
134+
content : 'Hello, world!'
135+
}
136+
```
137+
138+
139+
Or if it should be opened strictly at the center-right position:
140+
141+
```bemjson
142+
{
143+
block : 'popup',
144+
mods : { autoclosable : true, theme: 'simple' },
145+
js : { directions : ['right-center'] },
146+
content : 'Hello, world!'
147+
}
148+
```
149+
150+
151+
### Automatic closure `_autoclosable`
152+
153+
With `_autoclosable` modifier toggled block will automatically hide away on mouse click outside popup window (`_visible` modifier will be removed).
154+
155+
```bemjson
156+
{
157+
block : 'popup',
158+
mods : { theme : 'normal', autoclosable : true },
159+
content : 'normal'
160+
}
161+
```
162+
163+
164+
##Relations between popup's
165+
166+
As long as popup's parent block itself can be nested in another popup block there is a need in a popup's relations handling. Block can handle Parent → [ Child, Child, ... ] relations by checking if the parent block is nested in another popup block. So, the children knows about the parent blocks existence.
167+
168+
If there were no such relations, the parent popup block will be closed on mouse click on the child block regardless of the fact that `_autoclosable` modifier is set to `true`.
169+
170+
This means that with `autoclosable` modifier toggled block will close itself and close all of it children on mouse click outside block's window or it child's window.
171+
172+
Child popup blocks can be regarded as a chain of 1 → 2 → 3 → 4. By clicking on the second element of chain, third and forth will be closed. By clicking on first, the second, third and forth will be closed. On click outside of any popup window of the chain element all popups will be closed.
173+
174+
175+
## Dependencies
176+
177+
The block depends on:
178+
179+
* `i-bem__dom `
180+
* `jquery`
181+
* `dom`
182+
* `objects`
183+
* `functions__throttle`
184+
* `keyboard`
185+
* `ua`
186+
* `jquery__event_pointer`

‎common.blocks/popup/popup.ru.md‎

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

6767
### Расположение относительно родителя `_direction`
6868

69-
Модификатор управляет положением попапа на странице, относительно вызвавшего его блока. Расположение блока определяется автоматически, исходя из массива допустимых расположений и положения родителя на странице.
69+
Модификатор управляет положением попапа на странице относительно вызвавшего его блока. Расположение блока определяется автоматически, исходя из массива допустимых расположений и положения родителя на странице.
7070

7171
Выбранное расположение влияет на направление анимации раскрытия.
7272

@@ -126,7 +126,7 @@
126126
</tr>
127127
</table>
128128

129-
Чтобы управлять расположением попапа, можно ограничить массив расположений, оставив только требуемые. Пользовательский массив нужно передать в качестве JS-параметра с ключом `directions`. При этом, из значений массива будет выбрано наиболее подходящее, исходя из положения родителя на странице.
129+
Чтобы управлять расположением попапа, можно ограничить массив расположений, оставив только требуемые. Пользовательский массив нужно передать в качестве JS-параметра с ключом `directions`. При этом из значений массива будет выбрано наиболее подходящее, исходя из положения родителя на странице.
130130

131131
Например, если требуется, чтобы попап раскрывался над родителем:
132132

@@ -170,9 +170,9 @@
170170
Так как попап выносит себя в конец `<body>`, чтобы перекрывать другие элементы страницы, возникает необходимость в построении взаимосвязей. Блок умеет выстраивать связи Parent → [ Child, Child, ... ]. Для этого он выполняет проверку, вложен ли блок, вызывающий попап в другой `popup`. Потомки знают о наличии родителя.
171171
Если бы этих взаимосвязей не было, то родительский попап (при наличии модификатора `autoclosable` со значением `true`) закрылся бы при клике внутри дочернего.
172172

173-
Другими словами, модификатор `autoclosable` со значением `true` означает, что попап закроется сам и закроет свои дочерние блоки при клике за пределами его самого и дочерних попапов.
173+
Другими словами модификатор `autoclosable` со значением `true` означает, что попап закроется сам и закроет свои дочерние блоки при клике за пределами его самого и дочерних попапов.
174174

175-
Дочерние блоки popup можно рассматривать в виде цепочки 1 → 2 → 3 → 4. При клике на 2-ом попапе – закрываются 3, 4. При клике в 1 – закрываются 2, 3, 4. При клике за пределами любого попапа из цепочки – закроются все.
175+
Дочерние блоки popup можно рассматривать в виде цепочки 1 → 2 → 3 → 4. При клике на втором попапе – закрываются третий и четвертый. При клике в первом – закрываются второй, третий, четвертый. При клике за пределами любого попапа из цепочки – закроются все.
176176

177177
### Зависимости блока
178178

0 commit comments

Comments
 (0)