Skip to content

Commit

Permalink
z-index-group: documentation + #965
Browse files Browse the repository at this point in the history
  • Loading branch information
Inna Belaya committed Aug 26, 2014
1 parent 393a688 commit 0174acc
Show file tree
Hide file tree
Showing 4 changed files with 171 additions and 6 deletions.
70 changes: 67 additions & 3 deletions common.blocks/popup/popup.en.md
View file
Expand Up @@ -13,6 +13,54 @@ To display `popup` when `visible` modifier is assigned, block should be initiali

The method returns `this`.

## Custom fields of a block

The following custom fields could be specified in BEMJSON declaration of the block:

<table>
<tr>
<th>Custom field name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><a href="#direction">directions</a></td>
<td>
<code>Array</code>
</td>
<td>Specifies position (e.g., <code>bottom-left</code>, where <code>bottom</code> is main direction and <code>left</code> - secondary) of `popup` relative to the element that triggers it.</td>
</tr>
<tr>
<td>mainOffset</td>
<td>
<code>String</code>
</td>
<td>Specifies offset along the main direction.</td>
</tr>
<tr>
<td>secondaryOffset</td>
<td>
<code>String</code></td>
<td>Specifies offset along the secondary direction.</td>
</tr>
<tr>
<td>viewportOffset</td>
<td>
<code>String</code>
</td>
<td>Specifies offset from the viewport (browser window).</td>
</tr>
<tr>
<td>zIndexGroupLevel</td>
<td>
<code>String</code>
</td>
<td>Specifies level of a layer for popups' opening. Uses <a href="../z-index-group/z-index.group.ru.md">z-index-group</a> block.</td>
</tr>
</table>

Additional required HTML attributes could be specified in `attrs` field of BEMJSON.

## Modifiers of a block

### _theme
Expand Down Expand Up @@ -62,6 +110,8 @@ See following examples:

`visible` modifier is set automatically when `popup` is displayed. When `popup` is hidden, `visible` modofier is removed.

**NB:** this block's version does not support manual selection of `visible` modifier in BEMJSON.

#### `_autoscalable`

When `autoscalable` modifier with `true` is set to `popup` block, mouse click outside the popup area hides it automatically.
Expand All @@ -74,9 +124,10 @@ When `autoscalable` modifier with `true` is set to `popup` block, mouse click ou
}
```

### Popup opening direction `_direction`
<a name="direction">
## Popup opening direction `_direction`

This modifier controls position of `popup` ralative to the element that trigges it.
This modifier controls position of `popup` relative to the element that triggers it.

By default the following admissible directions are available:

Expand Down Expand Up @@ -117,9 +168,22 @@ To open `popup` strictly at the `center-right` position do the following:
}
```

Use `mainOffset` and/or `secondaryOffset` parameters to manage the offset direction:

```bemjson
{
block : 'popup',
mods : { autoclosable : true, theme: 'normal' },
direction : ['right-center'],
mainOffset : 100,
secondaryOffset : 100,
content : 'Hello, world!'
}
```

## Relationship between popups

`popup` block supports a nested stucture of multiple simultaneous popups. It means you can open popup (child) within another popup (parent) with the parent popup remaining opened.
`popup` block supports nested stucture of multiple simultaneous popups. It means you can open popup (child) within another popup (parent) with the parent popup remaining opened.

If `autoscalable` modifier is specified, mouse click outside the parent popup area hides it and all its child automatically.

Expand Down
70 changes: 67 additions & 3 deletions common.blocks/popup/popup.ru.md
View file
Expand Up @@ -15,6 +15,54 @@

Метод `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`
Expand Down Expand Up @@ -62,6 +110,8 @@

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

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

#### `_autoscalable`

Модификатор `autoscalable` скрывает блок по щелчку мыши вне зоны попапа.
Expand All @@ -74,9 +124,10 @@
}
```

### Расположение относительно родителя `_direction`
<a href="direction"></a>
## Расположение относительно родителя `_direction`

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

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

Expand Down Expand Up @@ -117,9 +168,22 @@
}
```

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

```bemjson
{
block : 'popup',
mods : { autoclosable : true, theme: 'normal' },
direction : ['right-center'],
mainOffset : 100,
secondaryOffset : 100,
content : 'Hello, world!'
}
```

## Взаимосвязи между popup'ами

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

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

Expand Down
19 changes: 19 additions & 0 deletions common.blocks/z-index-group/z-index-group.en.md
View file
@@ -0,0 +1,19 @@
# z-index-group

`z-index-group` block is used to create several layers on a page for blocks representation.
This block can be mixed only with blocks that have a modifier `position`.

`level` modifier controls the layer position on the `z`-axis. Integer number from 0 to 9 can be used as a value for 'level' mode. When blocks overlap, z-order determines which one covers the other. A block with a larger `level` value covers a block with a lower one. If two blocks have the same `level` value, a block that is declared in BEMJSON declaration lower will cover the other one.

`z-index-group` block allows a user to open new elements on a layer that is specified in `level` modifier value. For example, if parent block that initiates [popup](../popup/popup.ru.md) is mixed with `{ block : 'z-index-group', mods : { level : 2 } }`, `popup` block will be shown at the second level (`2 * 1000`).

The example below shows popup block that does not cover another block (e.g., block `header`):

```js
{
block : 'popup',
mix : { block : 'z-index-group', mods : { level : 1 } },
mods : { autoclosable : true, theme : 'normal' },
content : 'I\'m under the block with \`level : 2\` value !'
}
```
18 changes: 18 additions & 0 deletions common.blocks/z-index-group/z-index-group.ru.md
View file
@@ -0,0 +1,18 @@
# z-index-group

Блок `z-index-group` используется для формирования нескольких слоев отображения блоков на странице. Применяется только к тем блокам, которым может быть установлено значение `position`. Каждый слой может находиться как выше, так и ниже других объектов веб-страницы. Их размещением по `z`-оси управляет модификатор `level`.

В качестве значения модификатора `level` используются целые числа от 0 до 9 включительно. Чем больше значение, тем выше находится слой по сравнению с теми слоями, у которых оно меньше. При равном значении `level` на переднем плане находится тот элемент, который в BEMJSON задекларирован ниже.

Блок `z-index-group` с указанным значением модификатора `level` примешивается к позиционированному элементу веб-страницы и позволяет открывать новые элементы относительно уровня слоя, указанного в значении `level`. Например, если родителю, вызывающему [popup](../popup/popup.ru.md), примешан `{ block : 'z-index-group', mods : { level : 2 } }`, то попап вызывается уже от второго уровня (`2 * 1000`).

На примере ниже показана ситуация, когда открывающийся попап не перекрывает другой блок (например, шапку), находящийся на странице:

```js
{
block : 'popup',
mix : { block : 'z-index-group', mods : { level : 1 } },
mods : { autoclosable : true, theme : 'normal' },
content : 'I\'m under the block with \`level : 2\` value !'
}
```

0 comments on commit 0174acc

Please sign in to comment.