README.md

enb-bh

Пакет предоставляет набор ENB-технологий для сборки BH-шаблонов в проектах, построенных по методологии БЭМ.

Технологии пакета enb-bh:

• bh-bundle
• bh-commonjs
• bemjson-to-html

Принципы работы технологий и их API описаны в документе API технологий.

Совместимость: технологии пакета enb-bh поддерживает версию шаблонизатора BH 4.1.0 и выше.

Установка

Установите пакет enb-bh:

$ npm install --save-dev enb-bh

Требования: зависимость от пакета enb версии 0.12.0 или выше.

Обзор документа

• Быстрый старт
• Работа с технологиями
  • Исполнение шаблонов в Node.js
  • Исполнение шаблонов в браузере
  • Использование шаблонов для сборки HTML
• Особенности работы пакета
  • Подключение сторонних библиотек
  • Мимикрия под BEMHTML
  • Интернационализация
• Дополнительная документация

Быстрый старт

Подключите технологию bh-bundle.

var BHBundleTech = require('enb-bh/techs/bh-bundle'),
    FileProvideTech = require('enb/techs/file-provider'),
    bemTechs = require('enb-bem-techs');

 module.exports = function(config) {
     config.node('bundle', function(node) {
         // Получаем FileList
         node.addTechs([
             [FileProvideTech, { target: '?.bemdecl.js' }],
             [bemTechs.levels, levels: ['blocks']],
             bemTechs.deps,
             bemTechs.files
         ]);

         // Создаем BH-файл
         node.addTech(BHBundleTech);
         node.addTarget('?.bh.js');
     });
 };

Для сборки HTML используйте технологию bemjson-to-html.

var BemjsonToHtmlTech = require('enb-bh/techs/bemjson-to-html'),
    BHCommonJSTech = require('enb-bh/techs/bh-commonjs'),
    FileProvideTech = require('enb/techs/file-provider'),
    bemTechs = require('enb-bem-techs');

module.exports = function(config) {
    config.node('bundle', function(node) {
        // Получаем BEMJSON-файл
        node.addTech([FileProvideTech, { target: '?.bemjson.js' }]);

        // Получаем FileList
        node.addTechs([
            [bemTechs.levels, levels: ['blocks']],
            bemTechs.bemjsonToBemdecl,
            bemTechs.deps,
            bemTechs.files
        ]);

        // Собираем BH-файл
        node.addTech(BHCommonJSTech);
        node.addTarget('?.bh.js');

        // Создаем HTML-файл
        node.addTech(BemjsonToHtmlTech);
        node.addTarget('?.html');
    });
};

Работа с технологиями

В БЭМ-методологии шаблоны к каждому блоку хранятся в отдельных файлах с расширением .bh.js в директориях блоков. Чтобы использовать шаблоны, необходимо собрать их исходные файлы.

Отдельные файлы с шаблонами (.bh.js) собираются в один общий файл (?.bh.js) с помощью одной из следующих технологий:

• bh-bundle
• bh-commonjs

Результат — скомпилированный файл ?.bh.js — может применяться по-разному в зависимости от наличия модульной системы и ее типа в следующих случаях:

• в Node.js
• в браузере
• для сборки HTML

Исполнение шаблонов в Node.js

Файл ?.bh.js подключается как модуль в формате CommonJS.

var BH = require('bundle.bh.js'); // Путь до скомпилированного файла

BH.apply({ block: 'button' });

Исполнение шаблонов в браузере

Файл ?.bh.js подключается на страницу как JavaScript-файл.

<script src="bundle.bh.js"></script>

В браузере исполнение шаблонов зависит от наличия модульной системы:

• Без модульной системы

  Шаблоны доступны из глобальной переменной BH.

  BH.apply({ block: 'button' });

• С модульной системой YModules

  Шаблоны доступны из модульной системы (YModules):

  modules.require(['BH'], function(BH) {
      BH.apply({ block: 'button' })
  });

Использование шаблонов для сборки HTML

HTML – результат применения скомпилированного шаблона к указанному BEMJSON-файлу.

Сборка HTML (файл ?.html) с помощью технологий enb-bh проходит в два этапа:

1. Файл ?.bh.js собирается с помощью одной из технологий bh-bundle или bh-commonjs.
2. BEMJSON и скомпилированный ?.bh.js-файл обрабатываются с помощью технологии bemjson-to-html, которая возвращает HTML-файл (?.html).

Особенности работы пакета

Подключение сторонних библиотек

Технологии bh-bundle и bh-commonjs поддерживают возможность подключения сторонних библиотек.

Способы подключения для каждой технологии отличаются.

bh-bundle

Технология bh-bundle позволяет подключать библиотеки как глобально, так и для разных модульных систем с помощью опции requires.

Для подключения укажите название библиотеки и в зависимости от используемой модульной системы:

• имя глобальной переменной;
• имя модуля из YModules;
• путь к модулю для CommonJS.

{
    requires: {
        'lib-name': {
            globals: 'dependName',      // Название переменной в глобальной видимости
            ym: 'depend-name',          // Имя модуля из YModules
            commonJS: 'path/to/module'  // Путь к модулю CommonJS относительно собираемого файла
        }
    }
}

В шаблонах модули будут доступны из пространства имен bh.lib, например:

var lib = bh.lib['lib-name'];

bh.match('block', function (ctx) {
    var text = lib.hello();

    ctx.content(text);
});

Не обязательно указывать все модульные системы для подключения библиотеки.

Например, указать зависимости глобально для всех модульных систем. В этом случае модуль всегда будет передаваться из глобальной переменной, даже если в среде исполнения будет использоваться модульная система.

{
    requires: {
        'lib-name': {
            globals: 'dependName' // Название переменной в глобальной видимости
        }
    }
}

Пример подключения библиотеки moment

Указывается название библиотеки и путь к модулю:

{
    requires: {
        moment: {
            commonJS: 'moment'
        }
    }
}

В шаблонах модуль будет доступен из bh.lib.moment. Шаблон пишется одинаково для исполнения в браузере и в Node.js:

var moment = bh.lib.moment;   // Библиотека `moment`

bh.match('post__date', function (ctx) {
    // Время в миллисекундах, полученное с сервера
    var date = moment(ctx.param.date).format('YYYY-MM-DD HH:mm:ss');

    ctx.content(date);
});

bh-commonjs

Технология bh-commonjs позволяет подключать библиотеки в шаблоне с помощью require:

var lib = require('path/to/module');  // Путь до библиотеки

Мимикрия под BEMHTML

БЭМ-платформа поддерживает шаблонизаторы BH и BEMHTML, которые преобразуют BEMJSON в HTML.

Для возможности писать JavaScript-код, совместимый с обоими шаблонизаторами, используется опция mimic. Она позволяет использовать имена переменных BEMHTML, но по факту выполнять шаблоны BH.

Интернационализация

Базовая реализация BH-технологий не поддерживает интернационализацию (i18n).

Чтобы использовать i18n в шаблонах, следует подключить модуль BEM.I18N по аналогии с другими сторонними библиотеками.

BEM.I18N — библиотека для интернационализации блоков. Ядро находится в keyset-файлах в одной из базовых библиотек блоков:

• bem-core
• bem-bl

После подключения BEM.I18N можно использовать в шаблонах из пространства имен bh.lib:

bh.match('block', function (ctx) {
    ctx.content({
        elem: 'tooltip',
        content: bh.lib.i18n('block', 'tooltip');
    });
});

Дополнительная документация

• Шаблонизатор BH
• API технологий

Лицензия

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