diff --git a/method-docs/bem-build.ru.md b/method-docs/bem-build.ru.md deleted file mode 100644 index 68ece57..0000000 --- a/method-docs/bem-build.ru.md +++ /dev/null @@ -1,245 +0,0 @@ -# Методология сборки БЭМ-проекта - -Организация файловой системы, обусловленная использованием компонентного подхода, определяет особенности сборки БЭМ-проекта. - -Сборка решает следующие задачи: -* собирает отдельные [файлы реализаций](../filesystem/filesystem.ru.md#Реализация-блока-разделяется-на-отдельные-файлы), разложенные по файловой системе; -* включает в сборку только нужные блоки, элементы и модификаторы из имеющихся в проекте; -* учитывает порядок подключения файлов в сборку. - -Рассмотрим организацию файловой структуры типового БЭМ-проекта. - -БЭМ-методология предполагает разделение интерфейса на независимые [блоки](../definitions/definitions.ru.md#Блок). Блоки, в свою очередь, могут быть реализованы в одной или нескольких [технологиях](../definitions/definitions.ru.md#Технология-реализации). Технологии реализации находятся в отдельных файлах. [Реализация](../definitions/definitions.ru.md#Реализация-блока) каждого блока может быть дополнительно разделена по [уровням переопределения](../definitions/definitions.ru.md#Уровень-переопределения). - -Например: - -``` -blocks/ # Уровень проекта - input/ # Директория блока `input` - input.css # Реализация блока `input` в технологии CSS - input.js # Реализация блока `input` в технологии JavaScript - icon/ - icon.css -library/ # Уровень библиотеки - input/ - button/ -``` - ->Подробно о целях разделения блоков на отдельные файлы читайте в документе [Организация файловой системы БЭМ-проекта](../filesystem/filesystem.ru.md). - -## Основные этапы сборки - -Чтобы из директорий и файлов получить рабочую страницу (результат сборки), необходимо: - -* Разработчику: - - * [перечислить блоки, элементы и модификаторы, учавствующие в построении страницы](#Перечисление-необходимых-блоков-и-элементов-для-создания-страницы) - -* Инструменту сборки: - - * [указать зависимости используемых БЭМ-сущностей](#Поиск-необходимых-зависимостей-используемых-БЭМ-сущностей) - * [собрать исходные файлы](#Определение-порядка-подключения-БЭМ-сущностей-в-сборку) - - -### Результаты сборки - -В результате сборки можно получить разные финальные наборы файлов: -* файлы для отдельной страницы (например, `hello-page.css` и `hello-page.js`); -* общие файлы для всего проекта (например, один `project.css` и `project.js` для всего проекта и отдельные шаблоны для каждой страницы); -* файлы для фрагмента страницы (например, `header.css` и `header.js`.) Используются, когда существует общая часть для всех страниц проекта. Удобно собрать ее отдельно и подключать при сборке. - -Такие наборы файлов, полученные в результате сборки, в БЭМ-методологии принято называть **бандлами**. - -> В этом документе сборка рассматривается на примере страницы — частного случая бандла. - -В файловой системе собранные файлы помещается в отдельную директорию с названием страницы (например, `hello-page`): - -``` -blocks/ # Директория, содержащая блоки -bundles/ # Директория, содержащая все результаты сборки - hello-page/ # Директория страницы `hello-page` -``` - -Пример файловой системы БЭМ-проекта до выполнения сборки: - -``` -blocks/ # Директория, содержащая блоки -bundles/ # Директория, содержащая все результаты сборки - hello-page/ # Директория страницы `hello-page` - hello-page.decl.js # Список БЭМ-сущностей, которые необходимы для страницы `hello-page` -``` - -Пример файловой системы БЭМ-проекта после выполнения сборки: - -``` -blocks/ # Директория, содержащая блоки -bundles/ # Директория, содержащая все результаты сборки - hello-page/ # Директория страницы `hello-page` - hello-page.decl.js # Список БЭМ-сущностей, которые необходимы для страницы `hello-page` - hello-page.css # Собранный CSS-файл страницы `hello-page` - hello-page.js # Собранный JavaScript-файл страницы `hello-page` -``` - -В зависимости от способа сборки в проект могут быть включены: -* все БЭМ-сущности с файловой системы (что значительно увеличивает кодовую базу); -* только необходимые для постороения страницы БЭМ-сущности в строго определенном порядке. - -Для сборки в проект только нужных БЭМ-сущностей могут использоваться: - -* [Декларация](#Определение-списка-блоков-элементов-и-модификаторов-для-создания-страницы) — опеределяет список БЭМ-сущностей, необходимых для создания страницы. -* [Зависимости](#Поиск-необходимых-зависимостей-используемых-БЭМ-сущностей) — определяют дополнительные БЭМ-сущности, необходимые для создания страницы. -* [Уровни переопределения](#Определение-порядка-подключения-БЭМ-сущностей-в-сборку) — определяеют порядок подключения БЭМ-сущностей в сборку. - -### Определение списка блоков, элементов и модификаторов для создания страницы - -Чтобы начать сборку страницы, необходимо узнать, из чего она состоит. - -![Декларация](https://img-fotki.yandex.ru/get/15577/246231603.1/0_16353e_4f60f18f_orig) - -Рассмотрим на примере, для чего формируется список необходимых БЭМ-сущностей: - -В проект подключена библиотека, из которой на странице используются несколько блоков. Нет необходимости включать все блоки библиотеки в сборку. Достаточно составить список нужных блоков по описанию страницы, на основании этого списка в сборку попадут только перечисленные блоки. В БЭМ-методологии такой список называется **декларацией**. - -Основная задача декларации определить, что и в каком порядке подключать в сборку. - -В большинстве проектов, построенных не по БЭМ-методологии, структура страницы описывается с помощью HTML. В БЭМ-проекте все БЭМ-сущности, необходимые для построения страницы, описываются в декларации. Существуют различные способы построения декларации, подробнее о них читайте в разделе [Способы получения декларации](#Способы-получения-декларации). - ->В БЭМ-платформе описание страницы создается формате BEMJSON, а декларация страницы описывается в формате BEMDECL, например: -```js -exports.blocks = [ - { name: 'input' }, - { name: 'button' }, - { name: 'checkbox' } -]; -``` - -#### Способы получения декларации - -Декларация может формироваться вручную (для этого нужно перечислить БЭМ-сущности, необходимые для построения страницы) или строиться автоматически: - -* [по описанию страницы](#Создание-декларации-по-описанию-страницы) -* [с помощью интроспекции файловой системы](#Создание-декларации-с-помощью-интроспекции-файловой-системы) - -##### Создание декларации по описанию страницы - -В БЭМ-проекте структура страницы описывается с помощью [БЭМ-дерева](../definitions/definitions.ru.md#БЭМ-дерево). HTML страницы содержит классы с именами всех используемых блоков, элементов и модификаторов. БЭМ-дерево может быть построено автоматически на основании данных из HTML-файла или создано вручную. - -При сборке страницы декларация формируется автоматически на основании данных из БЭМ-дерева: все сущности (блоки, элементы и модификаторы) попадают в декларацию в требуемом порядке, без повторений и отображения вложенности. Результатом сборки являются CSS- и JavaScript-файлы для этой страницы. - -Один из инструментов, позволяющих получить БЭМ-дерево по HTML-структуре страницы — [html2bemjson](https://github.com/bem-incubator/html2bemjson). - -![Способ создания декларации](https://img-fotki.yandex.ru/get/6114/246231603.1/0_162b0c_f5211dc6_orig) - ->Пример проекта, в котором формируется отдельная декларация для каждой страницы — [Создаем свой проект на БЭМ](https://ru.bem.info/tutorials/start-with-project-stub/). - -##### Создание декларации с помощью интроспекции файловой системы - -При сборке в декларацию автоматически попадают все БЭМ-сущности, находящиеся в файловой системе проекта со всех уровней переопределения. - -![Способ создания декларации](https://img-fotki.yandex.ru/get/4510/246231603.1/0_162b0d_d4139277_orig) - ->В [bem-components](https://ru.bem.info/libs/bem-components/) такой способ создания декларации используется для поставки библиотеки в виде [Dist](https://ru.bem.info/libs/bem-components/current/#Варианты-поставки-библиотеки). - -#### Способы управления декларациями - -С помощью деклараций можно управлять набором сущностей, попадающих в сборку. Декларации можно совмещать, повторно использовать, выделять общие части или различия. Такое управление дает возможность собирать все страницы в один [бандл](#bundle), догружать необходимые части страницы по требованию, повторно использовать уже собранные общие компоненты на разных страницах и не только. - -Рассмотрим возможные действия с декларациями: - -* [сложение](#Объединение-нескольких-деклараций-в-одну) — объединение нескольких деклараций в одну; -* [вычитание](#Получение-разницы-между-декларациями) — получение разницы между декларациями; -* [пересечение](#Получение-декларации-на-основе-пересечения-нескольких-других) — получение декларации на основе пересечения нескольких других. - -##### Объединение нескольких деклараций в одну - -Применяется для создания общих файлов технологий (например, одного CSS- и JavaScript-файла) для нескольких страниц. Используется, если необходимо загрузить все страницы одновременно и не тратить время при переходе между ними. - -![Объединение нескольких деклараций в одну](https://img-fotki.yandex.ru/get/3604/246231603.1/0_177332_dbcab202_orig.png) - -Один из способов применения — формирование [merged-бандла](https://github.com/enb-bem/enb-bem-techs/blob/master/docs/build-merged-bundle.md). В результате для объединенной декларации создаются общие файлы технологий. - -##### Получение разницы между декларациями - -Один из способов применения — сборка части страницы, которая догружается по требованию (например, в ответ на действие пользователя). Используется, если нет необходимости тратить время на загрузку части страницы, которая может не понадобиться. - -![Получение разницы между декларациями](https://img-fotki.yandex.ru/get/9511/246231603.1/0_177333_c58eddb7_orig.png) - -Например, на странице используется виртуальная клавиатура, которая становится доступна пользователю только в ответ на определенное действие. Нет необходимости включать этот блок в сборку всей страницы, так как это увеличит время при загрузке. Частично кнопки клавиатуры могут быть уже реализованы на странице для других целей. Возможность вычитать декларации позволяет создать отдельный бандл (файлы для части страницы) для недостающей реализации виртуальной клавиатуры и подключать его только по требованию. - -##### Получение общей части из нескольких деклараций - -Применяется для создания декларации, описывающей общие части разных страниц проекта. Это позволяет собрать общую часть для всех страниц и подключать ее при сборке один раз ко всем страницам. - -Например, такое разделение эффективно, если в проекте на всех страницах используется `шапка` и `подвал`. Общая часть страниц описывается в отдельной декларации. При сборке каждая страница формируется на основании двух деклараций: общей (содержащей `шапку` и `подвал`) и уникальной. - -![Получение общей части из нескольких деклараций](https://img-fotki.yandex.ru/get/5207/246231603.1/0_177334_972f6fd8_orig.png) - -### Поиск необходимых зависимостей используемых БЭМ-сущностей - -В БЭМ-методологии многие блоки строятся на основании других блоков. Так, например, блок формы поиска (`search-form`) построен с помощью блоков `input` (поле ввода) и `button` (кнопка). Нет необходиости реализовывать блок повторно, если он уже представлен в бибиотеке, и новый блок можно построить на основании существующего. - -Для обеспечения взаимосвязи между блоками и их корректной работы необходимо указать зависимости. - -Инструмент сборки получает данные о зависимостях и добавляет все сущности и технологии, необходимые для реализации блока, в сборку. В зависимостях также указывается порядок подключения сущностей в сборку. - -Существует несколько способов указать зависимости: - -* Непосредственно в коде блока (inplace). - - ``` - blocks/ - input/ - input.css # Зависимости в CSS можно определять по правилам `@import`. - input.js # Зависимости в JavaScript можно декларировать с помощью модульной системы или импортов (ECMAScript 2015 ES6) - button/ - button.css - button.js - ``` - -* В отдельном файле. - - >В БЭМ-платформе для указания зависимостей используется технология [DEPS](https://ru.bem.info/technology/deps/). - - ``` - blocks/ - input/ - input.css - input.js - input.deps.js # Файл с зависимостями блока `input`. - button/ - button.css - button.js - ``` - -### Определение порядка подключения БЭМ-сущностей в сборку - -Порядок подключения БЭМ-сущностей в сборку зависит от: -* **указанных зависимостей** - Тип зависимости определяет, когда дополнительная сущность должна попасть в сборку: в обязательном порядке до кода зависимого блока или порядок подключения не важен. -* **используемых уровней переопределения** - Важно соблюдать порядок подключения [уровней](../definitions/definitions.ru.md#Уровень-переопределения) в сборку. Если сравнить уровни со слоями, то базовый слой – это исходная реализация блока, а каждый последующий слой накладывается сверху и дополняет или изменяет базовую реализацию. Поэтому важно, чтобы в сборку сначала попадала исходная реализация, а затем изменения со всех уровней переопределения. - -На схеме показан принцип использования уровней переопределения при сборке: с уровня `common` подключаются общие компоненты для всех платформ, а с уровней `desktop` и `touch` — платформо-специфичные компоненты. - -![Уровни переопределения](https://img-fotki.yandex.ru/get/15587/246231603.1/0_162b0f_98525a17_orig) - -Подробно об использовании уровней читайте в примерах: - -* [Переопределение блоков библиотеки](../filesystem/filesystem.ru.md#Подключение-библиотеки). -* [Разделение проекта на платформы](../filesystem/filesystem.ru.md#Разделение-проекта-на-платформы). - -## Инструменты для сборки - -Выбор инструмента для сборки зависит от сложности БЭМ-проекта, наличия в нем уровней переопределения и использования зависимостей. - -БЭМ-методология не ограничивает выбор инструмента — можно использовать любые сборщики (например, Gulp, Grunt, Brunch, Broccoli), отвечающие требованиям вашего проекта. - ->Пример сборки БЭМ-проекта с помощью Gulp — [Декларативный JavaScript по БЭМ](https://ru.bem.info/events/beminar-july-2015/). - -В БЭМ-платформе реализованы два инструмента, которые подходят для сборки БЭМ-проектов любой сложности: - -* [ENB](https://ru.bem.info/tools/bem/enb-bem/) -* [bem-tools](https://ru.bem.info/tools/bem/bem-tools/) - ->Пример сборки БЭМ-проекта с помощью [ENB](https://ru.bem.info/tools/bem/enb-bem/) или [bem-tools](https://ru.bem.info/tools/bem/bem-tools/) — [Создаем свой проект на БЭМ](https://ru.bem.info/tutorials/start-with-project-stub/). - diff --git a/method-docs/build-method/build-method.ru.md b/method-docs/build-method/build-method.ru.md new file mode 100644 index 0000000..a5fe50d --- /dev/null +++ b/method-docs/build-method/build-method.ru.md @@ -0,0 +1,176 @@ +# Методология сборки БЭМ-проекта + +Компонентный подход в БЭМ-методологии определяет структуру проекта в файловой системе. Интерфейс разделяется на отдельные компоненты — блоки. Каждый компонент располагается в своей директории. Поэтому для получения рабочего БЭМ-проекта необходима сборка. + +Сборка решает следующие задачи: +* собирает отдельные [файлы реализаций](../filesystem/filesystem.ru.md#Реализация-блока-разделяется-на-отдельные-файлы), разложенные по файловой системе; +* включает в сборку только нужные [блоки](../definitions/definitions.ru.md#Блок), [элементы](../definitions/definitions.ru.md#Элемент) и [модификаторы](../definitions/definitions.ru.md#Модификатор) из имеющихся в проекте; +* учитывает порядок подключения файлов в сборку. + +Рассмотрим организацию файловой структуры БЭМ-проекта. + +Блоки могут быть реализованы в одной или нескольких [технологиях](../definitions/definitions.ru.md#Технология-реализации). Каждая технология реализации находятся в отдельном файле. [Реализация](../definitions/definitions.ru.md#Реализация-блока) блока, элемента или модификатора может быть дополнительно разделена по [уровням переопределения](../definitions/definitions.ru.md#Уровень-переопределения). + +Например: + +``` +blocks/ # Уровень проекта + input/ # Директория блока `input` + input.css # Реализация блока `input` в технологии CSS + input.js # Реализация блока `input` в технологии JavaScript + icon/ + icon.css +library/ # Уровень библиотеки + input/ + button/ +``` + +>Подробно о целях разделения блоков на отдельные файлы читайте в документе [Организация файловой системы БЭМ-проекта](../filesystem/filesystem.ru.md). + +## Основные этапы сборки + +Чтобы из отдельных файлов получить рабочую страницу (результат сборки), необходимо: + +* [перечислить блоки, элементы и модификаторы, участвующие в построении страницы](#Перечисление-необходимых-блоков-и-элементов-для-создания-страницы) +* [указать зависимости используемых БЭМ-сущностей](#Поиск-необходимых-зависимостей-используемых-БЭМ-сущностей) +* [собрать исходные файлы](#Определение-порядка-подключения-БЭМ-сущностей-в-сборку) + + +### Результаты сборки + +В результате сборки можно получить разные финальные наборы файлов: + +* файлы для отдельной страницы (например, `hello-page.css` и `hello-page.js`); +* общие файлы для всего проекта (например, один `project.css` и `project.js` и отдельные шаблоны для каждой страницы); +* файлы для фрагмента страницы (например, `header.css` и `header.js`.) Используются, когда существует общая часть для всех страниц проекта, которая собирается отдельно и подключается при сборке. + +Такие наборы файлов, полученные в результате сборки, в БЭМ-методологии принято называть **бандлами**. + +> Обратите внимание, в документе сборка рассматривается на примере **страницы** — частного случая бандла. + +В файловой системе собранные файлы помещаются в отдельную директорию с названием страницы (например, `hello-page`): + +``` +blocks/ # Директория, содержащая блоки +bundles/ # Директория, содержащая все результаты сборки + hello-page/ # Директория страницы `hello-page` +``` + +Пример файловой системы БЭМ-проекта до выполнения сборки: + +``` +blocks/ # Директория, содержащая блоки +bundles/ # Директория, содержащая все результаты сборки + hello-page/ # Директория страницы `hello-page` + hello-page.decl.js # Список БЭМ-сущностей, которые необходимы для страницы `hello-page` +``` + +Пример файловой системы БЭМ-проекта после выполнения сборки: + +``` +blocks/ # Директория, содержащая блоки +bundles/ # Директория, содержащая все результаты сборки + hello-page/ # Директория страницы `hello-page` + hello-page.decl.js # Список БЭМ-сущностей, которые необходимы для страницы `hello-page` + hello-page.css # Собранный CSS-файл страницы `hello-page` + hello-page.js # Собранный JavaScript-файл страницы `hello-page` +``` + +При сборке в проект могут быть включены: + +* все БЭМ-сущности с файловой системы (что значительно увеличивает объем результирующего кода); +* только необходимые для построения страницы БЭМ-сущности в строго определенном порядке. + +Для сборки в проект только нужных БЭМ-сущностей используются (опционально): + +* [Декларация](#Определение-списка-блоков-элементов-и-модификаторов-для-создания-страницы) — определяет список БЭМ-сущностей, необходимых для создания страницы. +* [Зависимости](#Поиск-зависимостей) — определяют дополнительные БЭМ-сущности. +* [Уровни переопределения](#Определение-порядка-подключения-БЭМ-сущностей-в-сборку) — определяют порядок подключения БЭМ-сущностей в сборку. + +### Определение списка блоков, элементов и модификаторов для создания страницы + +Чтобы начать сборку страницы, необходимо узнать, из чего она состоит. + +![Декларация](https://img-fotki.yandex.ru/get/15577/246231603.1/0_16353e_4f60f18f_orig) + +Рассмотрим на примере, для чего формируется список необходимых БЭМ-сущностей. + +В проект подключена библиотека, из которой на странице используются несколько блоков. Нет необходимости включать всю библиотеку в сборку. Достаточно составить список нужного по описанию страницы. На основании этого списка в сборку попадут только перечисленные блоки. В БЭМ-методологии такой список называется [декларацией](../declaration/declaration.ru.md). + +Основная задача декларации определить, что и в каком порядке подключать в сборку. + +Существуют различные [способы построения декларации](../declaration/declaration.ru.md#Способы-управления-декларациями). + +### Поиск зависимостей + +В БЭМ-методологии многие блоки строятся на основании других блоков. Так, например, блок формы поиска (`search-form`) построен с помощью блоков `input` (поле ввода) и `button` (кнопка). Нет необходимости реализовывать блок повторно, если он уже представлен в библиотеке. Новый блок можно построить на основании существующего. + +![Пример составного блока](https://img-fotki.yandex.ru/get/5308/246231603.1/0_17c68d_be6f9fbe_orig.png) + +Для обеспечения взаимосвязи между блоками и их корректной работы необходимо указать зависимости. + +Инструмент сборки получает данные о зависимостях и добавляет все сущности и технологии, необходимые для реализации блока, в сборку. В зависимостях также указывается порядок подключения сущностей. + +Существует несколько способов указать зависимости: + +* Непосредственно в коде блока (in place). + + ``` + blocks/ + input/ + input.css # Зависимости в CSS можно определять по `@import` + input.js # Зависимости в JavaScript можно декларировать + # с помощью модульной системы (например, AMD, + # CommonJS) или импортов (ECMAScript 2015) + button/ + button.css + button.js + ``` + +* В отдельном файле. + + >В БЭМ-платформе для указания зависимостей используется технология [DEPS](https://ru.bem.info/technology/deps/). + + ``` + blocks/ + input/ + input.css + input.js + input.deps.js # Файл с зависимостями блока `input` + button/ + button.css + button.js + ``` + +### Определение порядка подключения БЭМ-сущностей в сборку + +Порядок подключения БЭМ-сущностей в сборку зависит от: + +* **указанных зависимостей** + + Зависимости определяют, когда дополнительная сущность должна попасть в сборку. + +* **используемых уровней переопределения** + + Важно соблюдать порядок подключения [уровней](../definitions/definitions.ru.md#Уровень-переопределения) в сборку. Если сравнить уровни со слоями, то базовый слой – это исходная реализация блока, а каждый последующий слой накладывается сверху и дополняет (наследует) или изменяет базовую реализацию. Поэтому важно, чтобы в сборку сначала попадала исходная реализация, а затем изменения со всех уровней переопределения. + +На схеме показан принцип использования уровней переопределения при сборке: с уровня `common` подключаются общие компоненты для всех платформ, а с уровней `desktop` и `touch` — платформо-специфичные компоненты. + +![Уровни переопределения](https://img-fotki.yandex.ru/get/15587/246231603.1/0_162b0f_98525a17_orig) + +Подробно об использовании уровней читайте в примерах: + +* [Переопределение блоков библиотеки](../filesystem/filesystem.ru.md#Подключение-библиотеки) +* [Разделение проекта на платформы](../filesystem/filesystem.ru.md#Разделение-проекта-на-платформы) + +## Инструменты для сборки + +Выбор инструмента для сборки зависит от сложности БЭМ-проекта, наличия в нем уровней переопределения и использования зависимостей. + +БЭМ-методология не ограничивает выбор инструмента — можно использовать любые сборщики (например, Gulp, Grunt, Brunch, Broccoli), отвечающие требованиям вашего проекта. + +>Пример сборки БЭМ-проекта с помощью Gulp — [Декларативный JavaScript по БЭМ](https://ru.bem.info/events/beminar-july-2015/). + +В БЭМ-платформе используется сборщик [ENB](https://ru.bem.info/tools/bem/enb-bem/), который подходит для сборки БЭМ-проектов любой сложности. + +>Пример сборки БЭМ-проекта с помощью [ENB](https://ru.bem.info/tools/bem/enb-bem/) — [Создаем свой проект на БЭМ](https://ru.bem.info/tutorials/start-with-project-stub/). diff --git a/method-docs/declaration/declaration.ru.md b/method-docs/declaration/declaration.ru.md new file mode 100644 index 0000000..d99e861 --- /dev/null +++ b/method-docs/declaration/declaration.ru.md @@ -0,0 +1,125 @@ +# Декларации в БЭМ + +Чтобы собрать только необходимые БЭМ-сущности для постороения страницы (читай «частного случая [бандла](../build-method/build-method.ru.md#bundle)»), можно воспользоваться **декларацией**. + +Декларация представляет собой список [блоков](../definitions/definitions.ru.md#Блок), [элементов](../definitions/definitions.ru.md#Элемент) и [модификаторов](../definitions/definitions.ru.md#Модификатор), которые используются на странице. Таким образом, декларация ограничивает количество сущностей, попадающих в сборку. Нет необходимости подключать все блоки проекта, если можно собрать только нужные по списку. + +Существуют различные [способы построения декларации](#Способы-получения-декларации). + +Задача декларации определить, что и в каком порядке подключать в сборку. + +>В БЭМ-платформе описание страницы создается в формате BEMJSON, а декларация страницы описывается в формате BEMDECL, например: +```js +exports.blocks = [ + { name: 'input' }, + { name: 'button' }, + { name: 'checkbox' } +]; +``` + +## Способы получения декларации + +Декларация может формироваться вручную (для этого нужно перечислить БЭМ-сущности, необходимые для построения страницы) или строиться автоматически: + +* [по описанию страницы](#Создание-декларации-по-описанию-страницы) +* [с помощью интроспекции файловой системы](#Создание-декларации-с-помощью-интроспекции-файловой-системы) + +### Создание декларации по описанию страницы + +В БЭМ-проекте структура страницы описывается с помощью [БЭМ-дерева](../definitions/definitions.ru.md#БЭМ-дерево). HTML страницы содержит классы с именами всех используемых блоков, элементов и модификаторов. БЭМ-дерево может быть построено автоматически по классам из HTML-файла или создано вручную. + +При сборке страницы декларация формируется автоматически на основании данных из БЭМ-дерева: все сущности (блоки, элементы и модификаторы) попадают в декларацию в требуемом порядке, без повторений и отображения вложенности. Результатом сборки являются, например, CSS- и JavaScript-файлы для этой страницы. + +>Один из инструментов, позволяющих получить БЭМ-дерево по HTML-структуре страницы — [html2bemjson](https://github.com/bem-incubator/html2bemjson). + +![Способ создания декларации](https://img-fotki.yandex.ru/get/6114/246231603.1/0_162b0c_f5211dc6_orig) + +>Пример проекта, в котором формируется отдельная декларация для каждой страницы — [Создаем свой проект на БЭМ](https://ru.bem.info/tutorials/start-with-project-stub/). + +### Создание декларации с помощью интроспекции файловой системы + +При сборке в декларацию автоматически попадают все БЭМ-сущности, находящиеся в файловой системе проекта со всех уровней переопределения. + +![Способ создания декларации](https://img-fotki.yandex.ru/get/4510/246231603.1/0_162b0d_d4139277_orig) + +>В [bem-components](https://ru.bem.info/libs/bem-components/) такой способ создания декларации используется для поставки библиотеки в виде [Dist](https://ru.bem.info/libs/bem-components/current/#Варианты-поставки-библиотеки). + +## Способы управления декларациями + +С помощью деклараций можно управлять набором сущностей, попадающих в сборку. Декларации можно совмещать, повторно использовать, выделять общие части или различия. Такое управление дает возможность собирать все страницы в один [бандл](../build-method/build-method.ru.md#bundle), догружать необходимые части страницы по требованию, повторно использовать уже собранные общие компоненты на разных страницах и не только. + +Возможные действия с декларациями: + +* [сложение](#Объединение-нескольких-деклараций-в-одну) — объединение нескольких деклараций в одну; +* [вычитание](#Получение-разницы-между-декларациями) — получение разницы между декларациями; +* [пересечение](#Получение-декларации-на-основе-пересечения-нескольких-других) — получение декларации для общей части нескольких деклараций. + +### Объединение нескольких деклараций в одну + +Применяется для создания общих файлов технологий (например, общего CSS- и JavaScript-файла) для нескольких страниц. Используется, если необходимо загрузить все страницы одновременно и не тратить время при переходе между ними. + +``` +Декларация 1 Декларация 2 Декларация 3 + +[ [ [ + 'header', 'header', 'header', + 'input', 'input', 'input', + 'button', 'button', 'button', + 'link', 'link', + 'attach', + + 'attach', + 'menu', 'menu', + 'image', 'image', + 'checkbox', 'checkbox', + 'popup' 'popup', + 'textarea' 'textarea' +] ] ] +``` + +![Объединение деклараций](https://img-fotki.yandex.ru/get/15553/246231603.1/0_17be5e_b27a0dcd_orig.png) + +### Получение разницы между декларациями + +Один из способов применения — сборка части страницы, которая догружается по требованию (например, в ответ на действие пользователя). + +``` +Декларация 1 Декларация 2 Декларация 3 + +[ [ [ + 'button', 'button', + 'checkbox', 'checkbox', + 'textarea', 'textarea', + 'suggest' 'suggest' + 'header', + - 'input', = + 'button', + 'menu', + 'image', + 'popup' +] ] ] +``` + +![Получение разницы между декларациями](https://img-fotki.yandex.ru/get/15582/246231603.1/0_17be5f_571327ab_orig.png) + +Например, на странице используется виртуальная клавиатура, которая становится доступна пользователю только в ответ на определенное действие. Нет необходимости включать этот блок в сборку всей страницы, так как это увеличит время загрузки. Кнопки клавиатуры могут быть уже реализованы на странице для других целей. Возможность вычитать декларации позволяет создать отдельный бандл (файлы для части страницы) для недостающей реализации виртуальной клавиатуры и подключать его только по требованию. + +### Получение общей части из нескольких деклараций + +Применяется для создания декларации, описывающей общие части разных страниц проекта. Это позволяет собрать общую часть для всех страниц и подключать ее при сборке один раз ко всем страницам. + +Например, такое разделение эффективно, если в проекте на всех страницах используется `шапка` и `подвал`. Общая часть страниц описывается в отдельной декларации. При сборке каждая страница формируется на основании двух деклараций: общей (содержащей `шапку` и `подвал`) и уникальной. + +``` +Декларация 1 Декларация 2 Декларация 3 + +[ [ [ + 'header', 'header', 'header', + 'input', 'menu', + 'link', + 'button', = + 'attach', 'input', + 'checkbox', 'image', + 'textarea', 'popup', + 'footer' 'footer' 'footer' +] ] ] +``` + +![Получение общей части деклараций](https://img-fotki.yandex.ru/get/4302/246231603.1/0_17be60_3f67c646_orig.png)