API технологий

Пакет предоставляет следующие технологии:

levels
levelsToBemdecl
bemjsonToBemdecl
deps
depsOld
depsByTechToBemdecl
files
provideBemdecl
provideDeps
mergeBemdecl
mergeDeps
subtractDeps

levels

Собирает информацию о БЭМ-сущностях на уровнях переопределения. Результат выполнения этой технологии необходим следующим технологиям:

levelsToBemdecl
deps
depsOld
files

Информация представляет собой экземпляр класса Levels.

target

Тип: String. По умолчанию: ?.levels.

Имя таргета, в который будет записан результат сканирования уровней переопределения.

levels

Тип: String[] | Object[].

Список путей до уровней переопределения.

Каждый путь может быть абсолютным или задаваться относительно корня проекта.

Вместо строки может использоваться объект вида { path: 'path/to/level', check: false }. Поле path является обязательным, а поле check по умолчанию равно true.

Допустимые значения поля check:

false — используется, чтобы закэшировать содержимое уровня.
true — уровень будет сканироваться заново каждый раз при сборке вне зависимости от наличия кэша.

Пример

var bemTechs = require('enb-bem-techs');

module.exports = function (config) {
    config.node('bundle', function (node) {
        node.addTech([bemTechs.levels, {
            levels: [
                // В проекте не нужно менять код внешних библиотек,
                // достаточно один раз просканировать их уровни и использовать кэш.
                { path: 'libs/bem-core/common.blocks', check: false },
                { path: 'libs/bem-core/desktop.blocks', check: false },

                // Уровни проекта нужно сканировать перед каждой сборкой.
                { path: 'desktop.blocks', check: true },
            ]
        }]);
        node.addTarget('?.levels');
    });
}

levelsToBemdecl

Формирует BEMDECL-файл, состоящий из всех БЭМ-сущностей, найденных в указанных уровнях.

Опции

source
target
bemdeclFormat

source

Тип: String. По умолчанию: ?.levels.

Имя таргета, из которого будет доступен результат сканирования уровней переопределения (Levels). Информацию об уровнях переопределения предоставляет технология levels.

target

Тип: String. По умолчанию: ?.bemdecl.js.

Имя файла, в который будет записан BEMDECL-файл со всеми БЭМ-сущностями, найденными в уровнях переопределения.

bemdeclFormat

Тип: String. По умолчанию: bemdecl.

Формат результирующей декларации. Возможные значения:

bemdecl — стандартный BEMDECL-формат.

Пример

{ blocks: [{ name: 'b', elems: [{ name: 'e', mods: [{ name: 'm', vals: [{ name: 'v' }] }] }] }]}

deps — формат результата deps и depsOld техннологий.
Пример
```
{ deps: [{ block: 'b', elem: 'e', mod: 'm', val: 'v' }] }
```

Пример

var bemTechs = require('enb-bem-techs');

module.exports = function (config) {
    config.node('bundle', function (node) {
        node.addTechs([
            // Сканируем уровни проекта.
            // Результат записываем в `?.levels`,
            // т.к. опция `target` по умолчанию — `?.levels`.
            [bemTechs.levels, { levels: ['blocks'] }],

            // Строим BEMDECL-файл по результатам сканирования уровней.
            // Интроспекцию берем из `?.levels`,
            // т.к. опция `source` по умолчанию — `?.levels`.
            [bemTechs.levelsToBemdecl]
        ]);
        node.addTarget('?.bemdecl.js');
    });
};

bemjsonToBemdecl

Формирует BEMDECL-файл из BEMJSON-файла.

Опции

source
target
bemdeclFormat

source

Тип: String. По умолчанию: ?.bemjson.js.

Имя BEMJSON-файла, по которому будет построена декларация.

target

Тип: String. По умолчанию: ?.bemdecl.js.

Имя создоваемого BEMDECL-файла.

bemdeclFormat

Тип: String. По умолчанию: bemdecl.

Формат результирующей декларации. Возможные значения:

bemdecl — стандартный BEMDECL-формат.

Пример

{ blocks: [{ name: 'b', elems: [{ name: 'e', mods: [{ name: 'm', vals: [{ name: 'v' }] }] }] }]}

deps — формат результата deps и depsOld техннологий.
Пример
```
{ deps: [{ block: 'b', elem: 'e', mod: 'm', val: 'v' }] }
```

