bemer 0.1.0 → 0.2.0

data/docs//320/241/320/276/320/267/320/264/320/260/320/275/320/270/320/265-/320/270-/320/270/321/201/320/277/320/276/320/273/321/214/320/267/320/276/320/262/320/260/320/275/320/270/320/265-UI-/320/272/320/276/320/274/320/277/320/276/320/275/320/265/320/275/321/202.md

@@ -0,0 +1,173 @@
+# Создание и использование UI компонент
+
+**ВАЖНО**. *Только для компонент, структура (дерево) которых была создана с помощью [хелпера `define_component`](Хелпер-define_component.md) доступно использование [BEMHTML шаблонов](Шаблоны.md).*
+
+Для всех примеров используется следующая файловая структура:
+
+```
+app/
+  ├── assets/
+  |     ├── javascripts/
+  |     |     └── application.js
+  |     └── stylesheets/
+  |           └── application.css
+  ├── bemer_components/
+  |     ├── panel/
+  |     |     ├── index.html.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>
+```
+## Компонент без использования шаблонизатора
+
+```html
+<!-- Содержимое файла index.html компонента 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>
+```
+получение HTML кода компонента в представлениях и/или хелперах:
+```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>
+```
+
+## Компонент с использованием шаблонизатора
+
+```slim
+/ Содержимое файла index.html.slim компонента panel
+.panel.panel-default
+  .panel-heading
+    h3.panel-title Panel title
+  .panel-body Panel content
+  .panel-footer Panel footer
+```
+получение HTML кода компонента в представлениях и/или хелперах:
+```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>
+```
+
+## Компонент с помощью `block_tag`
+
+```slim
+/ Содержимое файла index.html.slim компонента panel
+= block_tag :panel, bem_cascade: false, tag: :div, cls: 'panel panel-default' do |panel|
+  = panel.elem :heading, tag: :div, cls: 'panel-heading'
+    = panel.elem :title, tag: :h3, cls: 'panel-title', content: 'Panel title'
+  = panel.elem :body, tag: :div, cls: 'panel-body', content: 'Panel content'
+  = panel.elem :footer, tag: :div, cls: 'panel-footer', content: 'Panel footer'
+```
+получение HTML кода компонента в представлениях и/или хелперах:
+```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>
+```
+
+## Компонент с помощью `define_component`
+
+**ВАЖНО**. *Доступно использование [BEMHTML шаблонов](Шаблоны.md).*
+
+```slim
+/ Содержимое файла index.html.slim компонента panel
+= define_component bem_cascade: false, tag: :div do |component|
+  = component.block :panel, cls: 'panel panel-default' do |panel|
+    = panel.elem :heading, cls: 'panel-heading'
+      = panel.elem :title, tag: :h3, cls: 'panel-title', content: 'Panel title'
+    = panel.elem :body, cls: 'panel-body', content: 'Panel content'
+    = panel.elem :footer, cls: 'panel-footer', content: 'Panel footer'
+```
+получение HTML кода компонента в представлениях и/или хелперах:
+```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>
+```
+
+## Передача локальных переменных в индексный файл технологии HTML
+
+```slim
+/ Содержимое файла index.html.slim компонента panel
+.panel.panel-default
+  .panel-heading
+    h3.panel-title = local_assigns.fetch(:title, 'Default title')
+  .panel-body = local_assigns.fetch(:content, 'Default content')
+  .panel-footer = local_assigns.fetch(:footer, 'Default footer')
+```
+получение HTML кода компонента в представлениях и/или хелперах:
+```slim
+/ Шаблонизатор Slim
+= render_component :panel, title: 'Title', content: 'Content', footer: 'Footer'
+
+/ =>
+/ <div class="panel panel-default">
+/   <div class="panel-heading">
+/     <h3 class="panel-title">Title</h3>
+/   </div>
+/   <div class="panel-body">Content</div>
+/   <div class="panel-footer">Footer</div>
+/ </div>
+```

data/docs//320/244/320/260/320/270/314/206/320/273/320/276/320/262/320/260/321/217-/321/201/321/202/321/200/321/203/320/272/321/202/321/203/321/200/320/260.md

