README.md

Bemer

ВАЖНО. Для работы с UI компонентами не обязательно использовать методологию БЭМ.

1. Позволяет создавать переиспользуемые UI компоненты для приложений на Ruby on Rails.
2. Предоставляет функционал для разработки приложений на Ruby on Rails с использованием методологии БЭМ.

Дополнительно

1. Статья на Хабре - Переиспользуемые UI компоненты в приложениях на Ruby on Rails.
2. bemer-simple_form - Использование соглашений из БЭМ методологии в формах SimpleForm.
3. bemer-bootstrap - переиспользуемые компоненты Bootstrap v3.
4. Пример приложения с использованием bemer и bemer-bootstrap.

Установка

Добавить в Gemfile:

gem 'bemer'

Выполнить в терминале команду:

$ bundle

Использование

Конфигурация

Конфигурация для Bemer:

# config/initializers/bemer.rb

Bemer.setup do |config|
  config.bem                     = true
  config.modifier_name_separator = '--'
  config.path                    = 'app/frontend/components' # или Webpacker.config.source_path
  # config.default_path_prefix     = lambda { |path, view|
  #   view.controller.class.name.split('::')[0].underscore
  # }
end

Если используется Webpacker:

# config/webpacker.yml

default: &default
  source_path: app/frontend/components
  source_entry_path: ../packs
  public_output_path: frontend/assets
  # ...

development:
  <<: *default
  # ...

test:
  <<: *default
  # ...

production:
  <<: *default
  # ...

Файловая структура

Пример файловой структуры при использовании Sprockets:

app/
  ├── assets/
  |     ├── javascripts/
  |     |     ├── admin_panel/
  |     |     |     ├── application.js
  |     |     |     └── ...
  |     |     ├── landing/
  |     |     |     ├── application.js
  |     |     |     └── ...
  |     |     ├── user_panel/
  |     |     |     ├── application.js
  |     |     |     └── ...
  |     |     └── ...
  |     ├── stylesheets/
  |     |     ├── admin_panel/
  |     |     |     ├── application.scss
  |     |     |     └── ...
  |     |     ├── landing/
  |     |     |     ├── application.scss
  |     |     |     └── ...
  |     |     ├── user_panel/
  |     |     |     ├── application.scss
  |     |     |     └── ...
  |     |     └── ...
  |     └── ...
  ├── frontend/
  |     ├── components/
  |     |     ├── common/
  |     |     |     ├── carousel/
  |     |     |     |     ├── index.slim
  |     |     |     |     ├── index.bemhtml.slim
  |     |     |     |     ├── index.js
  |     |     |     |     ├── index.scss
  |     |     |     |     └── ...
  |     |     |     ├── form/
  |     |     |     |     ├── error_messages_elem/
  |     |     |     |     |     ├── index.slim
  |     |     |     |     |     ├── index.js
  |     |     |     |     |     ├── index.scss
  |     |     |     |     |     └── ...
  |     |     |     |     ├── locales/
  |     |     |     |     |     ├── en.yml
  |     |     |     |     |     └── ...
  |     |     |     |     ├── index.slim
  |     |     |     |     ├── base.rb
  |     |     |     |     ├── index.js
  |     |     |     |     ├── index.scss
  |     |     |     |     └── ...
  |     |     |     └── ...
  |     |     ├── admin_panel/
  |     |     |     └── ...
  |     |     ├── landing/
  |     |     |     └── ...
  |     |     ├── user_panel/
  |     |     |     └── ...
  |     |     └── ...
  |     └── ...
  └── ...

Пример файловой структуры при использовании Webpacker:

app/
  ├── frontend/
  |     ├── components/
  |     |     ├── common/
  |     |     |     ├── carousel/
  |     |     |     |     ├── index.slim
  |     |     |     |     ├── index.bemhtml.slim
  |     |     |     |     ├── index.js
  |     |     |     |     ├── index.scss
  |     |     |     |     └── ...
  |     |     |     ├── form/
  |     |     |     |     ├── error_messages_elem/
  |     |     |     |     |     ├── index.slim
  |     |     |     |     |     ├── index.js
  |     |     |     |     |     ├── index.scss
  |     |     |     |     |     └── ...
  |     |     |     |     ├── locales/
  |     |     |     |     |     ├── en.yml
  |     |     |     |     |     └── ...
  |     |     |     |     ├── index.slim
  |     |     |     |     ├── base.rb
  |     |     |     |     ├── index.js
  |     |     |     |     ├── index.scss
  |     |     |     |     └── ...
  |     |     |     └── ...
  |     |     ├── admin_panel/
  |     |     |     └── ...
  |     |     ├── landing/
  |     |     |     └── ...
  |     |     ├── user_panel/
  |     |     |     └── ...
  |     |     └── ...
  |     ├── packs/
  |     |     ├── admin_panel/
  |     |     |     ├── application.js
  |     |     |     └── ...
  |     |     ├── landing/
  |     |     |     ├── application.js
  |     |     |     └── ...
  |     |     ├── user_panel/
  |     |     |     ├── application.js
  |     |     |     └── ...
  |     |     └── ...
  |     └── ...
  └── ...