Пример

var bemTechs = require('enb-bem-techs'),
    FileProviderTech = require('enb/techs/file-provider');

module.exports = function (config) {
    config.node('bundle', function (node) {
        node.addTechs([
            // Предоставляет BEMJSON-файл, написанный вручную, для ENB.
            // В опции `target` имя BEMJSON-файла.
            [FileProviderTech, { target: '?.bemjson.js' }],

            // Строим BEMDECL-файл по полученному BEMJSON-файлу.
            // BEMJSON-файл берем из `?.bemjson.js`,
            // т.к. опция `source` по умолчанию — `?.bemjson.js`.
            [bemTechs.bemjsonToBemdecl]
        ]);
        node.addTarget('?.bemdecl.js');
    });
};

deps

Дополняет декларацию БЭМ-сущностей на основе информации из технологий зависимостей (deps.js или deps.yaml).

Опции

target
bemdeclFile
levelsTarget

target

Тип: String. По умолчанию: ?.deps.js.

Имя собираемого файла с дополненной и упорядоченной декларацией БЭМ-сущностей.

bemdeclFile

Тип: String. По умолчанию: ?.bemdecl.js.

Имя файла с исходной декларацией БЭМ-сущностей.

levelsTarget

Тип: String. По умолчанию: ?.levels.

Пример

Раскрытие зависимостей по BEMDECL-файлу.

var bemTechs = require('enb-bem-techs');

module.exports = function (config) {
    config.node('bundle', function (node) {
        node.addTech([bemTechs.deps, {
            bemdeclFile: '?.bemdecl.js',
            target: '?.deps.js'
        }]);
        node.addTarget('?.deps.js');
    });
};

Раскрытие зависимостей по DEPS-файлу.

var bemTechs = require('enb-bem-techs');

module.exports = function (config) {
    config.node('bundle', function (node) {
        node.addTech([bemTechs.deps, {
            bemdeclFile: 'source-decl.deps.js',
            target: '?.deps.js'
        }]);
        node.addTarget('?.deps.js');
    });
};

depsOld

Дополняет декларацию БЭМ-сущностей на основании информации из технологий зависимостей (deps.js).

Использует алгоритм, заимствованный из bem-tools.

Опции

target
bemdeclFile
levelsTarget

target

Тип: String. По умолчанию: ?.deps.js.

Имя собираемого файла с дополненной и упорядоченной декларацией БЭМ-сущностей.

bemdeclFile

Тип: String. По умолчанию: ?.bemdecl.js.

Имя файла с исходной декларацией БЭМ-сущностей.

levelsTarget

Тип: String. По умолчанию: ?.levels.

strict

Тип: Boolean. По умолчанию: false.

Включает строгий режим раскрытия зависимостей: если будет найдена хотя бы одна циклическая зависимость mustDeps (A ← B ← A), то сборка прекратится с ошибкой.

Пример

Раскрытие зависимостей по BEMDECL-файлу.

var bemTechs = require('enb-bem-techs');

module.exports = function (config) {
    config.node('bundle', function (node) {
        node.addTech([bemTechs.depsOld, {
            bemdeclFile: '?.bemdecl.js',
            target: '?.deps.js'
        }]);
        node.addTarget('?.deps.js');
    });
};

Раскрытие зависимостей по DEPS-файлу.

var bemTechs = require('enb-bem-techs');

module.exports = function (config) {
    config.node('bundle', function (node) {
        node.addTech([bemTechs.depsOld, {
            bemdeclFile: 'source-decl.deps.js',
            target: '?.deps.js'
        }]);
        node.addTarget('?.deps.js');
    });
};

depsByTechToBemdecl

Формирует BEMDECL-файл на основе зависимостей по технологиям (depsByTech). Такие зависимости описываются в deps.js-технологиях.

Опции

target
sourceTech
destTech
filesTarget
sourceSuffixes
bemdeclFormat

target

Тип: String. По умолчанию: ?.bemdecl.js.

Имя создоваемого BEMDECL-файла.

sourceTech

Тип: String. Обязательная опция.

Имя технологии, для которой собираются зависимости.

destTech

Тип: String.

Имя технологии, от которой зависит sourceTech.

filesTarget

