enb-bemxjst

bem-xjst support for ENB

enb-bemxjst

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

Важно: базовые шаблоны для BEMHTML и BEMTREE находятся в библиотеке bem-core. Для технологий, базовые шаблоны которых находятся в библиотеке bem-bl, следует использовать пакет enb-xjst.

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

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

Совместимость: технологии пакета enb-bemxjst используют компилятор BEM-XJST версии 1.2.1.

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

$ npm install --save-dev enb-bemxjst

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

Подключите необходимые технологии: bemhtml, bemtree.

var BemtreeTech = require('enb-bemxjst/techs/bemtree'),
    BemhtmlTech = require('enb-bemxjst/techs/bemhtml'),
    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
         ]);
 
         // Создаем BEMTREE-файл 
         node.addTech(BemtreeTech);
         node.addTarget('?.bemtree.js');
 
         // Создаем BEMHTML-файл 
         node.addTech(BemhtmlTech);
         node.addTarget('?.bemhtml.js');
     });
 };

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

var BemjsonToHtmlTech = require('enb-bemxjst/techs/bemjson-to-html'),
    BemhtmlTech = require('enb-bemxjst/techs/bemhtml'),
    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
        ]);
 
        // Собираем BEMHTML-файл 
        node.addTech(BemhtmlTech);
        node.addTarget('?.bemhtml.js');
 
        // Создаем HTML-файл 
        node.addTech(BemjsonToHtmlTech);
        node.addTarget('?.html');
    });
};

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

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

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

Скомпилированный файл подключается как модуль в формате CommonJS.

var BEMTREE = require('bundle.bemtree.js').BEMTREE, // Путь до скомпилированного BEMTREE-файла 
    BEMHTML = require('bundle.bemhtml.js').BEMHTML; // Путь до скомпилированного BEMHTML-файла 
 
BEMTREE.apply({ block: 'page', data: { /* ... */ } })
    .then(function (bemjson) {
        var html = BEMHTML.apply(bemjson);
    });

Скомпилированный файл подключается на страницу как JavaScript-файл.

<script src="bundle.bemtree.js"></script>
<script src="bundle.bemhtml.js"></script>

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

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

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

    BEMTREE.apply({ block: 'page', data: { /* ... */ } })
        .then(function (bemjson) {
            var html = BEMHTML.apply(bemjson);
        });
  • С модульной системой YModules

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

    modules.require(['BEMTREE', 'BEMHTML'], function(BEMTREEBEMHTML) {
        BEMTREE.apply({ block: 'page', data: { /* ... */ } })
            .then(function (bemjson) {
                var html = BEMHTML.apply(bemjson);
            });
    });

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

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

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

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

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

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

В шаблонах модули будут доступны с помощью метода this.require, например:

block('button').content()(function () {
    var lib = this.require('lib-name');
 
    return lib.hello();
});

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

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

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

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

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

{
    requires: {
        moment: {
            commonJS: 'moment',  // Путь к модулю CommonJS относительно собираемого файла 
        }
    }
}

В шаблонах модуль будет доступен с помощью метода this.require('moment'). Код шаблона пишется один раз, одинаково для исполнения в браузере и в Node.js:

block('post').elem('data').content()(function () {
    var moment = this.require('moment'),  // Библиотека `moment` 
 
    // Время в миллисекундах, полученное с сервера 
    return moment(ctx.param.date).format('YYYY-MM-DD HH:mm:ss');
});

Существует два синтаксиса для шаблонов BEMHTML и BEMTREE:

С момента выпуска библиотеки bem-core сокращенный синтаксис шаблонов считается устаревшим. Рекомендуется использовать JS-синтаксис для всех шаблонов.

О правилах перехода на JS-синтаксис читайте в руководстве по миграции.

Технологии bemhtml и bemtree позволяют собирать шаблоны в сокращенном синтаксисе c помощью опции compat.

Это может быть полезно при миграции c bem-bl на bem-core. Опция compat позволяет поэтапно переходить на JS-синтакис для каждого отдельного шаблона, а не переписывать код всего проекта целиком.

В процессе сборки шаблоны, написанные в сокращенном синтаксисе, приводятся к JS-синтаксису. Синтаксическое преобразование производит модуль bemhtml-compat. Из-за транслирования сборка происходит медленнее даже для файлов в JS-синтаксисе.

Шаблоны в сокращенном синтаксисе следует хранить в файлах с расширениями .bemhtml и .bemtree, а не .bemhtml.js и .bemtree.js.

Важно: оба синтаксиса не могут использоваться одновременно в файле шаблона.

Технология BEMTREE работает асинхронно. Для обработки асинхронных вызовов используются промисы. Это означает, что после подключения скомпилированного BEMTREE-файла и вызова метода BEMTREE.apply, который применит шаблоны к данным, вернется промис.

Для работы с промисами используется библиотека vow версии 0.4.10.

Важно: технология BEMHTML работает синхронно, асинхронная работа невозможна.

Базовая реализация BEM-XJST-технологий не содержит шаблонов для интернационализации (i18n).

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

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

После подключения BEM.I18N библиотека будет доступна в шаблонах с помощью метода this.require:

block('button').elem('tooltip').content()(function () {
    var i18n = this.require('i18n'),  // Библиотека `BEM.I18N` 
 
    // Локализованное значение для ключа `tooltip` 
    return i18n('button', 'tooltip');
});

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