Создание HTML структуры компонента

Простой компонент

Структура компонента Сarousel из Bootstrap:

/ app/frontend/components/common/carousel/index.slim

.carousel.slide data-ride="carousel" class=local_assigns[:cls]
  ol.carousel-indicators
    - image_urls.size.times do |i|
      li data-target=".carousel" class=(:active if i.zero?) data-slide-to=i
  .carousel-inner
    - image_urls.each_with_index do |image_url, i|
      .carousel-item class=(:active if i.zero?)
        = image_tag image_url, class: 'd-block w-100'
  a.carousel-control-prev data-slide="prev" data-target='.carousel' role="button"
    span.carousel-control-prev-icon aria-hidden="true"
    span.sr-only Предыдущий
  a.carousel-control-next data-slide="next" data-target='.carousel' role="button"
    span.carousel-control-next-icon aria-hidden="true"
    span.sr-only Следующий

Вызов компонента carousel в любом представлении или в других компонентах:

= render_component :carousel, prefix: :common, image_urls: image_urls, cls: 'carousel-fade'

Компонент к которому можно применять BEMHTML шаблоны

Структура компонента Сarousel из Bootstrap:

/ app/frontend/components/common/carousel/index.slim

= define_component do |component|
  = component.block :carousel, 'data-ride': :carousel, 'data-interval': false, cls: :slide do |carousel|
    = carousel.elem :indicators, tag: :ol, cls: 'carousel-indicators'
      - image_urls.size.times do |i|
        = carousel.elem :indicator, tag: :li, 'data-slide-to': i, mods: (:active if i.zero?), 'data-target': '.carousel'
    = carousel.elem :inner, cls: 'carousel-inner'
      - image_urls.each_with_index do |image_url, i|
        = carousel.elem :item, cls: 'carousel-item', mods: (:active if i.zero?)
          = carousel.elem :image, tag: :img, cls: 'd-block w-100', src: image_url
    = carousel.elem :control_prev, tag: :a, cls: 'carousel-control-prev', 'data-slide': :prev, role: :button, 'data-target': '.carousel'
      span.carousel-control-prev-icon aria-hidden="true"
      span.sr-only Предыдущий
    = carousel.elem :control_next, tag: :a, cls: 'carousel-control-next', 'data-slide': :next, role: :button, 'data-target': '.carousel'
      span.carousel-control-next-icon aria-hidden="true"
      span.sr-only Следующий

Шаблон по умолчанию:

/ app/frontend/components/common/carousel/index.bemhtml.slim

= define_templates do |template|
  = template.elem(mods: :active).add_cls :active

Вызов компонента carousel в любом представлении или в других компонентах с применением BEMHTML шаблонов:

= render_component :carousel, prefix: :common, image_urls: image_urls do |template|
  = template.block(:carousel).add_mix :carousel_fade

Документация

1. Файловая структура
2. Конфигурация
3. Создание и использование UI компонент
4. Хелперы для работы с компонентами
   1. define_component
   2. define_templates
   3. render_component
   4. refine_component
   5. component_pack
   6. component_asset_path
   7. component_partial_path
5. Дополнительные хелперы для БЭМ методологии
   1. bem_mix
   2. bem_mods
   3. block_tag
   4. elem_tag
6. BEMHTML
   1. Шаблоны
   2. Контекст узла
   3. Предикаты
   4. Режимы

Ссылки

1. BEM methodology - https://bem.info/methodology/
2. Minimal stack for coding client-side JavaScript and templating - https://github.com/bem/bem-core
3. Declarative template engine for the browser and server with regular JS syntax - https://github.com/bem/bem-xjst
4. BEM Forum - https://bem.info/forum/

Лицензия

Copyright (c) 2017 - 2020 Александр Григорьев. Более подробную информацию о лицензии можно получить в файле LICENSE.txt.