Тип: String. По умолчанию: ?.files.

Имя таргета, из которого будет доступен список исходных deps.js файлов для сборки. Список файлов предоставляет технология files.

sourceSuffixes

Тип: String[]. По умолчанию: ['deps.js'].

Суффиксы файлов, по которым отбираются исходные файлы зависимостей для дальнейшей сборки.

bemdeclFormat

Тип: String. По умолчанию: bemdecl.

Формат результирующей декларации. Возможные значения:

bemdecl — стандартный BEMDECL-формат.

Пример:

{ blocks: [{ name: 'b', elems: [{ name: 'e', mods: [{ name: 'm', vals: [{ name: 'v' }] }] }] }]}

deps — формат результата deps и depsOld техннологий.
Пример:
```
{ deps: [{ block: 'b', elem: 'e', mod: 'm', val: 'v' }] }
```

Пример

Частый случай, когда БЭМ-сущность в технологии клиенского JavaScript использует свою же технологию шаблонов.

button.deps.js

{
    block: 'button'
    tech: 'js'          // sourceTech
    shouldDeps: {
        tech: 'bemhtml' // destTech
    }
}

В большинстве случаев схема построения BEMDECL-файла по depsByTech выглядит так:

(BEMJSON ->) BEMDECL (1) -> deps (2) -> files (3) -> BEMDECL (4)

Получаем BEMDECL-файл (?.bemdecl.js).
Дополняем декларацию БЭМ-сущностей из BEMDECL-файла и записываем результат в DEPS-файл (?.deps.js).
Получаем упорядоченный список deps.js файлов (?.files.js).
Получаем BEMDECL-файл на основании зависимостей по технологиям (?.tech.bemdecl.js).

var bemTechs = require('enb-bem-techs'),
    FileProviderTech = require('enb/techs/file-provider');

module.exports = function (config) {
    config.node('bundle', function () {
        node.addTechs([
            [bemTechs.levels, { levels: ['blocks'] }],
            [FileProviderTech, { target: '?.bemdecl.js' }], // (1) `?.bemdecl.js`
            [bemTechs.deps],                          // (2) `?.deps.js`
            [bemTechs.files],                         // (3) `?.files.js`
            // Далее '?.bemhtml.bemdecl.js' можно использовать для сборки шаблонов,
            // которые используются в клиенском JavaScript.
            // Список `deps.js` файлов берем из `?.files`, т.к. опция filesTarget
            // по умолчанию — `?.files`.
            [bemTechs.depsByTechToBemdecl, {          // (4) `?.bemhtml.bemdecl.js`
                target: '?.bemhtml.bemdecl.js',
                sourceTech: 'js',
                destTech: 'bemhtml'
            }]
        ]);
        node.addTarget('?.bemdecl.js');
    });
};

files

Собирает список исходных файлов и директорий для сборки на основе декларации БЭМ-сущностей, а также результате сканирования уровней (Levels).

Результат будет записан в два таргета:

Список файлов — ?.files таргет. Настраивается опцией filesTarget.
Список директорий — ?.dirs таргет. Настраивается опцией dirsTarget.

Каждый список представлен экземпляром класса FileList.

Большинство технологий из других пакетов принимают на вход результат этой технологии.

Опции

filesTarget
dirsTarget
depsFile
levelstarget

filesTarget

Тип: String. По умолчанию: ?.files.

Имя таргета, в который будет записан список файлов.

dirsTarget

Тип: String. По умолчанию: ?.dirs.

Имя таргета, в который будет записан список директорий.

depsFile

Тип: String. По умолчанию: ?.deps.js.

Имя файла с декларацией БЭМ-сущностей.

levelsTarget

Тип: String. По умолчанию: ?.levels.

Пример

Формирование списка файлов и директорий по BEMDECL-файлу.

var bemTechs = require('enb-bem-techs'),
    FileProviderTech = require('enb/techs/file-provider');

module.exports = function (config) {
    config.node('bundle', function (node) {
        node.addTechs([
            [bemTechs.levels, { levels: ['blocks'] }],
            [FileProviderTech, { target: '?.bemdecl.js' }]
            [bemTechs.files, { depsFile: '?.bemdecl.js' }]
        ]);
        node.addTargets(['?.files', '?.dirs']);
    });
};

