bemer 0.1.0 → 0.2.0

data/docs//320/245/320/265/320/273/320/277/320/265/321/200-block_tag.md

@@ -0,0 +1,215 @@
+# Хелпер block_tag
+
+**ВАЖНО**. *Только для компонент, [структура (дерево) которых была создана](Создание-и-использование-UI-компонент.md) с помощью [хелпера `define_component`](Хелпер-define_component.md) доступно использование [BEMHTML шаблонов](Шаблоны.md).*
+
+**ВАЖНО**. *Для сущностей у которых не указано название, не будут созданы css классы и js атрибуты из методологии БЭМ*:
+```ruby
+block_tag js: true, bem: true # => <div></div>
+```
+
+**ВАЖНО**. *[Параметр `bem` из конфигурации](Конфигурация.md#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-bem) никак не влияет на работу `block_tag`.*
+
+**ВАЖНО**. *Использование строковых (`String`) ключей при передаче параметров не допустимо, ключами могут быть только сиволы (`Symbol`).*
+
+Позволяет создавать блок по методологии БЭМ.
+
+## Название сущности
+
+При вызове `block_tag` первым аргументом передается название блока (указывать не обязательно) допустимые типы:
+1. `Symbol` ВСЕ символы нижнего подчеркивания будут преобразованы в тире, при формирование css классов по методологии БЭМ
+1. `String` возвращается без изменений
+
+```ruby
+# Вызов без каких-либо параметров
+block_tag # => <div></div>
+```
+```ruby
+block_tag :block_name # => <div class="block-name"></div>
+```
+
+**ВАЖНО**. *Будьте ВНИМАТЕЛЬНЫ при использовании названий с типом `String`, если в них содержатся знаки нижнего подчеркивания `_`, это может привести к неправильному результату согласно методологии БЭМ*:
+```ruby
+block_tag 'block_name' # => <div class="block_name"></div>
+```
+
+## Допустимые параметры
+
+`bem`, `bem_cascade`, `cls` (синоним `class`), `content`, `js`, `mix`, `mods` и `tag`, все остальные переданные параметры с названиями не из этого списка будут считаться атрибутами.
+
+### Параметр `bem`
+
+Разрешает или запрещает использовать методологию БЭМ при создании текущего блока.
+
+```ruby
+block_tag :block, bem: true  # => <div class="block"></div>
+block_tag :block, bem: false # => <div></div>
+block_tag :block, bem: nil # => <div class="block"></div>
+```
+
+### Параметр `bem_cascade`
+
+Разрешает или запрещает использовать методологию БЭМ для текущего блока и ТОЛЬКО всех его элементов (в [хелпере `define_component` используется для ВСЕХ ДОЧЕРНИХ ЭЛЕМЕНТОВ см. описание параметра `content`](#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-content))
+
+```ruby
+block_tag :block, bem_cascade: true  # => <div class="block"></div>
+block_tag :block, bem_cascade: false # => <div></div>
+```
+
+Имеет меньший приоритет чем параметр `bem`:
+
+```ruby
+block_tag :block, bem_cascade: true, bem: false # => <div></div>
+block_tag :block, bem_cascade: false, bem: true # => <div class="block"></div>
+```
+
+### Параметр `cls` синоним `class`
+
+Добавляет css классы.
+
+```ruby
+block_tag :block, cls: 'class-1', bem: false  # => <div class="class-1"></div>
+block_tag :block, class: 'class-1', bem: true # => <div class="block class-1"></div>
+```
+ВСЕ символы нижнего подчеркивания будут преобразованы в тире, если класс передан как `Symbol`:
+
+```ruby
+block_tag :block, cls: ['cls_1', :cls_2], bem: false # => <div class="cls_1 cls-2"></div>
+```
+
+### Параметр `content`
+
+Добавляет содержимое для блока.
+
+```ruby
+block_tag :block, content: 'Block content' # => <div>Block content</div>
+```
+Если передан `Ruby &block`, тогда параметр `content` игнорируется:
+
+```slim
+/ Шаблонизатор Slim
+= block_tag :block, content: 'Block content', bem: false do
+  h1 Content from Ruby &block
+
+/ => <div><h1>Content from Ruby &block</h1></div>
+```
+Для блоков доступно альтернативное создание элементов:
+
+```slim
+/ Шаблонизатор Slim
+= block_tag :block, bem_cascade: true do |block|
+  = block.elem :elem_1 do
+    = block.elem :elem_2 do
+      span Elem 2 content
+
+/ =>
+/<div class="block">
+/   <div class="block__elem-1">
+/     <div class="block__elem-2">
+/       <span>Elem 2 content</span>
+/     </div>
+/   </div>
+/ </div>
+
+= block_tag :block, bem_cascade: false, bem: true do |block|
+  = block.elem :elem_1 do
+    = block.elem :elem_2 do
+      span Elem 2 content
+
+/ =>
+/ <div class="block">
+/   <div>
+/     <div>
+/       <span>Elem 2 content</span>
+/     </div>
+/   </div>
+/ </div>
+
+= block_tag :block, bem_cascade: false, bem: true do |block|
+  = block.elem :elem_1, bem: true do
+    = block.elem :elem_2 do
+      span Elem 2 content
+/ =>
+/ <div class="block">
+/   <div class="block__elem-1">
+/     <div>
+/       <span>Elem 2 content</span>
+/     </div>
+/   </div>
+/ </div>
+```
+
+
+### Параметр `js`
+
+Создает атрибут `data-bem` и css класс `i-bem`.
+
+```ruby
+block_tag :block, js: true, bem: true
+# => <div class="block i-bem" data-bem="{"block":{}}"></div>
+
+block_tag :block, js: [1, 2], bem: true
+# => <div class="block i-bem" data-bem="{"block":[1,2]}"></div>
+
+block_tag :block, js: { key: :val }, bem: true
+# => <div class="block i-bem" data-bem="{"block":{"key":"val"}}"></div>
+
+block_tag :block, js: true, bem: false # => <div></div>
+```
+Для блока без имени js атрибуты не создаются:
+```ruby
+block_tag js: true, bem: true # => <div></div>
+```
+### Параметр `mix`
+
+Добавляет миксы подробнее см. [хелпер `bem_mix`](Хелпер-bem_mix.md).
+
+```ruby
+block_tag :block, mix: [:mix_1, block_1: :elem], bem: true
+# => <div class="block mix-1 block-1__elem"></div>
+
+block_tag :block, mix: { block_1: :elem }, bem: true
+# => <div class="block block-1__elem"></div>
+```
+
+### Параметр `mods`
+
+Добавляет модификаторы подробнее см. [хелпер `bem_mods`](Хелпер-bem_mods.md).
+
+```ruby
+block_tag :block, mods: :enabled, bem: true
+# => <div class="block block_enabled"></div>
+
+block_tag :block, mods: [:enabled, size: :small], bem: true
+# => <div class="block block_enabled block_size_small"></div>
+
+block_tag :block, mods: { size: :small }, bem: true
+# => <div class="block block_size_small"></div>
+```
+
+### Параметр `tag`
+
+Добавляет или удаляет html тег, допустимые значения: `Symbol`, `String`, `false` и `nil`.
+
+```ruby
+block_tag :block, tag: :span, content: 'Block content'
+# => <span>Block content</span>
+
+block_tag :block, tag: '', content: 'Block content'
+# => 'Block content'
+
+block_tag :block, tag: false, content: 'Block content'
+# => 'Block content'
+
+# Будет использован default_block_tag из конфига
+block_tag :block, tag: nil, content: 'Block content'
+# => <div>Block content</div>
+```
+
+### Атрибуты
+
+Любой параметр с названием не из [списка допустимых параметров](#%D0%94%D0%BE%D0%BF%D1%83%D1%81%D1%82%D0%B8%D0%BC%D1%8B%D0%B5-%D0%BF%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80%D1%8B) считается атрибутом:
+
+```ruby
+block_tag :block, data: { key: :val } # => <div data-key="val"></div>
+block_tag :block, key: :val           # => <div key="val"></div>
+```

data/docs//320/245/320/265/320/273/320/277/320/265/321/200-component_asset_path.md

@@ -0,0 +1,71 @@
+# Хелпер component_asset_path
+
+**ВАЖНО**. *Необходимо делать прекомпиляцию ресурсов, с помощью `sprockets` или `webpacker`.*
+
+Хелпер `component_asset_path` возвращает путь до ресурса (asset) компонента: изображения, файла и т.д. При вызове, хелперу необходимо передать название ресурса (asset).
+
+Для примеров используется следующая файловая структура:
+
+```
+app/
+  ├── bemer_components/
+  |     ├── image_gallery/
+  |     |     ├── images/
+  |     |     |     ├── placeholder.jpg
+  |     |     |     └── ...
+  |     |     ├── _image.html.slim
+  |     |     ├── index.html.slim
+  |     |     ├── index.js
+  |     |     ├── index.scss
+  |     |     └── ...
+  |     ├── user_profile/
+  |     |     ├── images/
+  |     |     |     ├── placeholder.jpg
+  |     |     |     └── ...
+  |     |     ├── index.html.slim
+  |     |     ├── index.js
+  |     |     ├── index.scss
+  |     |     └── ...
+  |     └── ...
+  ├── views/
+  |     ├── users/
+  |     |     ├── show.html.slim
+  |     |     └── ...
+  |     ├── images/
+  |     |     ├── index.html.slim
+  |     |     └── ...
+  |     └── ...
+  └── ...
+```
+
+## Использование
+
+```slim
+/ app/bemer_components/user_profile/index.html.slim
+
+= component_asset_path('images/placeholder.jpg') / => 'user_profile/images/placeholder.jpg'
+= component_asset_path('image_gallery/images/placeholder.jpg') / => 'image_gallery/images/placeholder.jpg'
+
+```
+
+```slim
+/ app/bemer_components/image_gallery/_image.html.slim
+
+= component_asset_path('images/placeholder.jpg') / => 'image_gallery/images/placeholder.jpg'
+= component_asset_path('user_profile/images/placeholder.jpg') / => 'user_profile/images/placeholder.jpg'
+
+```
+
+```slim
+/ app/views/users/show.html.slim
+
+= component_asset_path('user_profile/images/placeholder.jpg') / => 'user_profile/images/placeholder.jpg'
+
+```
+
+```slim
+/ app/views/images/index.html.slim
+
+= component_asset_path('image_gallery/images/placeholder.jpg') / => 'image_gallery/images/placeholder.jpg'
+
+```

data/docs//320/245/320/265/320/273/320/277/320/265/321/200-component_pack.md

@@ -0,0 +1,101 @@
+# Хелпер component_pack
+
+**ВАЖНО**. *`component_pack` и параметр `cached: true` позволяют лишь в некоторых случаях пропускать перекомпиляцию одних и тех же шаблонов для технологии BEMHTML, дополнительно к этому обязательно используйте кэширование которое [доступно в Rails](http://rusrails.ru/caching-with-rails-an-overview)*.
+
+Использование `component_pack` и `cached: true` может пригодиться только в том случае, когда один и тот же компонент(ы) нужно вывести в одном месте несколько раз (используя цикл), при этом шаблоны этого компонента или используемые внутри его вызовы других компонент не зависят от итераций, для всех итераций шаблоны у них будут одни и те же (нет динамических данных в шаблонах BEMHTML).
+
+Для всех примеров используется файловая структура:
+```
+app/
+  ├── assets/
+  |     ├── javascripts/
+  |     |     └── application.js
+  |     └── stylesheets/
+  |           └── application.css
+  ├── bemer_components/
+  |     ├── common/
+  |     |     ├── alert/
+  |     |     |     ├── index.html.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.
+```
+## Примеры
+
+### Без использования `component_pack` с параметром `cached: true`
+
+После каждой итерации, скомпилированные шаблоны компонента `alert` и шаблоны других компонент (в примере их нет), которые были созданы при вызове `render_component :alert` будут удалены, поэтому `cached: true` при вызове компонента `alert` не влияет на результат:
+```slim
+- %i[success info warning danger].each do |alert_type|
+  = render_component :alert, cached: true do |template|
+    = template.block(:alert).add_cls "alert-#{alert_type}"
+      = template.elem(:message).content
+        strong = "Alert type: #{alert_type}"
+```
+![alert-cached-false](images/alert-cached-false.jpg)
+
+### С использованием `component_pack` без параметра `cached` (`cached: false`)
+
+Если у компонента есть в шаблонах вызов других компонент с параметром `cached: true` или присутствуют [шаблоны по умолчанию (у `define_templates` по умолчанию параметр `cached` равен `true`)](Хелпер-define_templates.md) тогда для каждой итерации будут использоваться шаблоны из кэша (скомпилированные при первой итерации).
+
+Шаблоны для компонента `alert` не кэшируются потому что не был передан параметр `cached: true`
+
+```slim
+= component_pack do
+  - %i[success info warning danger].each do |alert_type|
+    = render_component :alert do |template|
+      = template.block(:alert).add_cls "alert-#{alert_type}"
+        = template.elem(:message).content
+          strong = "Alert type: #{alert_type}"
+```
+![alert-cached-false](images/alert-cached-false.jpg)
+
+### С использованием `component_pack` и параметром `cached: true`
+
+Для всех итераций используются шаблоны которые были получены при первой итерации:
+```slim
+= component_pack do
+  - %i[success info warning danger].each do |alert_type|
+    = render_component :alert, cached: true do |template|
+      = template.block(:alert).add_cls "alert-#{alert_type}"
+        = template.elem(:message).content
+          strong = "Alert type: #{alert_type}"
+```
+
+![alert-cached-true](images/alert-cached-true.jpg)

data/docs//320/245/320/265/320/273/320/277/320/265/321/200-component_partial_path.md

@@ -0,0 +1,28 @@
+# Хелпер component_partial_path
+
+Хелпер `component_partial_path` возвращает путь до партиала (partial) в каталоге компонента. При вызове хелпера необходимо передать название партиала (partial).
+
+Для примеров используется следующая файловая структура:
+
+```
+app/
+  ├── bemer_components/
+  |     ├── image_gallery/
+  |     |     ├── _image.html.slim
+  |     |     ├── index.html.slim
+  |     |     ├── index.js
+  |     |     ├── index.scss
+  |     |     └── ...
+  └── ...
+```
+
+## Использование
+
+```slim
+/ app/bemer_components/image_gallery/index.html.slim
+
+= component_partial_path(:image) / => 'image_gallery/image'
+
+= render component_partial_path(:image)
+
+```

data/docs//320/245/320/265/320/273/320/277/320/265/321/200-define_component.md

@@ -0,0 +1,154 @@
+# Хелпер define_component
+
+**ВАЖНО**. *Необходимо только описывать структуру (дерево) компонента в терминах (блок и элемент) методологии БЭМ*, **создание `css` классов и `js` атрибутов из методологии БЭМ НЕ ОБЯЗАТЕЛЬНО**.
+
+**ВАЖНО**. *В отличие от хелперов `block_tag` и `elem_tag`, генерация данных из методологии БЭМ зависит от параметра [`bem` в конфигурации](Конфигурация.md#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-bem).*
+
+**ВАЖНО**. *Доступно использование [BEMHTML шаблонов](Шаблоны.md).*
+
+**ВАЖНО**. *Для сущностей у которых не указано название, не будут созданы css классы и js атрибуты из методологии БЭМ*.
+
+Хелпер `define_component` позволяет описывать структуру (дерево) компонента с помощью сущностей (блок и элемент) методологии БЭМ, благодаря этому, используя BEMHTML шаблоны можно более продвинутыми способами взаимодействовать с такими типами компонент.
+
+При вызове `define_component` обязательно нужно использовать `&block` в который будет передан билдер (builder) для построения структуры (дерева) компонента.
+
+##  Метод `block`
+
+Принимает такие же параметры как и [хелпер `block_tag`](Хелпер-block_tag.md).
+
+**ВАЖНО**. *В отличие от `block_tag` и `elem_tag`, переданный в текущий узел параметр `bem_cascade` распространяется на сам узел и все его дочерние узлы (блоки и элементы), даже если текущий узел является элементом.*
+
+Позволяет создавать блок из методологии БЭМ:
+```slim
+= define_component do |component|
+  = component.block content: 'Plain text'
+
+= define_component do |component|
+  = component.block :block_name, content: 'Plain text'
+
+= define_component do |component|
+  = component.block
+    span Content
+
+/ bem_cascade: false применится к узлу и ко всем его дочерним узлам
+= define_component do |component|
+  = component.block bem_cascade: false do |block|
+    = component.block :block2 do |block2|
+      = block2.elem :elem
+    = block.elem content: 'Plain text'
+```
+
+##  Метод `elem`
+
+Принимает такие же параметры как и [хелпер `elem_tag`](Хелпер-elem_tag.md).
+
+**ВАЖНО**. *В отличие от `block_tag` и `elem_tag`, переданный в текущий узел параметр `bem_cascade` распространяется на сам узел и все его дочерние узлы (блоки и элементы), даже если текущий узел является элементом.*
+
+Позволяет создавать элемент из методологии БЭМ:
+```slim
+= define_component do |component|
+  = component.elem content: 'Plain text'
+
+= define_component do |component|
+  = component.elem :block_name, :elem_name, content: 'Plain text'
+
+= define_component do |component|
+  = component.elem
+    span Content
+
+/ bem_cascade: true применится к узлу и ко всем его дочерним узлам
+= define_component do |component|
+  = component.elem bem_cascade: true
+    = component.block do |block|
+      = block.elem content: 'Plain text'
+```
+
+##  Метод `text`
+
+**ВАЖНО**. *Переданные параметры через методы `apply`, `apply_next`, `content` и `ctx` не будут использоваться в узлах внутри метода `text`*.
+
+Создает текстовый узел(`TextNode`) в структуре(дереве) компонента, к узлам такого типа **не применяются шаблоны BEMHTML** и значение параметра `tag` указано как `false`, не принимает никаких дополнительных параметров.
+
+Узлы с типом `TextNode` предназначены ТОЛЬКО для расположения текста на определенном уровне в структуре(дереве), чтобы при рендеринге компонента не происходило выталкивание вверх текстовых вставок:
+
+```slim
+/ При такой структуре 'span Content' всплывет на верх
+= define_component bem_cascade: true do |component|
+  = component.block :block_name
+  span Content
+
+/ =>
+/ <span>Content</span>
+/ <div class="block-name"></div>
+
+= define_component bem_cascade: true do |component|
+  = component.block :block_name
+  = component.text
+    span Content
+
+/ =>
+/ <div class="block-name"></div>
+/ <span>Content</span>
+
+= define_component bem_cascade: true do |component|
+  = component.block :block_name
+  = component.text 'Content'
+
+/ =>
+/ <div class="block-name"></div>
+/ Content
+```
+
+В данном случае, результат будет одинаковым, но лучше избегать использование методов `block` и `elem` внутри метода `text`:
+```slim
+= define_component bem_cascade: true do |component|
+  = component.block :block1
+  = component.text
+    = component.block :block2 do |block2|
+      = block2.elem :elem
+
+= define_component bem_cascade: true do |component|
+  = component.block :block1
+  = component.block :block2 do |block2|
+    = block2.elem :elem
+
+/ =>
+/ <div class="block1"></div>
+/ <div class="block2">
+/   <div class="block2__elem"></div>
+/ </div>
+```
+
+##  Параметры по умолчанию
+
+В `define_component` можно передать такие же параметры как и в методы `block` и `elem`, которые будут значениями по умолчанию для узлов дерева (структуры) компонента:
+```slim
+/ Эквивалентные записи
+= define_component do |component|
+  = component.block :block1, tag: :div, js: true, bem: true
+  = component.block :block2, tag: :div, js: true, bem: true do |block2|
+    = block2.elem :elem, tag: :div, js: true, bem: true
+
+= define_component tag: :div, js: true, bem: true do |component|
+  = component.block :block1
+  = component.block :block2 do |block2|
+    = block2.elem :elem
+
+/ =>
+/ <div data-bem="{"block1":{}}" class="block1 i-bem"></div>
+/ <div data-bem="{"block2":{}}" class="block2 i-bem">
+/   <div data-bem="{"block2__elem":{}}" class="block2__elem i-bem"></div>
+/ </div>
+
+/ Переопределение дефолтных значений
+= define_component tag: :div, js: true, bem: true do |component|
+  = component.block :block1, js: false
+  = component.block :block2, js: false do |block2|
+    = block2.elem :elem
+
+/ =>
+/ <div class="block1"></div>
+/ <div class="block2">
+/   <div data-bem="{"block2__elem":{}}" class="block2__elem i-bem"></div>
+/ </div>
+```