BH support for ENB
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
techs
test
.editorconfig
.gitignore
.jscsrc
.jshintignore
.jshintrc
.npmignore
.travis.yml
CHANGELOG.md
CONTRIBUTORS.md
LICENSE.txt
MIGRATION-1.md
README.md
api.en.md
api.ru.md
appveyor.yml
package.json

README.md

enb-bh

NPM version Build Status Build status Coverage Status Dependency Status

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

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

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

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

Установка

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

$ npm install --save-dev enb-bh

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

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

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

Подключите технологию 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.js — может применяться по-разному в зависимости от наличия модульной системы и ее типа в следующих случаях:

Исполнение шаблонов в 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.I18N можно использовать в шаблонах из пространства имен bh.lib:

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

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

Лицензия

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