Формирование списка файлов и директорий по DEPS-файлу.

var bemTechs = require('enb-bem-techs'),
    FileProviderTech = require('enb/techs/file-provider');

module.exports = function (config) {
    config.node('bundle', function (node) {
        node.addTechs([
            [bemTechs.levels, { levels: ['blocks'] }],
            [FileProviderTech, { target: '?.bemdecl.js' }]
            [bemTechs.deps],
            [bemTechs.files]
        ]);
        node.addTargets(['?.files', '?.dirs']);
    });
};

provideBemdecl

Копирует BEMDECL-файл в текущую ноду (node) по указанному имени из указанной ноды (node) .

Может понадобиться для объединения BEMDECL-файлов из разных нод (node) .

Опции

node
source
target

node

Тип: String. Обязательная опция.

Путь к ноде (node) с исходным BEMDECL-файлом.

source

Тип: String. По умолчанию: ?.bemdecl.js (демаскируется в рамках исходной ноды).

Имя исходного BEMDECL-файла, который будет скопирован.

target

Тип: String. По умолчанию: ?.bemdecl.js (демаскируется в рамках текущей ноды).

Имя создоваемого BEMDECL-файла.

Пример

/**
 * Ноды в файловой системе до сборки:
 *
 * bundles/
 * ├── bundle-1/
 *     └── bundle-1.bemdecl.js
 * ├── bundle-2/
 *     └── bundle-1.bemdecl.js
 * └── bundle-3/
 *
 * Что должно получиться после сборки:
 *
 * bundles/
 * ├── bundle-1/
 *     └── bundle-1.bemdecl.js
 * ├── bundle-2/
 *     └── bundle-2.bemdecl.js
 * └── bundle-3/
 *     ├── bundle-1.bemdecl.js
 *     └── bundle-2.bemdecl.js
 */

var bemTechs = require('enb-bem-techs');

module.exports = function (config) {
    config.node('bundle-3', function (node) {
        node.addTechs([
            // Копируем BEMDECL-файл из ноды `bundle-1` в `bundle-3`
            [bemTechs.provideBemdecl, {
                node: 'bundles/bundle-1',
                source: 'bundle-1.bemdecl.js',
                target: 'bundle-1.bemdecl.js'
            }],

            // Копируем BEMDECL-файл из ноды `bundle-2` в `bundle-3`
            [bemTechs.provideBemdecl, {
                node: 'bundles/bundle-2',
                source: 'bundle-2.bemdecl.js',
                target: 'bundle-2.bemdecl.js'
            }]
        ]);
        node.addTargets(['bundle-1.bemdecl.js', 'bundle-2.bemdecl.js']);
    })
};

provideDeps

Копирует DEPS-файл в текущую ноду (node) по указанному имени из указанной ноды (node) .

Может понадобиться для объединения DEPS-файлов из разных нод (node) .

Опции

node
source
target

node

Тип: String. Обязательная опция.

Путь к ноде (node) с исходным DEPS-файлом.

source

Тип: String. По умолчанию: ?.deps.js (демаскируется в рамках исходной ноды).

Имя исходного DEPS-файла, который будет скопирован из указанной ноды (node).

target

Тип: String. По умолчанию: ?.deps.js (демаскируется в рамках текущей ноды).

Имя создоваемого DEPS-файла.

Пример

/**
 * Ноды в файловой системе до сборки:
 *
 * bundles/
 * ├── bundle-1/
 *     └── bundle-1.deps.js
 * ├── bundle-2/
 *     └── bundle-1.deps.js
 * └── bundle-3/
 *
 * Что должно получиться после сборки:
 *
 * bundles/
 * ├── bundle-1/
 *     └── bundle-1.deps.js
 * ├── bundle-2/
 *     └── bundle-2.deps.js
 * └── bundle-3/
 *     ├── bundle-1.deps.js
 *     └── bundle-2.deps.js
 */

var bemTechs = require('enb-bem-techs');

module.exports = function (config) {
    config.node('bundle-3', function (node) {
        node.addTechs([
            // Копируем DEPS-файл из ноды `bundle-1` в `bundle-3`
            [bemTechs.provideDeps, {
                node: 'bundles/bundle-1',
                target: 'bundle-1.deps.js'
            }],

            // Копируем DEPS-файл из ноды `bundle-2` в `bundle-3`
            [bemTechs.provideDeps, {
                node: 'bundles/bundle-2',
                target: 'bundle-2.deps.js'
            }]
        ]);
        node.addTargets(['bundle-1.deps.js', 'bundle-2.deps.js'])
    });
};

