docs(tech): add exports option description

enb · May 26, 2016 · 8f9b9a4 · 8f9b9a4
1 parent 717baf6
commit 8f9b9a4
Show file tree

Hide file tree

Showing 2 changed files with 35 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -121,6 +121,17 @@ module.exports = function(config) {
 * [в браузере](#Исполнение-шаблонов-в-браузере)
 * [для сборки HTML](#Использование-шаблонов-для-сборки-html)
 
+### Способы экспортирования бандла шаблонов
+
+Существуют разные способы сборки:
+
+* в виде CommonJS-модуля для [исполнения шаблонов в Node.js](#Исполнение-шаблонов-в-nodejs) или сборки с Browserify
+* в виде YM-модуля для [исполнения шаблонов в браузере](#Исполнение-шаблонов-в-браузере)
+
+По умолчанию сборщик пытается собрать шаблоны как CommonJS- и YM-модуль одновременно (будет возможно подключать как в среде браузера с модульной системой, так и в среде Node.js) и, если файл подключается иным способом, то при его исполнении объект с шаблонизатором экспортируется в глобальную область видимости.
+
+Это поведение описывается объектом опции `exports: { globals: true, commonJS: true, ym: true }` и является значением по умолчанию. В свойстве `globals` допустимо передать строку `'force'` для явного экспорта объекта с шаблонизатором в глобальную область видимости.
+
 ### Исполнение шаблонов в Node.js
 
 Скомпилированный файл подключается как модуль в формате [CommonJS](http://www.commonjs.org/).
@@ -148,14 +159,19 @@ var bemjson = BEMTREE.apply({ block: 'page', data: { /* ... */ } }),
 
   Шаблоны доступны из глобальной переменной `BEMTREE` или `BEMHTML`.
 
+  Значение опции `exports`: `{ globals: true }`.
+
   ```js
   var bemjson = BEMTREE.apply({ block: 'page', data: { /* ... */ } }),
       html = BEMHTML.apply(bemjson); // <html>...</html>
   ```
+
 * **С модульной системой YModules**
 
   Шаблоны доступны из модульной системы ([YModules](https://ru.bem.info/tools/bem/modules/)):
 
+  Значение опции `exports`: `{ ym: true }`.
+
   ```js
   modules.require(['BEMTREE', 'BEMHTML'], function(BEMTREE, BEMHTML) {
       var bemjson = BEMTREE.apply({ block: 'page', data: { /* ... */ } }),

diff --git a/api.ru.md b/api.ru.md
@@ -25,6 +25,7 @@ bemhtml
 * [sourceSuffixes](#sourcesuffixes)
 * [requires](#requires)
 * [exportName](#exportname)
+* [exports](#exports)
 * [forceBaseTemplates](#forceBaseTemplates)
 * [engineOptions](#engineoptions)
 * [naming](#naming)
@@ -83,6 +84,24 @@ bemhtml
   });
   ```
 
+#### exports
+
+Тип: `{globals: ?(Boolean|'force'), commonJS: ?Boolean, ym: ?Boolean}`.
+
+Указывает каким именно образом должен экспортироваться экземпляр BEMHTML.
+
+По умолчанию: `{ globals: true, commonJS: true, ym: true }`.
+
+Доступны следующие параметры:
+* `globals` указывает выгружать ли ссылку на экземпляр в глобальную область видимости, игнорируется, если указана одна из модульных систем, со значением `'force'` экспортируется безусловно;
+* `ym` — регистрировать ли экземпляр как модуль в YModules (при наличии переменной modules);
+* `commonJS` — записывать ли экземпляр в `modules.exports` (при его наличии).
+
+Примеры использования:
+- В случае переходного периода с глобального объекта к YModules можно передать `{globals: 'force', ym: true}` и шаблонизатор будет экспортирован для использования и из YModules, и из глобальной области видимости.
+- Передав `{ym: true}` или `{commonJS: true}` можно запретить экспорт в глобальную область видимости.
+- Передав `{ym: true, commonJS}` можно собрать бандл и для node.js, и для браузера с YModules, но без экспорта в глобальную область видимости.
+
 #### forceBaseTemplates
 
 Тип: `Boolean`. По умолчанию `false`.