Skip to content

Commit

Permalink
popup: fix after review
Browse files Browse the repository at this point in the history
  • Loading branch information
Inna Belaya committed Dec 25, 2014
1 parent 8451f9c commit b1eabbd
Showing 1 changed file with 162 additions and 125 deletions.
287 changes: 162 additions & 125 deletions common.blocks/popup/popup.ru.md
View file
@@ -1,133 +1,122 @@
# popup

Блок `popup` используется для создания выпадающих элементов и позволяет изменять их состояние, поведение и внешний вид. Блок всегда отображается поверх остальных элементов страницы.

Попап может быть вызван различными элементами страницы, например, кнопками или псевдоссылками.

При первом открытии попапа DOM-элемент блока переносится в конце `<body>`. Блок получает модификатор `visible`.

## Инициализация блока

Чтобы попап отображался при установке модификатора `visible`, блок должен быть предварительно инициализирован. Для этого служит метод `setTarget`. В ходе выполнения методу необходимо определить положение попапа на странице. Это может осуществляться:

* исходя из положения на странице родительского элемента. В этом случае методу `setTarget` следует передать аргументом родительский DOM-элемент или БЭМ-блок;
* путем явного указания координат. Первым аргументом методу `setTarget` передается значение отступа от левого края страницы, вторым отступ сверху: `setTarget(x-coordinate, y-coordinate)`.

Метод `setTarget` возвращает объект `this`.

## Специализированные поля блока

Список зарезервированных полей входного BEMJSON:

<table>
<tr>
<th>Поле</th>
<th>Тип</th>
<th>Описание</th>
</tr>
<tr>
<td>directions</td>
<td>
<code>Массив</code>
</td>
<td>Управляет <a href="#directions">направлением открытия попапа</a> (например, <code>bottom-left</code>, где <code>bottom</code> является основным параметром, <code>left</code> — второстепенным) на странице относительно вызвавшего его элемента.</td>
</tr>
<tr>
<td>mainOffset</td>
<td>
<code>String</code>
</td>
<td>Задает смещение попапа относительно основного направления.</td>
</tr>
<tr>
<td>secondaryOffset</td>
<td>
<code>BEMJSON</code></td>
<td>Задает смещение попапа относительно второстепенного направления.</td>
</tr>
<tr>
<td>viewportOffset</td>
<td>
<code>String</code>
</td>
<td>Задает смещение попапа от края окна браузера.</td>
</tr>
<tr>
<td>zIndexGroupLevel</td>
<td>
<code>String</code>
</td>
<td>Позволяет задать уровень слоя для открывающихся попапов. Основан на блоке <a href="../z-index-group/z-index.group.ru.md">z-index-group</a></td>
</tr>
</table>

При необходимости дополнительные HTML-атрибуты блока могут быть заданы в зарезервированном поле `attrs` в BEMJSON.

## Модификаторы блока

### Темы `_theme`

Блок представлен в следующих темах:

* simple
* islands

