enb-bem-examples

Инструмент для генерации сетов из примеров БЭМ-блоков с помощью ENB.

Установка

$ npm install --save-dev enb-bem-examples

Для работы модуля требуется зависимость от пакетов enb-magic-factory версии 0.3.x или выше, а так же enb версии 0.15.0 или выше.

Технология examples в файловой системе

Примеры — это обычные бандлы, которые располагаются в папке технологии examples той БЭМ-сущности, которой они принадлежат. В файловой системе они складываются плоским списком (simple-уровень):

$ tree -a <level>.blocks/<block-name>/<block-name>.examples
 
<block-name>.examples/
 ├── 10-simple.bemjson.js       # `10-simple` бандл в технологии `bemjson.js` 
 ├── 10-simple.title.txt        # `10-simple` бандл в технологии `title.txt` 
 ├── 20-complex.bemjson.js      # `20-simple` бандл в технологии `bemjson.js` 
 └── 20-complex.title.txt       # `20-simple` бандл в технологии `title.txt` 

У каждого примера может быть свой уровень блоков:

$ tree -a <level>.blocks/<block-name>/<block-name>.examples
 
<block-name>.examples/
 ├── blocks/                    # уровень для всех примеров блока `<block-name>` 
 ├── 10-simple.blocks/          # уровень только для примера `10-simple` 
 └── 10-simple.bemjson.js

В результате будет построен сет из примеров, каждый из которых представляет собой обычный бандл (nested-уровень):

$ tree -a <set-name>.examples
 
<set-name>.examples
 └── <block-name>/                  # папка группирует примеры для БЭМ-сущности 
      ├── 10-simple/                # `10-simple` бандл 
          ├── <block-name>.blocks/  # уровень для всех примеров блока `<block-name>` 
          ├── 10-simple.blocks/     # уровень блоков только для примера `10-simple` 
          └── 10-simple.bemjson.js  # `10-simple` бандл в технологии `bemjson.js` 
      └── 20-complex/               # `20-simple` бандл 
          ├── <block-name>.blocks/  # уровень для всех примеров блока `<block-name>` 
          ├── 20-complex.blocks/    # уровень блоков только для примера `20-simple` 
          └── 20-complex.bemjson.js # `20-simple` бандл в технологии `bemjson.js` 

Примеры из документации (инлайновые примеры)

При написании документации в md-файлах используют вставки bemjson-кода.

Например, вставка bemjson-кода для блока button:

{
    block: 'button',
    mods: { theme: 'normal', size: 'm', view: 'action' },
    type: 'submit',
    text: 'Action'
}

Такие вставки можно собирать в файловую систему в сеты так же, как и обычные примеры технологии examples.

При сборке сета название бандла для инлайнового примера будет уникальным. Оно формируется из хэш-суммы bemjson-кода примера.

Например, путь до банда с примерами блока button, представленным выше:

desktop.examples/button/F_1FoglPvs4YpLRQGeUEiM6w4CY

Как использовать?

В make-файле (.enb/make.js) нужно подключить модуль enb-bem-examples. С помощью этого модуля следует создать конфигуратор, указав название таска в рамках которого будет происходить сборка уровней сетов из примеров.

Конфигуратор имеет единственный метод configure. Его можно вызывать несколько раз, чтобы задекларировать сборку нескольких сетов.

module.exports = function (config) {
    config.includeConfig('enb-bem-examples'); // Подключаем модуль `enb-bem-examples`.
 
    var examples = config.module('enb-bem-examples') // Создаём конфигуратор сетов
        .createConfigurator('examples');             //  в рамках `examples`-таска.
 
    examples.configure({
        destPath: 'desktop.examples',
        levels: ['blocks']
    });
};

Опции

• String destPath — путь относительно корня до нового сета с бандлами примеров, которые нужно собрать. Обязательная опция.
• String[] | Object[] levels — уровни в которых следует искать примеры. Обязательная опция.
• String[] techSuffixes — суффиксы папок технологий с примерами. По умолчанию — ['examples'].
• String[] fileSuffixes — суффиксы файлов внутри папок технологий с примерами. По умолчанию — ['bemjson.js'].
• Boolean inlineBemjson — определяет возможность создания инлайновых примеров из  md-файлов. По умолчанию — false.
• Function processInlineBemjson — функция обработки инлайнового bemjson.

Запуск из консоли

В make-файле декларируется таск, в котором будет выполняться сборка сетов из примеров.

В ENB запуск таска осуществляется с помощью команды make, которой передаётся имя таска:

$ ./node_modules/.bin/enb make <task-name>

Сборка всех примеров

Если сборка сетов из примеров была задекларирована в examples-таске:

$ ./node_modules/.bin/enb make examples

Сборка указанного примера (точечная сборка)

Передаём список путей примеров, по которым должны собраться бандлы внутри сета:

$ ./node_modules/.bin/enb make <task-name> path/to/example-1 path/to/example-2

Чтобы собрать пример 10-simple, принадлежащий БЭМ-сущности block__elem, для сета desktop.examples:

$ ./node_modules/.bin/enb make examples desktop.examples/block__elem/10-simple

Сборка всех примеров указанной БЭМ-сущности

Чтобы собрать все примеры БЭМ-сущности block__elem для сета desktop.examples:

$ ./node_modules/.bin/enb make examples desktop.examples/block__elem

Лицензия

© 2014 YANDEX LLC. Код лицензирован Mozilla Public License 2.0.