Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/enb/enb-bemxjst

bem-xjst support for ENB
https://github.com/enb/enb-bemxjst

bem-xjst bemhtml bemtree enb

Last synced: about 1 year ago
JSON representation

bem-xjst support for ENB

Awesome Lists containing this project

README 

          
enb-bemxjst

===========



[![NPM version](https://img.shields.io/npm/v/enb-bemxjst.svg?style=flat)](https://www.npmjs.org/package/enb-bemxjst) [![Build Status](https://img.shields.io/travis/enb/enb-bemxjst/master.svg?style=flat&label=tests)](https://travis-ci.org/enb/enb-bemxjst) [![Build status](https://img.shields.io/appveyor/ci/blond/enb-bemxjst.svg?style=flat&label=windows)](https://ci.appveyor.com/project/blond/enb-bemxjst) [![Coverage Status](https://img.shields.io/coveralls/enb/enb-bemxjst.svg?style=flat)](https://coveralls.io/r/enb/enb-bemxjst?branch=master) [![Dependency Status](https://img.shields.io/david/enb/enb-bemxjst.svg?style=flat)](https://david-dm.org/enb/enb-bemxjst)



Пакет предоставляет набор [ENB](https://ru.bem.info/tools/bem/enb/)-технологий для сборки [BEMTREE](https://ru.bem.info/technology/bemtree/current/bemtree/)- и [BEMHTML](https://ru.bem.info/technology/bemhtml/current/reference/)-шаблонов в проектах, построенных по [методологии БЭМ](https://ru.bem.info/method/).



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



* [bemhtml](api.ru.md#bemhtml)

* [bemtree](api.ru.md#bemtree)

* [bemjson-to-html](api.ru.md#bemjson-to-html)



Принципы работы технологий и их API описаны в документе [API технологий](api.ru.md).



**Совместимость:** технологии пакета `enb-bemxjst` используют [компилятор BEM-XJST](https://ru.bem.info/tools/templating-engines/bemxjst/). Мажорная версия enb-bemxjst всегда совпадает с мажорной версией bem-xjst.



Установка

---------



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



```sh

$ npm install --save-dev enb-bemxjst

```



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



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

---------------



* [Быстрый старт](#Быстрый-старт)

* [Работа с технологиями](#Работа-с-технологиями)

    * [Исполнение шаблонов в Node.js](#Исполнение-шаблонов-в-nodejs)

    * [Исполнение шаблонов в браузере](#Исполнение-шаблонов-в-браузере)

    * [Использование шаблонов для сборки HTML](#Использование-шаблонов-для-сборки-html)

* [Особенности работы пакета](#Особенности-работы-пакета)

    * [Подключение сторонних библиотек](#Подключение-сторонних-библиотек)

    * [Синтаксис](#Синтаксис)

    * [Интернационализация](#Интернационализация)

* [Дополнительная документация](#Дополнительная-документация)



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

-------------



Подключите необходимые технологии: [bemtree](api.ru.md#bemtree), [bemhtml](api.ru.md#bemhtml).



```js

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](api.ru.md#bemjson-to-html).



```js

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');

    });

};

```



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

---------------------



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



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



* [bemtree](api.ru.md#bemtree)

* [bemhtml](api.ru.md#bemhtml)



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



* [в Node.js](#Исполнение-шаблонов-в-nodejs)

* [в браузере](#Исполнение-шаблонов-в-браузере)

* [для сборки HTML](#Использование-шаблонов-для-сборки-html)



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



Скомпилированный файл подключается как модуль в формате [CommonJS](http://www.commonjs.org/).



```js

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

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



var bemjson = BEMTREE.apply({ block: 'page', data: { /* ... */ } }),

    html = BEMHTML.apply(bemjson); // ...

```



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



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



```html



```



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



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



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



  ```js

  var bemjson = BEMTREE.apply({ block: 'page', data: { /* ... */ } }),

      html = BEMHTML.apply(bemjson); // ...

  ```

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



  Шаблоны доступны из модульной системы ([YModules](https://ru.bem.info/tools/bem/modules/)):



  ```js

  modules.require(['BEMTREE', 'BEMHTML'], function(BEMTREE, BEMHTML) {

      var bemjson = BEMTREE.apply({ block: 'page', data: { /* ... */ } }),

          html = BEMHTML.apply(bemjson); // ...

  });

  ```



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



HTML – результат применения скомпилированного шаблона к указанному [BEMJSON](https://ru.bem.info/technology/bemjson/current/bemjson/)-файлу.



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



1. Файл `?.bemhtml.js` собирается с помощью технологии [bemhtml](api.ru.md#bemhtml).

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



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

-------------------------



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



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



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



* имя глобальной переменной;

* имя модуля из YModules;

* путь к модулю для CommonJS.



```js

{

    requires: {

        'lib-name': {

            globals: 'libName',           // Название переменной в глобальной видимости

            ym: 'lib-name',               // Имя модуля из YModules

            commonJS: 'path/to/lib-name'  // Путь к модулю CommonJS относительно собираемого файла

        }

    }

}

```



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



```js

block('button').content()(function () {

    var lib = this.require('lib-name');



    return lib.hello();

});

```



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



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



```js

{

    requires: {

        'lib-name': {

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

        }

    }

}

```



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



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



```js

{

    requires: {

        moment: {

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

        }

    }

}

```



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



```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-шаблонов:



* [JS-синтаксис](https://ru.bem.info/technology/bemhtml/current/bemhtml-js-syntax/)

* [сокращенный синтаксис](https://ru.bem.info/technology/bemhtml/current/reference/)



С момента выпуска библиотеки [bem-core](https://ru.bem.info/libs/bem-core/) сокращенный синтаксис шаблонов считается устаревшим и больше не поддерживается.



О правилах перехода на JS-синтаксис читайте в [руководстве по миграции](https://ru.bem.info/technology/bemhtml/current/bemhtml-js-syntax/).



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



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



Чтобы использовать i18n в шаблонах, следует подключить модуль `BEM.I18N` по аналогии с другими [сторонними библиотеками](#Подключение-сторонних-библиотек).



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

* [bem-core](https://github.com/bem/bem-core/blob/v2/common.blocks/i-bem/__i18n/i-bem__i18n.i18n/core.js)

* [bem-bl](https://github.com/bem/bem-bl/blob/support/2.x/blocks-common/i-bem/__i18n/i-bem__i18n.i18n/core.js)



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



```js

block('button').elem('tooltip').content()(function () {

    var i18n = this.require('i18n'),  // Библиотека `BEM.I18N`



    // Локализованное значение для ключа `tooltip`

    return i18n('button', 'tooltip');

});

```



### Использование карт кода



Для того, чтобы включить на вашем проекте вывод ошибок в BEMHTML- и BEMTREE-

шаблонах с использованием карт кода (ошибка будет указывать не на собранный

файл, а на исходный файл с шаблоном) вам необходимо использовать enb-bemxjst

версии 8.9.0 и выше.



В конфигурационном файле `.enb/make` на вашем проекте у технологий

bemhtml/bemtree должна быть включена опция `sourcemaps: true`. Настоятельно

рекомендуем включать эту опцию только в окружении разработки, но не в

продакшене.



```

'use strict';



const techs = {

    bemhtml: require('enb-bemxjst/techs/bemhtml'),

    ...

};



module.exports = function(config) {

    config.nodes('pages/all', function(nodeConfig) {

        nodeConfig.addTechs([

            // bemhtml

            [techs.bemhtml, {

                target: '?.bemhtml.js',

                sourcemap: env === 'development',

                engineOptions: {

                    production: env === 'production',

                    omitOptionalEndTags: true,

                    unquotedAttrs: true,

                    elemJsInstances: true

                }

            }]

        ]);



        nodeConfig.addTargets(['?.bemhtml.js']);

    });

});

```



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

---------------------------



* [API технологий](api.ru.md)

* [Быстрый старт по BEMHTML](https://ru.bem.info/technology/bemhtml/current/intro/)

* [Описание шаблонизатора и его преимуществ](https://ru.bem.info/technology/bemhtml/current/rationale/)

* [Справочное руководство по шаблонизатору BEMHTML](https://ru.bem.info/technology/bemhtml/current/reference/)

* [Справочное руководство по шаблонизатору BEMTREE](https://ru.bem.info/technology/bemtree/current)

* [Справочное руководство по BEMJSON](https://ru.bem.info/technology/bemjson/current/bemjson/)

* [JS-синтаксис](https://ru.bem.info/technology/bemhtml/current/bemhtml-js-syntax/)



Лицензия

--------



© 2013 YANDEX LLC. Код лицензирован [Mozilla Public License 2.0](LICENSE.txt).