bemer 0.1.0 → 0.2.0

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

@@ -0,0 +1,96 @@
+# Хелпер define_templates
+
+**ВАЖНО**. *Только для компонент, структура (дерево) которых была создана с помощью [хелпера `define_component`](Хелпер-define_component.md) доступно использование [BEMHTML шаблонов](Шаблоны.md).*
+
+Позволяет создавать шаблоны по умолчанию (технология BEMHTML) для компонент созданных [с помощью `define_component`](Хелпер-define_component.md).
+
+При вызове `define_templates` можно передать единственный параметр `cached` который по умолчанию равен `true`, см. [хелпер `component_pack`](Хелпер-component_pack.md).
+
+Используется следующая файловая структура:
+```
+app/
+  ├── assets/
+  |     ├── javascripts/
+  |     |     └── application.js
+  |     └── stylesheets/
+  |           └── application.css
+  ├── bemer_components/
+  |     ├── panel/
+  |     |     ├── index.html.slim
+  |     |     ├── index.bemhtml.slim
+  |     |     ├── index.js
+  |     |     └── index.css
+  |     └── ...
+  └── ...
+```
+Подключение технологий JavaScript и CSS компонента `panel` при использовании Sprockets:
+
+```js
+// Файл app/assets/javascripts/application.js
+//= require panel
+```
+
+```scss
+// Файл app/assets/stylesheets/application.css
+//= require panel
+```
+В качестве структуры компонента `panel` будет взят [компонент `panel` из библиотеки Twitter Bootstrap](https://getbootstrap.com/docs/3.3/components/#panels):
+
+```html
+<!-- Исходная HTML структура компонента panel из библиотеки Twitter Bootstrap -->
+<div class="panel panel-default">
+  <div class="panel-heading">
+    <h3 class="panel-title">Panel title</h3>
+  </div>
+  <div class="panel-body">Panel content</div>
+  <div class="panel-footer">Panel footer</div>
+</div>
+```
+Возможный вариант разметки компонента `panel` по БЭМ методологии:
+```slim
+/ Содержимое файла index.html.slim компонента panel
+= define_component bem_cascade: false, tag: :div do |component|
+  = component.block :panel, cls: 'panel' do |panel|
+    = panel.elem :heading, cls: 'panel-heading'
+      = panel.elem :title, tag: :h3, cls: 'panel-title', content: 'Panel title'
+    = panel.elem :content, cls: 'panel-body', content: 'Panel content'
+    = panel.elem :footer, cls: 'panel-footer', content: 'Panel footer'
+```
+
+После рендеринга без применения шаблонов по умолчанию, HTML структура будет выглядеть следующим образом:
+```slim
+/ Шаблонизатор Slim
+= render_component :panel
+
+/ =>
+/ <div class="panel">
+/   <div class="panel-heading">
+/     <h3 class="panel-title">Panel title</h3>
+/   </div>
+/   <div class="panel-body">Panel content</div>
+/   <div class="panel-footer">Panel footer</div>
+/ </div>
+```
+С помощью файла `index.bemhtml.slim` можно задать дефолтные шаблоны для компонента, которые можно будет переопределить при вызове `render_component` или `refine_component`.
+
+Возможный вариант шаблонов по умолчанию для компонента `panel`:
+```slim
+/ Содержимое файла index.bemhtml.slim компонента panel
+= define_templates do |template|
+  = template.block(:panel).add_cls :panel_default
+```
+
+После рендеринга HTML структура теперь будет выглядеть следующим образом (добавлен css класс `panel-default`):
+```slim
+/ Шаблонизатор Slim
+= render_component :panel
+
+/ =>
+/ <div class="panel panel-default">
+/   <div class="panel-heading">
+/     <h3 class="panel-title">Panel title</h3>
+/   </div>
+/   <div class="panel-body">Panel content</div>
+/   <div class="panel-footer">Panel footer</div>
+/ </div>
+```

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

@@ -0,0 +1,38 @@
+# Хелпер elem_tag
+
+**ВАЖНО**. *Только для компонент, [структура (дерево) которых была создана](Создание-и-использование-UI-компонент.md) с помощью [хелпера `define_component`](Хелпер-define_component.md) доступно использование [BEMHTML шаблонов](Шаблоны.md).*
+
+**ВАЖНО**. *Для сущностей у которых не указано название, не будут созданы css классы и js атрибуты из методологии БЭМ*:
+```ruby
+elem_tag js: true, bem: true            # => <div></div>
+elem_tag nil, js: true, bem: true       # => <div></div>
+elem_tag :block, js: true, bem: true    # => <div></div>
+elem_tag '', :elem, 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) никак не влияет на работу `elem_tag`.*
+
+**ВАЖНО**. *Альтернативное создание элементов по методологии БЭМ см. [хелпер `block_tag` параметр `content`](Хелпер-block_tag.md#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-content).*
+
+Позволяет создавать элемент по методологии БЭМ.
+
+## Название сущности
+
+При вызове `elem_tag` первым аргументом передается название блока (указывать не обязательно), вторым название элемента (указывать не обязательно) допустимые типы:
+1. `Symbol` ВСЕ символы нижнего подчеркивания будут преобразованы в тире, при формирование css классов по БЭМ методологии
+1. `String` возвращается без изменений
+
+```ruby
+# Вызов без каких-либо параметров
+elem_tag # => <div></div>
+```
+```ruby
+elem_tag :block, :elem # => <div class="block__elem"></div>
+```
+**ВАЖНО**. *Будьте ВНИМАТЕЛЬНЫ при использовании названий с типом `String`, если в них содержатся знаки нижнего подчеркивания `_`, это может привести к неправильному результату согласно методологии БЭМ*:
+```ruby
+elem_tag 'block_name', 'elem_name' # => <div class="block_name__elem_name"></div>
+```
+## Допустимые параметры
+
+Все параметры такие же как и у [хелпера `block_tag`](Хелпер-block_tag.md#%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).

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

@@ -0,0 +1,114 @@
+# Хелпер refine_component
+
+**ВАЖНО**. *Является псевдонимом для `render_component`.*
+
+**ВАЖНО**. *Только для компонент, структура (дерево) которых была создана с помощью [хелпера `define_component`](Хелпер-define_component.md) доступно использование [BEMHTML шаблонов](Шаблоны.md).*
+
+**ДОПОЛНИТЕЛЬНО**. *Различные способы создания и рендеринга компонент описаны [здесь](Создание-и-использование-UI-компонент.md).*
+
+Соглашения по использованию:
+1. `render_component` используется для рендеринга компонент
+1. `refine_component` используется для создания новых компонент на основе существующих, реализованных [с помощью `define_component`](Хелпер-define_component.md)
+
+Используя `refine_component` можно получать HTML структуру компонента, а если компонент был создан [с помощью `define_component`](Хелпер-define_component.md) тогда и изменять его структуру/внешний вид с помощью шаблонов BEMHTML.
+
+Все передаваемые параметры будут доступны в теле компонента как локальные переменные, исключение составляют параметры `cached` и `prefix`.
+
+Используется следующая файловая структура:
+```
+app/
+  ├── assets/
+  |     ├── javascripts/
+  |     |     └── application.js
+  |     └── stylesheets/
+  |           └── application.css
+  ├── bemer_components/
+  |     ├── progress/
+  |     |     ├── index.html.slim
+  |     |     ├── index.js
+  |     |     └── index.css
+  |     ├── stacked_progress/
+  |     |     └── index.html.slim
+  |     └── ...
+  └── ...
+```
+Подключение технологий JavaScript и CSS компонента `progress` при использовании Sprockets:
+
+```js
+// Файл app/assets/javascripts/application.js
+//= require progress
+```
+
+```scss
+// Файл app/assets/stylesheets/application.css
+//= require progress
+```
+В качестве структуры компонента `progress` будет взят [компонент `Progress bar` из библиотеки Twitter Bootstrap](https://getbootstrap.com/docs/3.3/components/#progress):
+
+```html
+<!-- Исходная HTML структура компонента Progress bar из библиотеки Twitter Bootstrap -->
+<div class="progress">
+  <div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
+    60%
+  </div>
+</div>
+```
+Возможный вариант разметки компонента `progress` с использованием `define_component` по методологии БЭМ:
+```slim
+/ Содержимое файла index.html.slim компонента panel
+= define_component bem_cascade: false, tag: :div do |component|
+  = component.block :progress, cls: :progress do |progress|
+    = progress.elem :bar, role: :progressbar, cls: :progress_bar, 'aria-valuemin': 0, 'aria-valuemax': 100
+```
+## Создание нового компонента на основе существующего
+
+Для компонент структура которых была создана [с помощью `define_component`](Хелпер-define_component.md), можно делать переопределение структуры (дерева).
+
+Создание компонента [`stacked_progress`](https://getbootstrap.com/docs/3.3/components/#progress-stacked) на основе компонента `progress`:
+
+```slim
+/ Содержимое файла index.html.slim компонента stacked_progress
+= refine_component :progress do |template|
+  = template.block(:progress) do |progress|
+    = progress.content do |node|
+      = node.content
+      = node.content
+      = node.content
+
+/ Эквивалентная запись
+= refine_component :progress do |template|
+  = template.block(:progress) do |progress|
+    = progress.content do |node|
+      - 3.times do
+        = node.content
+
+```
+Теперь можно вызвать новый компонент `stacked_progress`:
+```slim
+= render_component :stacked_progress do |template|
+  = template.elem :bar do |bar|
+    = bar.add_cls :progress_bar_striped, :active
+    = bar.specify(->(node) { node.first? }) do |first_bar|
+      = first_bar.add_attrs 'aria-valuenow': 20, style: 'width: 20%'
+      = first_bar.add_cls :progress_bar_danger
+    = bar.specify(->(node) { node.position.eql?(2) }) do |middle_bar|
+      = middle_bar.add_attrs 'aria-valuenow': 30, style: 'width: 30%'
+      = middle_bar.add_cls :progress_bar_warning
+    = bar.specify(->(node) { node.last? }) do |last_bar|
+      = last_bar.add_attrs 'aria-valuenow': 40, style: 'width: 40%'
+      = last_bar.add_cls :progress_bar_success
+
+/ =>
+/ <div class="progress">
+/   <div role="progressbar" aria-valuenow="20" aria-valuemin="0" aria-valuemax="100" style="width: 20%" class="progress-bar progress-bar-striped active progress-bar-danger"></div>
+/   <div role="progressbar" aria-valuenow="30" aria-valuemin="0" aria-valuemax="100" style="width: 30%" class="progress-bar progress-bar-striped active progress-bar-warning"></div>
+/   <div role="progressbar" aria-valuenow="40" aria-valuemin="0" aria-valuemax="100" style="width: 40%" class="progress-bar progress-bar-striped active progress-bar-success"></div>
+/ </div>
+```
+## Параметр `prefix`
+
+Для чего нужен и как использовать параметр `prefix` можно прочитать [здесь](Конфигурация.md#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-default_path_prefix).
+
+## Параметр `cached`
+
+Описание про `cached` можно найти [в `component_pack`](Хелпер-component_pack.md).

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

@@ -0,0 +1,108 @@
+# Хелпер render_component
+
+**ВАЖНО**. *Является псевдонимом для `refine_component`.*
+
+**ВАЖНО**. *Только для компонент, структура (дерево) которых была создана с помощью [хелпера `define_component`](Хелпер-define_component.md) доступно использование [BEMHTML шаблонов](Шаблоны.md).*
+
+**ДОПОЛНИТЕЛЬНО**. *Различные способы создания и рендеринга компонент описаны [здесь](Создание-и-использование-UI-компонент.md).*
+
+Соглашения по использованию:
+1. `render_component` используется для рендеринга компонент
+1. `refine_component` используется для создания новых компонент на основе существующих, реализованных [с помощью `define_component`](Хелпер-define_component.md)
+
+Используя `render_component` можно получать HTML структуру компонента, а если компонент был создан [с помощью `define_component`](Хелпер-define_component.md) тогда и изменять его структуру/внешний вид с помощью шаблонов BEMHTML.
+
+Все передаваемые параметры будут доступны в теле компонента как локальные переменные, исключение составляют параметры `cached` и `prefix`.
+
+Используется следующая файловая структура:
+```
+app/
+  ├── assets/
+  |     ├── javascripts/
+  |     |     └── application.js
+  |     └── stylesheets/
+  |           └── application.css
+  ├── bemer_components/
+  |     ├── progress/
+  |     |     ├── index.html.slim
+  |     |     ├── index.js
+  |     |     └── index.css
+  |     └── ...
+  └── ...
+```
+Подключение технологий JavaScript и CSS компонента `progress` при использовании Sprockets:
+
+```js
+// Файл app/assets/javascripts/application.js
+//= require progress
+```
+
+```scss
+// Файл app/assets/stylesheets/application.css
+//= require progress
+```
+В качестве структуры компонента `progress` будет взят [компонент `Progress bar` из библиотеки Twitter Bootstrap](https://getbootstrap.com/docs/3.3/components/#progress):
+
+```html
+<!-- Исходная HTML структура компонента Progress bar из библиотеки Twitter Bootstrap -->
+<div class="progress">
+  <div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
+    60%
+  </div>
+</div>
+```
+Возможный вариант разметки компонента `progress` с использованием `define_component` по методологии БЭМ:
+```slim
+/ Содержимое файла index.html.slim компонента panel
+= define_component bem_cascade: false, tag: :div do |component|
+  = component.block :progress, cls: :progress do |progress|
+    = progress.elem :bar, role: :progressbar, cls: :progress_bar
+```
+## Использование BEMHTML шаблонов
+
+В случае если структура компонента была создана [с помощью `define_component`](Хелпер-define_component.md), тогда при вызове `render_component` можно передать `&block` в теле которого будет доступен билдер (builder) шаблонов технологии BEMHTML:
+
+```slim
+/ Эквивалентный результат, только режим `attrs` здесь будет быстрее чем цепочка `add_attrs`
+= render_component :progress do |template|
+  = template.elem :bar do |bar|
+    = bar.attrs 'aria-valuenow': 60, 'aria-valuemin': 0, 'aria-valuemax': 100, style: 'width: 60%;'
+    = bar.content '60%'
+
+= render_component :progress do |template|
+  = template.elem :bar do |bar|
+    = bar.add_attrs 'aria-valuenow': 60
+    = bar.add_attrs 'aria-valuemin': 0
+    = bar.add_attrs 'aria-valuemax': 100
+    = bar.add_attrs style: 'width: 60%;'
+    = bar.content '60%'
+
+/ =>
+/ <div class="progress">
+/   <div role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;" class="progress-bar">
+/     60%
+/   </div>
+/ </div>
+```
+Для изменения внешнего вида, можно добавить css классы `progress-bar-success`, `progress-bar-striped` и `active`:
+```slim
+= render_component :progress do |template|
+  = template.elem :bar do |bar|
+    = bar.attrs 'aria-valuenow': 60, 'aria-valuemin': 0, 'aria-valuemax': 100, style: 'width: 60%;'
+    = bar.content '60%'
+    = bar.add_cls :progress_bar_striped, :active, :progress_bar_success
+
+/ =>
+/ <div class="progress">
+/   <div aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;" class="progress-bar progress-bar-striped active progress-bar-success">
+/     60%
+/   </div>
+/ </div>
+```
+## Параметр `prefix`
+
+Для чего нужен и как использовать параметр `prefix` можно прочитать [здесь](Конфигурация.md#%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80-default_path_prefix).
+
+## Параметр `cached`
+
+Описание про `cached` можно найти [в `component_pack`](Хелпер-component_pack.md).

data/docs//320/250/320/260/320/261/320/273/320/276/320/275/321/213.md

@@ -0,0 +1,44 @@
+# Шаблоны
+
+**ВАЖНО**. *Только для компонент, [структура (дерево) которых была создана](Создание-и-использование-UI-компонент.md) с помощью [хелпера `define_component`](Хелпер-define_component.md) доступно использование BEMHTML шаблонов.*
+
+**ВАЖНО**. *Шаблоны должны быть максимально простыми и не содержать излишней логики.*
+
+Каждый шаблон, например, `template.elem(:message).replace 'Plain text'` состоит из:
+1. `elem(:message)` - [предикат](Предикаты.md)
+1. `replace` - [режим](Режимы.md)
+1. `'Plain text'` - тело
+
+Если для узла из структуры (дерева) компонента, все условия в предикате верны, тогда для этого узла будет применено тело шаблона в указанном режиме изменения данных.
+
+Шаблоны можно создавать используя хелперы `define_templates`, `render_component` и  `refine_component`.
+
+## Примеры шаблонов
+
+### Шаблоны по умолчанию для компонента из файла `index.bemhtml.slim`
+
+```slim
+= define_templates do |template|
+  = template.block(:panel).add_cls :panel_default
+```
+
+### Шаблоны при использовании `render_component`
+
+```slim
+= render_component :alert do |template|
+  = template.block(:alert).add_cls :alert_info
+  = template.elem(:message).content do |node, builder|
+    span HTML content
+    = node.content
+    = builder.text TextNode content
+```
+
+### Шаблоны при использовании `refine_component`
+
+```slim
+= refine_component :progress do |template|
+  = template.block(:progress).content do |node|
+    = node.content
+    = node.content
+    = node.content
+```

data/lib/bemer.rb

@@ -22,6 +22,7 @@ module Bemer
   autoload :EntityBuilder
   autoload :MixinList
   autoload :ModifierList
+  autoload :PathResolver
   autoload :Pipeline
   autoload :Predicate
   autoload :Renderer
@@ -57,7 +58,7 @@ module Bemer
     alias prepend_asset_paths? prepend_asset_paths
 
     def config
-      Configuration.instance
+      Bemer::Configuration.instance
     end
 
     def setup
@@ -70,6 +71,7 @@ module Bemer
       Bemer::Builders.eager_load!
     end
 
+    # entity_class
     def bem_class(block, element = nil)
       return '' if block.blank? || (!element.nil? && element.blank?)
 

data/lib/bemer/builders.rb

@@ -12,6 +12,14 @@ module Bemer
       autoload :Tree
     end
 
+    class Tree
+      extend ActiveSupport::Autoload
+
+      eager_autoload do
+        autoload :Element
+      end
+    end
+
     module Tag
       extend ActiveSupport::Autoload
 

data/lib/bemer/builders/tree.rb

@@ -1,16 +1,8 @@
 # frozen_string_literal: true
 
-require 'active_support/dependencies/autoload'
-
 module Bemer
   module Builders
     class Tree
-      extend ActiveSupport::Autoload
-
-      eager_autoload do
-        autoload :Element
-      end
-
       def initialize(tree)
         @tree = tree
       end