Без указания модификатора `theme` отображается [нативный](#native) вид контрола.

Наглядно видно на примерах ниже:

<a name="native"></a>
**default**
Используется для создания блоков, открывающихся поверх остальных слоев страницы.

```
{
block : 'popup',
content : 'default'
}
```
## Обзор блока

**simple**
### Модификаторы блока

```
{
block : 'popup',
mods : { theme : 'simple' },
content : 'simple'
}
```
| Модификатор | Допустимые значения | Способы использования | Описание |
| ----------- | ------------------- | -------------------- | -------- |
| <a href="#target">target</a> | <code>'anchor'</code>, <code>'position'</code> | <code>BEMJSON</code> | Точка открытия всплывающего окна. |
| <a href="#visible">visible</a> | <code>true</code> | <code>JS</code> | Видимость всплывающего окна. |
| <a href="#autoclosable">autoclosable</a> | <code>true</code>| <code>BEMJSON</code> | Автоматическое скрытие всплывающего окна. |
| <a href="#theme">theme</a> | <code>'islands'</code> | <code>BEMJSON</code> | Стилевое оформление. |

**islands**
### Специализированные поля блока

```
| Поле | Тип | Описание |
| ---- | --- | -------- |
| <a href="#directions">directions</a> | <code>Array</code> | Расположение (в порядке приоритета) относительно точки открытия. Используется только для всплывающих окон с модификатором <a href="#popuptarget">target</a>. |
| <a href="#mainOffset">mainOffset</a> | <code>Number</code> | Смещение в пикселях всплывающего окна относительно основного направления. Используется только с модификатором <a href="#popuptarget">target</a>. |
| <a href="#secondaryOffset">secondaryOffset</a> | <code>Number</code>| Смещение в пикселях всплывающего окна относительно второстепенного направления. Используется только с модификатором <a href="#popuptarget">target</a>. |
| <a href="#viewportOffset">viewportOffset</a> | <code>Number</code>| Минимально допустимое смещение в пикселях всплывающего окна от края окна браузера. Используется только с модификатором <a href="#popuptarget">target</a>. |
| <a href="#zIndexGroupLevel">zIndexGroupLevel</a> | <code>Number</code> | Уровень слоя для открывающихся всплывающих окон. Использует блок <a href="../z-index-group/z-index-group.ru.md">z-index-group</a>.|

## Описание блока

Блок `popup` используется для создания всплывающих окон поверх остальных слоев страницы. Позволяет изменять их состояние, поведение и внешний вид.

### Модификаторы блока

<a name="target"></a>

#### Модификатор `target`

Допустимые значения: `'anchor'`, `'position'`.

Способ использования: `BEMJSON`.

Модификатор `target` определяет точку открытия всплывающего окна.

<a name="target-anchor"></a>

##### Якорь (модификатор `target` в значении `anchor`)

Позволяет использовать в качестве точки открытия всплывающего окна блок или элемент.

Поддерживается многоуровневая вложенность всплывающих окон (из каждого открытого блока `popup` может быть вызван другой). Одновременно с закрытием всплывающего окна закрываются все его дочерние окна.

Необходимо использовать метод [setAnchor](http://ru.bem.info/libs/bem-components/v2/desktop/popup/jsdoc/).

##### Координаты (модификатор `target` в значении `position`)

Позволяет задавать точку открытия всплывающего окна координатами.

Необходимо использовать метод [setPosition](http://ru.bem.info/libs/bem-components/v2/desktop/popup/jsdoc/).

<a name="visible"></a>

#### Модификатор `visible`

Допустимое значение: `true`.

Способы использования: `JS`.

Выставляется при открытии всплывающего окна.

Отвечает за видимость всплывающего окна на странице.

<a name="autoclosable"></a>

#### Модификатор `autoclosable`

Допустимое значение: `true`.

Способ использования: `BEMJSON`.

При наличии модификатора `autoclosable` блок скрывается по клику вне зоны всплывающего окна или по нажатию кнопки `Escape`.

```javascript
{
block : 'popup',
mods : { theme : 'islands' },
content : 'islands'
mods : { theme : 'islands', autoclosable : true },
content : ''
}
```

### Видимый `_visible`
<a name="theme"></a>

Модификатор `visible` выставляется блоку автоматически при открытии попапа. Когда попап скрыт, модификатор удаляется.
#### Модификатор `theme`

**NB:** данная реализация блока не поддерживает принудительную установку модификатора `visible` в BEMJSON-декларации.
Допустимое значение: `'islands'`.

#### `_autoclosable`
Способ использования: `BEMJSON`.

Модификатор `autoclosable` скрывает блок по щелчку мыши вне зоны попапа.
Отвечает за стилевое оформление блока.

```
```javascript
{
block : 'popup',
mods : { theme : 'islands', autoclosable : true },
content : 'islands'
mods : { theme : 'islands' },
content : 'Содержимое всплывающего окна'
}
```

<a href="direction"></a>
## Расположение относительно родителя `_direction`
### Специализированные поля блока

<a name="directions"></a>

#### Поле `directions`

Тип: `Array`.

Определяет расположение всплывающего окна относительно точки открытия.

Поле `direction` управляет направлением открытия попапа на странице относительно вызвавшего его элемента. Расположение блока определяется автоматически, исходя из массива допустимых направлений и положения родителя на странице.
Используется только для всплывающих окон с модификатором <a href=#target>target</a>.

<a name="directions-type"></a>
Расположение блока определяется автоматически, исходя из массива допустимых направлений (в порядке приоритета) и положения точки открытия на странице. У всех допустимых направлений есть основной и второстепенный параметры. Например, для направления `bottom-left` параметр `bottom` является основным, а `left` — второстепенным.

По умолчанию используется следующий массив допустимых направлений:

Expand All @@ -144,47 +133,95 @@
* left-center
* left-bottom

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

Например, если требуется, чтобы попап раскрывался над родителем:
Например, если требуется, чтобы всплывающее окно раскрывалось над точкой открытия:

```
```javascript
{
block : 'popup',
mods : { autoclosable : true, theme: 'simple' },
mods : { autoclosable : true, theme: 'islands', target : 'anchor' },
directions : ['top-left', 'top-center', 'top-right'],
content : 'Hello, world!'
content : 'Содержимое всплывающего окна'
}
```

Или необходимо разместить попап справа по центру:
Если необходимо разместить всплывающее окно справа по центру:

```javascript
{
block : 'popup',
mods : { autoclosable : true, theme: 'islands', target : 'anchor' },
directions : ['right-center'],
content : 'Содержимое всплывающего окна'
}
```
<a name="mainOffset"></a>

#### Поле `mainOffset`

Тип: `Number`.

Определяет смещение в пикселях всплывающего окна относительно <a href="#directions-type">основного</a> направления.

Используется только с модификатором <a href="#target">target</a>.

```javascript
{
block : 'popup',
mods : { autoclosable : true, theme: 'simple' },
mods : { theme: 'islands', target : 'anchor' },
directions : ['right-center'],
content : 'Hello, world!'
content : 'Содержимое всплывающего окна',
mainOffset : 100
}
```

Используйте поля `mainOffset` и/или `secondaryOffset` для управления направлением смещения.
<a name="secondaryOffset"></a>

#### Поле `secondaryOffset`

Тип: `Number`.

Определяет смещение в пикселях всплывающего окна относительно <a href="#directions-type">второстепенного</a> направления.

Используется только с модификатором <a href="#target">target</a>.

```javascript
{
block : 'popup',
mods : { theme: 'islands', target : 'anchor' },
directions : ['right-center'],
content : 'Содержимое всплывающего окна',
secondaryOffset : 100
}
```

<a name="viewportOffset"></a>

#### Поле `viewportOffset`

Тип: `Number`.

Определяет минимально допустимое смещение в пикселях всплывающего окна от края окна браузера.

Используется только с модификатором <a href="#target">target</a>.

```javascript
{
block : 'popup',
mods : { autoclosable : true, theme: 'islands' },
direction : ['right-center'],
mainOffset : 100,
secondaryOffset : 100,
content : 'Hello, world!'
mods : { theme: 'islands', target : 'anchor' },
directions : ['right-center'],
content : 'Содержимое всплывающего окна',
viewportOffset : 100
}
```

## Взаимосвязи между popup'ами
<a name="zIndexGroupLevel"></a>

#### Поле `zIndexGroupLevel`

Блок `popup` поддерживает вложенную структуру нескольких одновременно открытых попапов. Это означает, что один попап может вызывать второй, а второй, соответственно, может вызвать третий и так далее. И при этом все попапы будут оставаться открытыми.
Тип: `Number`.

Если установлен модификатор `autoclosable` в значении `true`, то при щелчке мышью вне зоны попапа, попап закроется сам и закроет свои дочерние блоки.
Определяет уровень слоя для каждого всплывающего окна.

Дочерние блоки popup можно рассматривать в виде цепочки `1` → `2` → `3` → `4`. При клике на втором попапе – закрываются третий и четвертый. При клике в первом – закрываются второй, третий, четвертый. При клике за пределами любого попапа из цепочки – закроются все.
Использует блок <a href="../z-index-group/z-index-group.ru.md">z-index-group</a>.

0 comments on commit b1eabbd

Please sign in to comment.