bemer 0.1.0 → 0.2.0

data/docs//320/237/321/200/320/265/320/264/320/270/320/272/320/260/321/202/321/213.md

@@ -0,0 +1,205 @@
+# Предикаты
+
+Позволяют указать условия для выбора узлов в структуре/дереве компонента.
+
+#### Предикат `block`
+
+С помощью предиката `block` можно задать условия для выбора узла(ов) с типом блок по БЭМ методологии в структуре/дереве компонента.
+
+В качестве параметров можно указать:
+1. [Название блока](%D0%A5%D0%B5%D0%BB%D0%BF%D0%B5%D1%80-block_tag.md#%D0%9D%D0%B0%D0%B7%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5-%D1%81%D1%83%D1%89%D0%BD%D0%BE%D1%81%D1%82%D0%B8) как `String` или `Symbol`, по умолчанию равно `'*'`.
+1. Вторым параметром можно передать условие, которым может быть `Proc`, `lambda`, название метода или какое-либо выражение, для `Proc` и `lambda` в качестве аргумента будет передан контекст (context) узла, для которого происходит проверка условий.
+1. `mods` задает список модификаторов которые должны присутствовать в списке модификаторов узла.
+1. `mix` задает список миксов которые должны присутствовать в списке миксов узла.
+
+##### Примеры
+
+Выбрать блоки с названием `panel` и заменить css классы:
+```slim
+= render_component :panel do |template|
+  = template.block(:panel).cls :panel, :panel_success
+```
+
+Выбрать блоки с названием `panel` и применить несколько режимов:
+```slim
+/ Эквивалентные записи
+= render_component :panel do |template|
+  = template.block(:panel).cls :panel, :panel_success
+  = template.block(:panel).bem true
+  = template.block(:panel).js true
+
+= render_component :panel do |template|
+  = template.block(:panel) do |panel|
+    = panel.cls :panel, :panel_success
+    = panel.bem true
+    = panel.js true
+```
+
+Выбрать все блоки(с любым названием) и выключить генерацию данных связанных с БЭМ методологией:
+```slim
+/ Эквивалентные записи
+= render_component :panel do |template|
+  = template.block.bem false
+
+= render_component :panel do |template|
+  = template.block('*').bem false
+```
+
+Выбрать блоки без названия и выключить генерацию данных связанных с БЭМ методологией:
+```slim
+= render_component :panel do |template|
+  = template.block('').tag false
+```
+
+Выбрать все блоки которые занимают первую позицию среди своих братьев/сестер(siblings) и заменить их на строку `'Plain text'`:
+```slim
+= render_component :panel do |template|
+  = template.block('*', ->(node) { node.first? }).replace 'Plain text'
+```
+
+Выбрать блоки у которых есть микс `block__elem` и заменить их содержимое на строку `'Plain text'`:
+```slim
+= render_component :panel do |template|
+  = template.block(mix: { block: :elem }).content 'Plain text'
+```
+
+Выбрать блоки у которых есть модификатор с названием `enabled` и значением `true` и добавить `js` атрибуты:
+```slim
+= render_component :panel do |template|
+  = template.block(mods: :enabled).js true
+```
+
+#### Предикат `elem`
+
+С помощью предиката `elem` можно задать условия для выбора узла(ов) с типом элемент по БЭМ методологии в структуре/дереве компонента.
+
+В качестве параметров можно указать:
+1. [Название элемента](%D0%A5%D0%B5%D0%BB%D0%BF%D0%B5%D1%80-elem_tag.md#%D0%9D%D0%B0%D0%B7%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5-%D1%81%D1%83%D1%89%D0%BD%D0%BE%D1%81%D1%82%D0%B8) как `String` или `Symbol`, по умолчанию равно `'*'`.
+1. Вторым параметром можно передать условие, которым может быть `Proc`, `lambda`, название метода или какое-либо выражение, для `Proc` и `lambda` в качестве аргумента будет передан контекст (context) узла, для которого происходит проверка условий.
+1. `block` [название блока](%D0%A5%D0%B5%D0%BB%D0%BF%D0%B5%D1%80-block_tag.md#%D0%9D%D0%B0%D0%B7%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5-%D1%81%D1%83%D1%89%D0%BD%D0%BE%D1%81%D1%82%D0%B8), как `String` или `Symbol`, по умолчанию равно `'*'`.
+1. `mods` задает список модификаторов которые должны присутствовать в списке модификаторов узла.
+1. `mix` задает список миксов которые должны присутствовать в списке миксов узла.
+
+##### Примеры
+
+Выбрать элементы с названием `heading` и заменить их контент/содержимое:
+```slim
+= render_component :panel do |template|
+  = template.elem(:heading).content
+    h3.panel-title Panel title
+```
+
+Выбрать элементы с названием `heading` и применить несколько режимов:
+```slim
+/ Эквивалентные записи
+= render_component :panel do |template|
+  = template.elem(:heading).cls :css_class
+  = template.elem(:heading).bem true
+  = template.elem(:heading).js true
+
+= render_component :panel do |template|
+  = template.elem(:heading) do |heading|
+    = heading.cls :css_class
+    = heading.bem true
+    = heading.js true
+```
+
+Выбрать все элементы(с любым названием) и выключить генерацию данных связанных с БЭМ методологией:
+```slim
+/ Эквивалентные записи
+= render_component :panel do |template|
+  = template.elem.bem false
+
+= render_component :panel do |template|
+  = template.elem('*', block: '*').bem false
+```
+
+Выбрать элементы без названия и отключить отображение HTML тега:
+```slim
+= render_component :panel do |template|
+  = template.elem('').tag ''
+```
+
+Выбрать все элементы которые занимают последнюю позицию среди своих братьев/сестер(siblings) и заменить их на строку `'Plain text'`:
+```slim
+= render_component :panel do |template|
+  = template.elem('*', ->(node) { node.last? }).replace 'Plain text'
+```
+
+Выбрать элементы у которых есть микс `block__elem` и заменить HTML атрибуты:
+```slim
+= render_component :panel do |template|
+  = template.block(mix: 'block__elem' }).attrs key: :val
+```
+
+Выбрать элементы у которых есть модификатор с названием `theme` и значением `green_islands` и добавить `js` атрибуты:
+```slim
+= render_component :panel do |template|
+  = template.elem(mods: { theme: :green_islands }).js key: :val
+```
+
+#### Предикат `match`
+
+С помощью предиката `match` можно задать условия для выбора узла(ов) с типом блок и/или элемент по БЭМ методологии в структуре/дереве компонента. Если условия заданы для блоков и элементов, тогда необходимо использовать `&block` см. примеры.
+
+В качестве параметров можно указать:
+1. Условие, которым может быть `Proc`, `lambda`, название метода или какое-либо выражение, для `Proc` и `lambda` в качестве аргумента будет передан контекст (context) узла, для которого происходит проверка условий.
+1. `block` название блока, как `String` или `Symbol`, по умолчанию равно `'*'`.
+1. `elem` название элемента, как `String` или `Symbol`, по умолчанию равно `'*'`.
+1. `mods` задает список модификаторов которые должны присутствовать в списке модификаторов узла.
+1. `mix` задает список миксов которые должны присутствовать в списке миксов узла.
+
+##### Примеры
+
+Выбрать все блоки и элементы, и выключить генерацию данных связанных с БЭМ методологией:
+```slim
+/ Эквивалентные записи
+= render_component :panel do |template|
+  = template.match do |block, elem|
+    = block.bem false
+    = elem.bem false
+
+= render_component :panel do |template|
+  = template.match(block: '*', elem: '*') do |block, elem|
+    = block.bem false
+    = elem.bem false
+```
+
+Выбрать блоки без названия и отключить отображение HTML тега:
+```slim
+/ Эквивалентные записи
+= render_component :panel do |template|
+  = template.match(block: '', elem: false).tag ''
+
+= render_component :panel do |template|
+  = template.match(block: '', elem: nil).tag ''
+```
+Выбрать все элементы и отключить отображение HTML тега:
+```slim
+/ Эквивалентные записи
+= render_component :panel do |template|
+  = template.match(block: false).tag ''
+
+= render_component :panel do |template|
+  = template.match(block: nil).tag ''
+```
+
+Использование других параметров такое же как у предикатов `block` и `elem`.
+
+#### Указание дополнительных условий с помощью `specify`
+
+Метод `specify` позволяет указать дополнительные (уточнить) условия для предиката (выстроить цепочку условий), с учетом, что они еще не были объявлены до этого, есть исключения:
+
+1. Название блока можно переопределить если оно равно `'*'`
+1. Название элемента можно переопределить если оно равно `'*'` или `nil`
+1. Условие которое идет вторым параметром у предикат `block` `elem` и первым параметром у `match` можно переопределять всегда
+1. Параметры `mix` и `mods` можно переопределить если они еще не были объявлены
+
+##### Примеры
+
+```slim
+= render_component :panel do |template|
+  = template.block(mix: :block) do |block|
+    = block.specify(block: :block1).tag false
+    = block.specify(block: :block2).tag true
+```

data/docs//320/240/320/265/320/266/320/270/320/274/321/213.md

@@ -0,0 +1,274 @@
+# Режимы
+
+**ВАЖНО**. *Только для компонент, [структура (дерево) которых была создана](Создание-и-использование-UI-компонент.md) с помощью [хелпера `define_component`](Хелпер-define_component.md) доступно использование [BEMHTML шаблонов](Шаблоны.md).*
+
+**ВАЖНО**. *Количество режимов и правила их использования отличаются от [bem-xjst](https://github.com/bem/bem-xjst/blob/f69293e95672e387ee5f734c253bb5829654974c/docs/ru/5-templates-syntax.md#Описание-стандартных-режимов).*
+
+**ВАЖНО**. *Порядок поиска и применения шаблонов такой же как и в [bem-xjst](https://github.com/bem/bem-xjst/blob/f69293e95672e387ee5f734c253bb5829654974c/docs/ru/7-runtime.md#Как-выбираются-и-применяются-шаблоны).*
+
+Режимы (моды, modes) позволяют производить различные манипуляции (добавлять/изменять/заменять/удалять) над узлами дерева (структуры). При работе с BEMHTML шаблонами доступно 9 основных и 4 вспомогательных режима.
+
+Для всех примеров используется файловая структура:
+```
+app/
+  ├── assets/
+  |     ├── javascripts/
+  |     |     └── application.js
+  |     └── stylesheets/
+  |           └── application.css
+  ├── bemer_components/
+  |     ├── common/
+  |     |     ├── alert/
+  |     |     |     ├── index.html.slim
+  |     |     |     ├── index.bemhtml.slim
+  |     |     |     ├── index.js
+  |     |     |     └── index.css
+  |     |     └── ...
+  |     └── ...
+  └── ...
+```
+Подключение технологий JavaScript и CSS компонента `alert` при использование Sprockets:
+
+```js
+// Файл app/assets/javascripts/application.js
+//= require common/alert
+```
+
+```scss
+// Файл app/assets/stylesheets/application.css
+//= require common/alert
+```
+
+В качестве структуры компонента `alert` будет взят [компонент `alert` из библиотеки Twitter Bootstrap](https://getbootstrap.com/docs/3.3/components/#alerts):
+
+```html
+<!-- Исходная HTML структура компонента alert из библиотеки Twitter Bootstrap -->
+<div class="alert alert-info alert-dismissible" role="alert">
+  <button type="button" class="close" data-dismiss="alert">
+    <span aria-hidden="true">&times;</span>
+  </button>
+  <strong>Warning!</strong> Better check yourself, you're not looking too good.
+</div>
+```
+Возможный вариант разметки компонента `alert` по БЭМ методологии:
+```slim
+/ Содержимое файла index.html.slim компонента alert
+= define_component bem_cascade: false do |component|
+  = component.block :alert, tag: :div, cls: 'alert alert-dismissible', role: :alert do |alert|
+    = alert.elem :close, type: :button, tag: :button, cls: :close, data: { dismiss: :alert }
+      span aria-hidden='true' &times;
+    = alert.elem :message, tag: false
+      strong> Warning!
+      | Better check yourself, you're not looking too good.
+```
+Возможный вариант шаблонов по умолчанию для компонента `alert`:
+```slim
+/ Содержимое файла index.bemhtml.slim компонента alert
+= define_templates do |template|
+  = template.block(:alert).add_cls :alert_info
+```
+HTML структура компонента `alert` после вызова `render_component`:
+```slim
+/ Шаблонизатор Slim
+= render_component 'common/alert'
+
+/ =>
+/ <div role="alert" class="alert alert-dismissible alert-info">
+/   <button type="button" data-dismiss="alert" class="close">
+/     <span aria-hidden="true">×</span>
+/   </button>
+/   <strong>Warning!</strong> Better check yourself, you're not looking too good.
+/ </div>
+```
+
+## Основные режимы
+
+Список основных режимов и порядок их применения: `replace`, `content`, `tag`, `cls`, `attrs`, `bem`, `mods`, `mix`, `js`.
+
+### Режим `replace`
+
+**ВАЖНО**. *Режим `content` работает быстрее режима `replace`.*
+
+**ВАЖНО**. *В тело шаблона вторым параметром передается билдер (builder) компонента.*
+
+**ВАЖНО**. *Методы `ctx` и `content` доступны ТОЛЬКО в режимах `replace` и `content`*.
+
+Заменяет/удаляет узел в дереве(структуре) компонента.
+
+Аргументом метода (телом шаблона) может быть `String`, `Proc`, `lambda` или `&block`.
+
+Найти элемент `message` и заменить на другой текст:
+```slim
+/ Шаблонизатор Slim
+= render_component 'common/alert' do |template|
+  = template.elem(:message).replace
+    strong> Heads up!
+    | This
+    =< link_to 'alert needs your attention', '#', class: 'alert-link'
+    | , but it's not super important.
+
+/ =>
+/ <div role="alert" class="alert alert-dismissible alert-info">
+/   <button type="button" data-dismiss="alert" class="close">
+/     <span aria-hidden="true">×</span>
+/   </button>
+/   <strong>Heads up!</strong>
+/   This <a class="alert-link" href="#">alert needs your attention</a>,
+/   but it's not super important.
+/ </div>
+```
+
+Найти элемент `close` и заменить на пустую строку, т.е. будет выполнено удаление:
+```slim
+/ Шаблонизатор Slim
+= render_component 'common/alert' do |template|
+  = template.elem(:close).replace
+
+/ =>
+/ <div role="alert" class="alert alert-dismissible alert-info">
+/   <strong>Warning!</strong> Better check yourself, you're not looking too good.
+/ </div>
+```
+
+### Режим `content`
+
+**ВАЖНО**. *Режим `content` работает быстрее режима `replace`.*
+
+**ВАЖНО**. *В тело шаблона вторым параметром передается билдер (builder) компонента.*
+
+**ВАЖНО**. *Методы `ctx` и `content` доступны ТОЛЬКО в режимах `replace` и `content`*.
+
+Заменяет/удаляет содержимое узла в дереве(структуре) компонента.
+
+Аргументом метода (телом шаблона) может быть `String`, `Proc`, `lambda` или `&block`.
+
+Пример из режима `replace`, будет работать быстрее для режима `content`:
+```slim
+/ Шаблонизатор Slim
+= render_component 'common/alert' do |template|
+  = template.elem(:message).content
+    strong> Heads up!
+    | This
+    =< link_to 'alert needs your attention', '#', class: 'alert-link'
+    | , but it's not super important.
+
+/ =>
+/ <div role="alert" class="alert alert-dismissible alert-info">
+/   <button type="button" data-dismiss="alert" class="close">
+/     <span aria-hidden="true">×</span>
+/   </button>
+/   <strong>Heads up!</strong>
+/   This <a class="alert-link" href="#">alert needs your attention</a>,
+/   but it's not super important.
+/ </div>
+```
+
+### Режим `tag`
+
+Изменяет [параметр `tag`, кроме допустимых значений](%D0%A5%D0%B5%D0%BB%D0%BF%D0%B5%D1%80-block_tag.md#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-tag) аргументом (телом шаблона) может быть `Proc` и `lambda`.
+
+### Режим `cls`
+
+Изменяет [параметр `cls`, кроме допустимых значений](%D0%A5%D0%B5%D0%BB%D0%BF%D0%B5%D1%80-block_tag.md#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-cls-%D1%81%D0%B8%D0%BD%D0%BE%D0%BD%D0%B8%D0%BC-class) аргументом (телом шаблона) может быть `Proc` и `lambda`.
+
+### Режим `attrs`
+
+Изменяет [HTML атрибуты](%D0%A5%D0%B5%D0%BB%D0%BF%D0%B5%D1%80-block_tag.md#%D0%90%D1%82%D1%80%D0%B8%D0%B1%D1%83%D1%82%D1%8B), аргументом (телом шаблона) может быть `Hash`, `Proc`, `lambda` или `Array`.
+
+### Режим `bem`
+
+Изменяет [параметр `bem`, кроме допустимых значений](%D0%A5%D0%B5%D0%BB%D0%BF%D0%B5%D1%80-block_tag.md#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-bem) аргументом (телом шаблона) может быть `Proc` и `lambda`.
+
+### Режим `mods`
+
+Изменяет [параметр `mods`, кроме допустимых значений](%D0%A5%D0%B5%D0%BB%D0%BF%D0%B5%D1%80-block_tag.md#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-mods) аргументом (телом шаблона) может быть `Proc` и `lambda`.
+
+### Режим `mix`
+
+Изменяет [параметр `mix`, кроме допустимых значений](%D0%A5%D0%B5%D0%BB%D0%BF%D0%B5%D1%80-block_tag.md#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-mix) аргументом (телом шаблона) может быть `Proc` и `lambda`.
+
+### Режим `js`
+
+Изменяет [параметр `js`, кроме допустимых значений](%D0%A5%D0%B5%D0%BB%D0%BF%D0%B5%D1%80-block_tag.md#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-js) аргументом (телом шаблона) может быть `Proc` и `lambda`.
+
+## Вспомогательные режимы
+
+**ВАЖНО**. *Вспомогательные режимы это всего лишь синтаксический сахар (syntactic sugar) для некоторых основных режимов.*
+
+Список вспомогательных режимов: `add_attrs`, `add_cls`, `add_mix`, `add_mods`.
+
+### Режим `add_attrs`
+
+**ВАЖНО**. *Аргументы такие же как и у режима `attrs`.*
+
+Добавляет HTML атрибуты.
+
+```slim
+/ Эквивалентные записи
+= render_component 'common/alert' do |template|
+  = template.block(:alert).add_attrs key: :value
+
+= render_component 'common/alert' do |template|
+  = template.block(:alert).attrs ->(node) { node.apply_next.merge!(key: :value) }
+
+= render_component 'common/alert' do |template|
+  = template.block(:alert).attrs ->(node) { node.apply(:attrs).merge!(key: :value) }
+```
+
+### Режим `add_cls`
+
+**ВАЖНО**. *Аргументы такие же как и у режима `cls`.*
+
+Добавляет css классы.
+
+```slim
+/ Эквивалентные записи
+= render_component 'common/alert' do |template|
+  = template.block(:alert).add_cls :css_class
+
+= render_component 'common/alert' do |template|
+  = template.block(:alert).cls ->(node) { node.apply_next << :css_class }
+
+= render_component 'common/alert' do |template|
+  = template.block(:alert).cls ->(node) { node.apply(:cls) << :css_class }
+```
+
+### Режим `add_mix`
+
+**ВАЖНО**. *Аргументы такие же как и у режима `mix`.*
+
+Добавляет миксы.
+
+```slim
+/ Эквивалентные записи
+= render_component 'common/alert' do |template|
+  = template.block(:alert).add_mix block: :elem
+
+= render_component 'common/alert' do |template|
+  = template.block(:alert).mix ->(node) { node.apply_next << { block: :elem } }
+
+= render_component 'common/alert' do |template|
+  = template.block(:alert).mix ->(node) { node.apply(:mix) << { block: :elem } }
+
+/ С использованием хелпера bem_mix
+= render_component 'common/alert' do |template|
+  = template.block(:alert).mix ->(node) { node.apply(:mix) << bem_mix(block: :elem) }
+```
+
+### Режим `add_mods`
+
+**ВАЖНО**. *Аргументы такие же как и у режима `mods`.*
+
+Добавляет модификаторы.
+
+```slim
+/ Эквивалентные записи
+= render_component 'common/alert' do |template|
+  = template.block(:alert).add_mods :enabled
+
+= render_component 'common/alert' do |template|
+  = template.block(:alert).mods ->(node) { node.apply_next.merge!(enabled: true) }
+
+= render_component 'common/alert' do |template|
+  = template.block(:alert).mods ->(node) { node.apply(:mods).merge!(enabled: true) }
+```