Skip to content

Latest commit

 

History

History
175 lines (134 loc) · 8.71 KB

SPEC.md

File metadata and controls

175 lines (134 loc) · 8.71 KB
Raw

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

Общие сведения

Считаем, что примеры могут разделяться на 1) «примеры для демонстрации функциональности» и 2) «примеры для тестирования верстки».

Первую группу так и будем называть примерами (examples); вторую — тестами (tests).

Несмотря на то, что документ описывает только первую группу (примеры), те же самые правила относятся и ко второй группе (тесты).

Не следует путать «примеры для тестирования верстки» (tests) и юнит тесты (specs). Подробнее про разницу между примерами и тестами, см. narqo#61

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

PRJ/
  desktop.blocks/
    block/
      block.examples/                [1]
        10-simple.blocks/            [3]
          ..
        10-simple.bemjson.js         [2]
      __elem/
        block__elem.examples/        [4]
          20-special.blocks/
            ..
          20-special.bemjson.js
    ..

block*.examples [1] предстовляет собой уровень переопределения на котором (в общем случае) плоским списком лежат примеры [2], 10-simple.bemjson.js.

Пример — это обычный бандл.

Числовые префиксы в названиях примеров, такие как 10-, не несут никакой специальной семантики. Префиксы, исторически используются для сортировки примеров от простого к сложному. Можно не использовать в случаях, когда сортировка не нужна. С точки зрения БЭМ это просто часть имени блока-примера.

Каждый пример может иметь свой собственный уровень переопределения (УП) блоков [3], с блоками относящимися только к конкретному примеру.

Например

Нам нужно показать (протестировать), как будет выглядеть блок кнопка button внутри таблицы table. Стилизацию таблицы для конкретно этого примера можно положить на собсветнный УП примера:

desktop.blocks/
  button/
    button.examples/
      simple.blocks/
        table/
          table.bemhtml
          table.css
      simple.bemjson.js       → { block : 'table', content : { block : 'button' } }

Собсвенный УП подключается в процессе сборки примера в конец списка остальных уровней участвующих в сборке (см. алгоритм сборки ниже).

Именование всех «сущностей» в уровнях blocks*.examples подпадает под БЭМ-нотацию для блоков. С точки зрения методологии, файлы примера (simple.*) — это реализация блока simple в соответсвующих технологиях (bemjson.js, blocks, title.txt и пр.).

Из правила выше, следует, что (в общем случае) имя примера не должно содержать знака подчеркивания _, поскольку он имеет значение «разделителя» в имени блока, элемента или модификара.

Примеры, как и любая другая технология, может быть у любой БЭМ-сущности: у блока, элемента или модификатора. Т.е. [1] и [4] равнозначны для процесса сборки.

Сборка

Терминология

Сет (набор, set) — группа УП в которых следует искать примеры.

Требования

Сборка примеров должна решать задачи:

  • собрать все примеры;
  • собрать все примеры сета (desktop.examples);
  • собрать все примеры блока в сете (desktop.examples/button);
  • собрать конкретный пример блока в сете (desktop.examples/button/10-simple);
  • собрать конкретную технологию в конкретном примере блока в сете (desktop.examples/button/10-simple/10-simple.js);
  • сборка в режиме dev-сервера;
  • корректная инвалидация всех этапов процесса сборки (изменения в исходном bemjson.js-файле в примере блока, должны инвалидировать весь процесс сборки примера).

Алгоритм сборки

  1. На заданном наборе уровней (сеты) необходимо найти все БЭМ-сущности у которых есть примеры.
PRJ/
  common.blocks/
    button/
      button.examples/
        10-simple.blocks/            [1.4]
        10-simple.bemjson.js         [1.1]
  desktop.blocks/
    button/
      button.examples/
        20-special.bemjson.js        [1.2]
      __control/
        button__control.examples/
          30-complex.bemjson.js      [1.3]

Для набора desktop включающего УП common.blocks + desktop.blocks, будут найденны примеры:

  • 10-simple.bemjson.js [1.1]
  • 20-special.bemjson.js [1.2]
  • 30-complex.bemjson.js [1.3]

При этом примеры [1.1] и [1.2] относятся к блоку button, а пример [1.3] относится к элементу этого блока button__control.

  1. Для примеров найденных на предыдущем эпате, для каждого bemjson.js-файла, создать бандл (страницу) и скопировать туда содержимое bemjson.js.

Директория назначения, куда копируется бандл с примером зависит от конкретной реализации сборщика. В bem-pr>=0.5.0 бандл с примером помещается в следующую ФС:

PRJ/
  common.blocks/
  desktop.blocks/
  ..
  desktop.examples/
    button/
      10-simple/                [2.1]
        10-simple.bemjson.js
      20-special/               [2.2]
        20-special.bemjson.js
    button__control/
      30-complex/               [2.3]
        30-complex.bemjson.js

Здесь, для соответсвующих примеров, созданы бандлы: button/10-simple, button/20-special и button__control/30-complex соответсвенно.

  1. Запустить сборку созданного(-ых) банда(-ов).

В процессе сборки бандла с примером, следует помнить, что у каждого примера, может быть свой собственный УП с блоками [1.4], который необходимо включить в список используемых, во время сборки, уровней.

  1. В случае, если на разных УП сета, есть примеры с одинаковым названием, собираться будет только пример с последнего уровня. Считаем, что пример на следующем УП сета переопределяет пример с предыдущего уровня.
PRJ/
  common.blocks/
    button/
      button.examples/
        10-simple.blocks/            [4.2]
        10-simple.bemjson.js         [4.1]
  desktop.blocks/
    button/
      button.examples/
        10-simple.blocks/            [4.4]
        10-simple.bemjson.js         [4.3]

В данном случае, для сета desktop : [common.block, desktop.blocks] будет собран один пример 10-simple c УП desktop.blocks ([4.3]). При этом только собсвенный УП этого примера [4.4] будет включен в сборку.

Пример [4.1] и его УП [4.2] будут проигнорированны сборщиком.