mergeBemdecl

Объединяет BEMDECL-файлы в один файл.

Может понадобиться для формирования merged-бандла.

Опции

sources
target

sources

Тип: String[]. Обязательная опция.

Список имен исходных BEMDECL-файлов, которые будут объединены.

target

Тип: String. По умолчанию: ?.bemdecl.js.

Имя собираемого BEMDECL-файла.

Пример

/**
 * Ноды в файловой системе до сборки:
 *
 * merged-bundle/
 * ├── bundle-1.bemdecl.js
 * └── bundle-2.bemdecl.js
 *
 * Что должно получиться после сборки:
 *
 * merged-bundle/
 * ├── bundle-1.bemdecl.js
 * ├── bundle-2.bemdecl.js
 * └── merged-bundle.bemdecl.js
 */

var bemTechs = require('enb-bem-techs');

module.exports = function (config) {
    config.node('merged-bundle', function (node) {
        node.addTech([bemTechs.mergeBemdecl, {
            sources: ['bundle-1.bemdecl.js', 'bundle-2.bemdecl.js'],
            target: 'merged-bundle.bemdecl.js'
        }]);
        node.addTarget('merged-bundle.bemdecl.js');
    });
};

mergeDeps

Объединяет DEPS-файлы и BEMDECL-файлы в результирующий DEPS-файл.

Может понадобиться для формирования merged-бандла.

Опции

sources
target

sources

Тип: String[]. Обязательная опция.

Список имен исходных DEPS-файлов, которые будут объединены.

target

Тип: String. По умолчанию: ?.bemdecl.js.

Имя собираемого DEPS-файла.

Пример

/**
 * Ноды в файловой системе до сборки:
 *
 * merged-bundle/
 * ├── bundle-1.deps.js
 * └── bundle-2.deps.js
 *
 * Что должно получиться после сборки:
 *
 * merged-bundle/
 * ├── bundle-1.deps.js
 * ├── bundle-2.deps.js
 * └── merged-bundle.deps.js
 */

var bemTechs = require('enb-bem-techs');

module.exports = function (config) {
    config.node('merged-bundle', function (node) {
        node.addTech([bemTechs.mergeDeps, {
            sources: ['bundle-1.deps.js', 'bundle-2.deps.js'],
            target: 'merged-bundle.deps.js'
        }]);
        node.addTarget('merged-bundle.deps.js');
    });
};

subtractDeps

Формирует DEPS-файл, вычитая один DEPS-файл из другого.

Опции

target
from
what

target

Тип: String. По умолчанию: ?.deps.js.

Имя собираемого DEPS-файла.

from

Тип: String. Обязательная опция.

Имя DEPS-файла, из которого вычитают.

what

Тип: String. Обязательная опция.

Имя DEPS-файла, который вычитают.

Пример

var bemTechs = require('enb-bem-techs');

module.exports = function (config) {
    config.node('bundle', function () {
        node.addTech([bemTechs.subtractDeps, {
            from: 'bundle-1.deps.js',
            what: 'bundle-2.deps.js',
            target: 'bundle.deps.js'
        } ]);
        node.addTarget('bundle.deps.js');
    });
};

Методология

Технологии

Инструментарий

Библиотеки

Учебные материалы

API технологий

levels

Опции

target

levels

levelsToBemdecl

Опции

source

target

bemdeclFormat

bemjsonToBemdecl

Опции

source

target

bemdeclFormat

deps

Опции

target

bemdeclFile

levelsTarget

depsOld

Опции

target

bemdeclFile

levelsTarget

strict

depsByTechToBemdecl

Опции

target

sourceTech

destTech

filesTarget

sourceSuffixes

bemdeclFormat

files

Опции

filesTarget

dirsTarget

depsFile

levelsTarget

provideBemdecl

Опции

node

source

target

provideDeps

Опции

node

source

target

mergeBemdecl

Опции

sources

target

mergeDeps

Опции

sources

target

subtractDeps

Опции

target

from

what