@@ -0,0 +1,167 @@
+# Файловая структура
+
+В общем случае структура каталогов и файлов может выглядеть следующим образом:
+
+```
+app/
+  ├── bemer_components/
+  |     ├── modal/
+  |     |     ├── index.html
+  |     |     ├── index.js
+  |     |     ├── index.scss
+  |     |     └── ...
+  |     ├── top_navbar/
+  |     |     ├── index.html.slim
+  |     |     ├── index.bemhtml.slim
+  |     |     ├── index.js
+  |     |     ├── index.scss
+  |     |     └── ...
+  |     └── ...
+  └── ...
+```
+
+Название каталога это название компонента, которое будет использоваться в представлениях (`views`) и/или хелперах (`helpers`) приложения. Каталог может содержать любые файлы (технологии) которые необходимы для компонента, например такие, как `js`, `css`, `md` и т.д.
+
+Соглашения о файлах (технологиях):
+
+1. Каталог **обязательно** должен содержать индексный файл для технологии HTML (это может быть: `index.html`, `index.html.slim`, `index.html.erb` и т.д.), который [описывает структуру компонента](Создание-и-использование-UI-компонент.md), используя для этого любой шаблонизатор (`ERB`, `Slim`, `HAML` и др.) или только HTML код.
+
+1. Если индексный файл технологии HTML для создания структуры (дерева) компонента [использует хелпер `define_component`](Хелпер-define_component.md), тогда каталог может содержать индексный файл для [шаблонов по умолчанию](Хелпер-define_templates.md) (технология `bemhtml`), он должен называться `index.bemhtml` с обязательным указанием шаблонизатора например: `index.bemhtml.erb`, `index.bemhtml.slim` и т.д.
+
+1. Все остальные технологии (`js`, `css`, `md` и т.д.) считаются дополнительными и их можно добавлять по мере необходимости, имена файлов могут быть любыми но для единообразия и удобства лучше использовать `index` в качестве имени:
+
+    В случае если используется [Sprockets](https://github.com/rails/sprockets-rails), тогда подключение `JS` и `CSS` файлов компонента может быть таким:
+
+    ```coffeescript
+    # Файл application.coffee
+    #= require modal
+    ```
+
+    ```js
+    // Файл application.js
+    //= require modal
+    ```
+
+    ```scss
+    // Файл application.css или application.scss
+    //= require modal
+    ```
+
+    Возможно всё-таки появится поддержка индексных файлов и у [SASS](https://github.com/sass/sass/issues/690).
+
+    При использовании [Webpacker](https://github.com/rails/webpacker) для JavaScript также можно не указывать `index.js`:
+    ```js
+    import 'modal'
+    ```
+
+
+Структуру каталогов можно организовывать по-разному в зависимости от вида приложений и решаемых задач.
+
+## Пример №1
+
+Компоненты разделены для использования в разных частях приложения, пользовательской (`user`), административной (`admin`) и общие (`common`) можно использовать/переопределять везде:
+
+```
+app/
+  ├── bemer_components/
+  |     ├── common/
+  |     |     ├── modal/
+  |     |     |     ├── index.html.slim
+  |     |     |     ├── index.bemhtml.slim
+  |     |     |     ├── index.js
+  |     |     |     ├── index.scss
+  |     |     |     └── ...
+  |     |     ├── top_navbar/
+  |     |     |     ├── index.html.slim
+  |     |     |     ├── index.bemhtml.slim
+  |     |     |     ├── index.js
+  |     |     |     ├── index.scss
+  |     |     |     └── ...
+  |     |     └── ...
+  |     ├── admin/
+  |     |     ├── top_navbar/
+  |     |     |     ├── index.html.slim
+  |     |     |     ├── index.bemhtml.slim
+  |     |     |     ├── index.js
+  |     |     |     ├── index.scss
+  |     |     |     └── ...
+  |     |     └── ...
+  |     ├── user/
+  |     |     ├── top_navbar/
+  |     |     |     ├── index.html.slim
+  |     |     |     ├── index.bemhtml.slim
+  |     |     |     ├── index.js
+  |     |     |     ├── index.scss
+  |     |     |     └── ...
+  |     |     └── ...
+  |     └── ...
+  └── ...
+```
+
+## Пример №2
+
+Приложение, в котором компоненты разделены для поддержки различных устройств:
+
+```
+app/
+  ├── bemer_components/
+  |     ├── common/
+  |     |     ├── modal/
+  |     |     |     ├── index.html.slim
+  |     |     |     ├── index.bemhtml.slim
+  |     |     |     ├── index.js
+  |     |     |     ├── index.scss
+  |     |     |     └── ...
+  |     |     ├── top_navbar/
+  |     |     |     ├── index.html.slim
+  |     |     |     ├── index.bemhtml.slim
+  |     |     |     ├── index.js
+  |     |     |     ├── index.scss
+  |     |     |     └── ...
+  |     |     └── ...
+  |     ├── desktop/
+  |     |     ├── top_navbar/
+  |     |     |     ├── index.html.slim
+  |     |     |     ├── index.bemhtml.slim
+  |     |     |     ├── index.js
+  |     |     |     ├── index.scss
+  |     |     |     └── ...
+  |     |     └── ...
+  |     ├── touch_pad/
+  |     |     ├── top_navbar/
+  |     |     |     ├── index.html.slim
+  |     |     |     ├── index.bemhtml.slim
+  |     |     |     ├── index.js
+  |     |     |     ├── index.scss
+  |     |     |     └── ...
+  |     |     └── ...
+  |     └── ...
+  └── ...
+```
+
+## Пример №3
+
+Альтернативный способ структуры каталогов и файлов для поддержки различных устройств в приложениях начиная с `Rails 4.1` это использовать [Variants](http://guides.rubyonrails.org/4_1_release_notes.html#action-pack-variants):
+
+```
+app/
+  ├── bemer_components/
+  |     ├── modal/
+  |     |     ├── index.html.slim
+  |     |     ├── index.html+phone.slim
+  |     |     ├── index.html+tablet.slim
+  |     |     ├── index.bemhtml.slim
+  |     |     ├── index.js
+  |     |     ├── index.scss
+  |     |     └── ...
+  |     ├── top_navbar/
+  |     |     ├── index.html.slim
+  |     |     ├── index.html+phone.slim
+  |     |     ├── index.html+tablet.slim
+  |     |     ├── index.bemhtml.slim
+  |     |     ├── index.js
+  |     |     ├── index.scss
+  |     |     └── ...
+  |     └── ...
+  └── ...
+```

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

@@ -0,0 +1,62 @@
+# Хелпер bem_mix
+
+**ВАЖНО**. *Для сущностей у которых не указано название, не будут созданы css классы из методологии БЭМ*.
+
+Позволяет создавать миксы по методологии БЭМ.
+
+Все передаваемые аргументы типа `Symbol` создают миксы блоков, аргументы типа `Hash` создают миксы элементов (исключение хеш у которого значение `nil`, см. пример ниже).
+
+У ВСЕХ аргументов переданных как тип:
+* `Symbol` ВСЕ символы нижнего подчеркивания будут преобразованы в тире
+* `String` возвращаются без модификации (включая ключи и/или значения хешей)
+
+```ruby
+bem_mix :block_name, block_name: :elem_name   # => 'block-name block-name__elem-name'
+```
+
+эквивалентная запись:
+
+```ruby
+bem_mix [:block_name, block_name: :elem_name] # => 'block-name block-name__elem-name'
+```
+С помощью хеша можно создать микс блока если значение передать как `nil`
+```ruby
+bem_mix block_name: nil # => 'block-name'
+```
+
+если значение хеша указано как `''` или `false` микс создан не будет:
+```ruby
+bem_mix block_name: false # => ''
+bem_mix block_name: ''    # => ''
+```
+Если у нескольких элементов название блока одинаковое, чтобы не переопределить предыдущее значение следующим, можно каждый элемент передавать как отдельный хеш:
+
+```ruby
+bem_mix({ block: :elem1 }, { block: :elem2 }) # => 'block__elem1 block__elem2'
+```
+или эквивалентная и более компактная запись используя массив:
+
+```ruby
+bem_mix block: [:elem1, :elem2] # => 'block__elem1 block__elem2'
+```
+**ВАЖНО.** *Будьте ВНИМАТЕЛЬНЫ при использование аргументов с типом `String`, а также ключей и/или значений хеша с типом `String` это может привести к неправильному результату согласно методологии БЭМ*:
+
+```ruby
+bem_mix 'block_name' => 'elem_name' # => 'block_name__elem_name'
+```
+Аргументы переданные как тип `String` ВСЕГДА остаются неизменными:
+
+```ruby
+bem_mix 'block_name', 'block_name__elem' # => 'block_name block_name__elem'
+```
+
+эквивалентная запись:
+
+```ruby
+bem_mix 'block_name block_name__elem' # => 'block_name block_name__elem'
+```
+
+Пустые аргументы возвращают пустую строку
+```ruby
+bem_mix nil, '', {} # => ''
+```

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

@@ -0,0 +1,63 @@
+# Хелпер bem_mods
+
+**ВАЖНО**. *Для сущностей у которых не указано название, не будут созданы css классы из методологии БЭМ*.
+
+Позволяет создавать модификаторы по методологии БЭМ.
+
+Действуют такие же правила трансформации для символов нижнего подчеркивания в символы тире как и у [хелпера `bem_mix`](Хелпер-bem_mix.md).
+
+`bem_mods` принимает название блока, название элемента (которые не могут быть `''`, `false` или `nil`) и параметры модификаторов которые могут быть массивом, хешем, символом или строкой.
+
+Модификаторы для блока:
+
+```ruby
+bem_mods :block_name, theme: :green_islands # => 'block-name_theme_green-islands'
+```
+
+Модификаторы для элемента:
+
+```ruby
+bem_mods :block_name, :elem_name, has_tail: true # => 'block-name__elem-name_has-tail'
+```
+
+Единственный модификатор с значением `true`:
+
+```ruby
+# Эквивалентные записи
+bem_mods :block_name, :has_tail            # => 'block-name_has-tail'
+bem_mods :block_name, has_tail: true       # => 'block-name_has-tail'
+bem_mods :block_name, [:has_tail]          # => 'block-name_has-tail'
+bem_mods :block_name, [has_tail: true]     # => 'block-name_has-tail'
+bem_mods :block_name, [{ has_tail: true }] # => 'block-name_has-tail'
+```
+
+Список модификаторов:
+
+```ruby
+# Эквивалентные записи
+bem_mods :block, enabled: true, size: :small           # => 'block_enabled block_size_small'
+bem_mods :block, [enabled: true, size: :small]         # => 'block_enabled block_size_small'
+bem_mods :block, [{ enabled: true, size: :small }]     # => 'block_enabled block_size_small'
+bem_mods :block, [{ enabled: true }, { size: :small }] # => 'block_enabled block_size_small'
+bem_mods :block, [:enabled, size: :small]              # => 'block_enabled block_size_small'
+```
+**ВАЖНО.** *Будьте ВНИМАТЕЛЬНЫ при использование аргументов с типом `String`, а также ключей и/или значений хеша с типом `String` это может привести к неправильному результату согласно методологии БЭМ*:
+
+```ruby
+bem_mods :block_name, 'has_tail'                # => 'block-name_has_tail'
+bem_mods :block_name, 'has_tail' => true        # => 'block-name_has_tail'
+bem_mods :block_name, 'mod_name' => 'mod_value' # => 'block-name_mod_name_mod_value'
+```
+те же самые модификаторы при использовании типа `Symbol`:
+```ruby
+bem_mods :block_name, :has_tail            # => 'block-name_has-tail'
+bem_mods :block_name, has_tail: true       # => 'block-name_has-tail'
+bem_mods :block_name, mod_name: :mod_value # => 'block-name_mod-name_mod-value'
+```
+Модификаторы у которых значение `false`, `nil` или `''`:
+```ruby
+# Эквивалентные записи
+bem_mods :block_name, enabled: false, size: :small # => 'block-name_size_small'
+bem_mods :block_name, enabled: '', size: :small    # => 'block-name_size_small'
+bem_mods :block_name, enabled: nil, size: :small   # => 'block-name_size_small'
+```