builder-core
Core data builder for bem-site
Основной модуль сборки данных для bem сайтов.
Установка
Пакет устанавливается как обычная npm зависимость
$ npm install --save bs-builder-core
API
При подключении данного модуля с помощью common modules становятся доступными 2 переменые:
- Builder - основной класс сборщика управляющий процессом сборки.
- tasks - объект, который позволяет легко подключать все задачи сборки пакета
избегая множественных вызовов
require
.
var bsBuilderCore = require('bs-builder-core');
var tasks = bsBuilderCore.tasks,
Builder = bsBuilderCore.Builder;
Builder
init
Статический метод для инициализации нового экземпляра класса Builder
.
Аргументы:
-
- {String} logLevel - уровень логгирования инструмента
Пример использования:
var bsBuilderCore = require('bs-builder-core');
var tasks = bsBuilderCore.tasks,
Builder = bsBuilderCore.Builder;
var builder = Builder.init('debug');
Примечание: эквивалентен вызову var builder = new Builder(logLevel)
;
getConfig
Возвращает экземпляр конфигурационного класса инструмента
Аргументы: - нет
getTasks
Возвращает массив задач для сборки которые будут выполнены в том же порядке в котором они перечислены в массиве.
Аргументы: - нет
setLanguages
Позволяет переопределять набор языков для которых будет произведена сборка. По умолчанию набор языков состоит из одного элемента которым является английский.
Аргументы:
-
- {Array} setLanguages - массив языковых локалей.
Пример использования:
var builder = Builder
.init('debug')
.setLanguages(['en', 'ru']);
Примечание: Все методы экземпляра класса Builder
кроме метода run
и get*
методов
возвращают ссылку на экземпляр, что позволяет вызывать их по цепочке.
setCacheFolder
Позволяет переопределить путь для директории куда будут помещены временные файлы и папки,
создаваемые в результате сборки. Путь должен быть относительным по отношению к рабочей директории приложения.
По умолчанию ./builder/cache
.
Аргументы:
-
- {String} cacheFolder - относительный путь к директории для хранения временных файлов.
Пример использования:
var builder = Builder
.init('debug')
.setCacheFolder('./my-cache-folder');
setDataFolder
Позволяет переопределить путь для директории куда будут помещены финальные результаты сборки.
Путь должен быть относительным по отношению к рабочей директории приложения.
По умолчанию ./data
.
Аргументы:
-
- {String} dataFolder - относительный путь к директории для хранения файлов и папок результатов сборки.
Пример использования:
var builder = Builder
.init('debug')
.setDataFolder('./my-data-folder');
setModelFilePath
Позволяет переопределить путь для json - файла исходной модели.
Путь должен быть относительным по отношению к рабочей директории приложения.
По умолчанию ./model/model.json
.
Аргументы:
-
- {String} modelFilePath - относительный путь к файлу исходной модели.
Пример использования:
var builder = Builder
.init('debug')
.setModelFilePath('./foo/bar/my-custom-model.json');
addTask
Добавляет задачу в очередь сборки.
Аргументы:
-
- {Base} Task - классы задач сборки отнаследованные от базовой задачи.
-
- {Object} taskConfig - конфигурационный объект в котором хрантся настройки и параметры специфичные для данной задачи сборки.
Пример использования:
var tasks = require('bs-builder-core').tasks,
Builder = require('bs-builder-core').Builder,
builder;
builder = Builder.init('debug')
.addTask(tasks.LoadModelFiles)
.addTask(tasks.MergeModels);
run
Запускает сборку всех сконфигураированных задач последовательно. Возвращает Promise - объект.
В случае успешной сборки возвращаемый promise содержит модель изменений данных относительно предыдущего запуска.
В случае ошибки возвращает promise с объектом ошибки вызвавшим завершение сборки.
var tasks = require('bs-builder-core').tasks,
Builder = require('bs-builder-core').Builder,
builder;
builder = Builder.init('debug')
.addTask(tasks.LoadModelFiles)
.run();
Набор готовых задач сборки в пакете
Данный пакет содержит набор готовых задач сборки, выполнение части которых является обязательным.
MakeDirectory
-- Описание: Позволяет создавать произвольную директорию.
- Параметры: - { path: './foo/bar' } - относительный путь к директории которую необходимо создать
- Обязательное использование: - нет.
LoadModelFiles
-- Описание: Загружает новый и старый (с предыдущего запуска) файлы моделей.
- Параметры: - нет
- Обязательное использование: - да.
MergeModels
-- Описание: Позволяет находить различия между текущей моделью и моделью предыдущего запуска.
- Зависимости: LoadModelFiles
- Параметры: - нет
- Обязательное использование: - да.
SaveModelFile
-- Описание: Сохраняет новый файл модели на место предыдущего.
- Параметры: - нет
- Обязательное использование: - нет.
AnalyzeModel
-- Описание: Производит первичный анализ и нормализацию файла модели.
- Зависимости: MergeModels
- Параметры: - нет
- Обязательное использование: - да.
MakePagesCache
-- Описание: Для каждой страницы в модели создает директории в папке кеша пути к которым совпадают с url-ами страниц.
- Зависимости: MergeModels
- Параметры: - нет
- Обязательное использование: - нет.
RsyncPages
-- Описание: Сохраняет результат в файл
data.json
в целевой директории сборки. - Параметры:
-
- {Array }
exclude
- массив с паттернами файлов которые должны быть исключены из процесса синхронизации.
- {Array }
-
- {Array}
include
- массив с паттернами файлов которые должны быть включены в процесс синхронизации даже если они находятся вexclude
.
- {Array}
-
- Обязательное использование: - да.
SaveDataFile
-- Описание: Сохраняет результат в файл
data.json
в целевой директории сборки. - Зависимости: MergeModels
- Параметры: - нет
- Обязательное использование: - да.
Разработка собственной задачи сборки
// TODO написать документацию
Тестирование
Запуск тестов с вычислением покрытия кода тестами с помощью инструмента istanbul:
npm test
Проверка синтаксиса кода с помощью jshint и jscs
npm run codestyle
Особая благодарность за помощь в разработке:
- Ильченко Николай (http://github.com/tavriaforever)
- Константинова Гела (http://github.com/gela-d)
- Гриненко Владимир (http://github.com/tadatuta)
- Абрамов Андрей (https://github.com/blond)
Разработчик Кузнецов Андрей Серргеевич @tormozz48 Вопросы и предложения присылать по адресу: tormozz48@gmail.com