XJST 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
.jscs.js
.jshintignore
.jshintrc
.npmignore
.travis.yml
CHANGELOG.md
CONTRIBUTORS.md
LICENSE.txt
README.md
api.ru.md
appveyor.yml
package.json

README.md

enb-xjst

NPM version Build Status Build status Coverage Status Dependency Status

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

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

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

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

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

Установка

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

$ npm install --save-dev enb-xjst

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

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

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

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

var BemtreeTech = require('enb-xjst/techs/bemtree'),
    BemhtmlTech = require('enb-xjst/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-xjst/techs/bemjson-to-html'),
    BemhtmlTech = require('enb-xjst/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 или .bemtree.xjst в директориях блоков. Чтобы использовать шаблоны, необходимо собрать их исходные файлы.

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

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

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

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

var BEMTREE = require('bundle.bemtree.xjst.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.xjst.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(BEMTREE, BEMHTML) {
        BEMTREE.apply({ block: 'page', data: { /* ... */ } })
            .then(function (bemjson) {
                var html = BEMHTML.apply(bemjson);
            });
    });

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

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

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

  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: {
    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: {
    var moment = this.require('moment'),  // Библиотека `moment`
    // Время в миллисекундах, полученное с сервера
    return moment(ctx.param.date).format('YYYY-MM-DD HH:mm:ss');
}

Синтаксис

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

Компилятор шаблонов XJST поддерживает только сокращенный синтаксис шаблонов.

Асинхронная шаблонизация

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

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

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

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

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

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

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

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

block button, elem tooltip, content: {
    var i18n = this.require('i18n'),  // Библиотека `BEM.I18N`

    // Локализованное значение для ключа `tooltip`
    return i18n('button', 'tooltip');
}

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

Лицензия

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