From 8478143f0a46c5c837e3aae5cc72fcd593781bed Mon Sep 17 00:00:00 2001
From: 4exova <4exova@yandex-team.ru>
Date: Tue, 30 Dec 2014 16:08:40 +0300
Subject: [PATCH 01/11] doc update
---
QuickStart.md | 325 +++++++++++++++++++++-----------------------------
1 file changed, 139 insertions(+), 186 deletions(-)
diff --git a/QuickStart.md b/QuickStart.md
index 919a4a2..f5a1a54 100644
--- a/QuickStart.md
+++ b/QuickStart.md
@@ -1,118 +1,78 @@
-# Как создать динамическую страницу с БЭМ
+## Быстрый старт по созданию статической страницы с БЭМ
-В этой статье мы рассмотрим пример реализации динамической функциональности страницы по [БЭМ-методологии](http://ru.bem.info/method/).
+В этой статье рассмотрен пример реализации статической страницы по [БЭМ-методологии](https://ru.bem.info/method/).
-# Что должно получиться
+## Что должно получиться
-Итогом проделанной работы будет страница с приветствием пользователя. Страница будет состоять из поля ввода, кнопки и приветствия. После того, как пользователь введет имя в поле и нажмет кнопку, его имя автоматически подставится в приветствие.
+Страница приветствия пользователя, содержащая поле ввода, кнопку и текст приветствия. При обновлении страницы (кнопка **Нажать**) текст дополняется значением, введенным в поле **Имя пользователя**.
-# Установка
+
-**Требования к установке**
+## С чего начать
-Для начала работы с любым БЭМ-проектом нужен [Node.js](http://nodejs.org).
+### Минимальные требования
-Устанавливаем свой собственный БЭМ-проект. В этом нам поможет [шаблонный репозиторий](https://github.com/bem/project-stub), который содержит необходимый минимум конфигурационных файлов и папок. Делаем локальную копию `project-stub`.
+Установленная платформа [Node.js](http://nodejs.org).
- git clone https://github.com/bem/project-stub.git start-project
- cd start-project
- npm install
+### Локальная копия и настройка окружения
-Собираем проект с помощью [ENB](http://enb-make.info/):
+Для создания БЭМ-проекта потребуется [шаблонный репозиторий](https://github.com/bem/project-stub), содержащий необходимый минимум конфигурационных файлов и папок.
- node_modules/.bin/enb make
+1. Сделайте локальную копию `project-stub`.
-Запускаем сервер:
+ **NB** В данном документе описана процедура установки для ревизии [13ae0e18ef8f48bc552b4944f7e5971c5b5f4768](https://github.com/bem/project-stub/ commit/13ae0e18ef8f48bc552b4944f7e5971c5b5f4768). Процесс установки последующих версий может отличаться.
- node_modules/.bin/enb server
+ ```bash
+ git clone https://github.com/bem/project-stub.git start-project
+ cd start-project
+ git checkout 13ae0e18ef8f48bc552b4944f7e5971c5b5f4768
+ npm install
+ ```
-При изменении конфигурации проекта нужно перезапускать сервер. Текущий процесс прерывается (`Ctrl+C`) и снова возобновляется командой запуска.
+2. Запустите сервер с помощью [ENB](https://ru.bem.info/tools/bem/enb-bem-techs/):
-Открываем браузер, чтобы проверить запустился ли сервер на компьютере:
+ ```bash
+ node_modules/.bin/npm start
+ ```
- http://localhost:8080/desktop.bundles/index/index.html
+3. Проверьте результат по ссылке [http://localhost:8080/desktop.bundles/index/index.html](http://localhost:8080/desktop.bundles/index/index.html).
-По умолчанию эта страница содержит примеры блоков библиотеки `bem-components`.
+ Должна открыться следующая страница:
-Альтернативный вариант для сборки проекта –– [bem-tools](http://ru.bem.info/tools/bem/bem-tools/). Результаты сборки в обоих случаях одинаковы.
+ 
-Про сборку проекта при помощи `bem-tools` вы можете почитать, пройдя по это ссылке http://ru.bem.info/tools/bem/bem-tools/commands/#bem-make.
+## Пошаговая инструкция по созданию проекта
-# Пошаговая инструкция по созданию проекта
-
-Этот раздел содержит пошаговую информацию по созданию динамической страницы.
-
-* [Создание страницы](#page_creation) –– рассмотрим варианты создания страницы.
-** [Описание страницы в BEMJSON-файле](#BEMJSON_declaration) –– опишем страницу в БЭМ-терминах.
-* [Создание блока](#block_creation) –– самостоятельно создадим блок.
-** [Создание блока с файлом определенной технологии](#block_using_concrete_tech) –– рассмотрим возможность создавать файлы блока конкретных технологий.
-* [Переопределение блока `hello`](#block_hello_modification) –– внесем необходимые изменения в файлы технологий блока.
-** [Реализация блока в технологии JS](#JS_modification) –– реализуем блок в технологии JavaScript.
-** [Реализация блока в технологии BEMHTML](#BEMHTML_modification) –– реализуем блок в технологии BEMHTML.
-** [Реализация блока в технологии CSS](#CSS_modification) –– реализуем блок в технологии CSS.
-* [Сборка проекта](#build) –– запустим сборку проекта.
+1. [Создайте страницу](#page_creation)
+ 1.1 [Опишите страницу в BEMJSON-файле](#BEMJSON_declaration)
+2. [Создайте блок](#block_creation)
+3. [Реализуйте блок hello](#block_hello_modification)
+ 3.1 [В технологии JavaScript](#JS_modification)
+ 3.2 [В технологии BEMHTML](#BEMHTML_modification)
+ 3.3 [В технологии CSS](#CSS_modification)
-## Создание страницы
-
-Макеты страниц размещаются в каталоге `desktop.bundles`. Данный каталог содержит одну директорию –– `index`. Вы можете продолжать работу с этой директорией. Для этого необходимо заменить декларацию файла `index.bemjson.js`. Пример описания BEMJSON-файла мы рассмотрим ниже.
-
-Альтернативный вариант –– создание новой страницы, используя команду [bem-tools](http://ru.bem.info/tools/bem/bem-tools/):
+### 1. Создайте страницу
- bem create -l desktop.bundles -b hello
+Исходники страниц размещаются в каталоге `desktop.bundles`. Изначально в проекте присутствует главная страница `index.html` с примерами блоков библиотеки [bem-components](http://ru.bem.info/libs/bem-components/).
-* `-l desktop.bundles` –– указывает на уровень переопределения `desktop.bundles`;
-* `-b hello` –– определяет имя блока страницы, в нашем случае `hello`.
+Создайте новую страницу. Для этого в каталоге `desktop.bundles` разместите папку с именем `hello` и добавьте в нее файл `hello.bemjson.js`.
-Выбирайте удобный для вас вариант. Дальше мы продолжим создание проекта на основе страницы `hello`.
-### Описание страницы в BEMJSON-файле
-
-#### Создаем свой блок
-
-Первым делом нам нужно добавить на страницу блок приветствия. Для того, чтобы разместить его на странице, добавим блок **hello** в файл `desktop.bundles/hello/hello.bemjson.js`.
-
-{ block: 'hello' }
-
-Дальше внутрь блока **hello** поместим элемент **greeting** с приветствием пользователя:
-
-```
-{
- elem: 'greeting',
- content: 'Привет, %пользователь%!'
-}
-```
-
-#### Используем готовые блоки
+#### 1.1 Опишите страницу в BEMJSON-файле
-Кроме приветствия на странице должно быть поле ввода и кнопка. Блоки **input** и **button** мы берем готовые из библиотеки [bem-components](http://ru.bem.info/libs/bem-components/v2/). И вкладываем их в элемент **greeting**.
+[BEMJSON-файл](https://ru.bem.info/technology/bemjson/) – это структура страницы, описанная в терминах блоков, элементов и модификаторов.
-```
-{
- elem: 'greeting',
- content: 'Привет, %пользователь%!'
- },
- {
- block: 'input',
- mods: {theme: 'islands', size: 'm'},
- placeholder: 'Имя пользователя'
- },
- {
- block : 'button',
- text : 'Нажать',
- mods : { theme : 'islands', size : 'm' }
- }
-}
-```
+1. Добавьте блок **hello** в файл `desktop.bundles/hello/hello.bemjson.js`.
-Если вы хотите внести какие-либо изменения в готовые блоки, это можно сделать на своем уровне переопределения. Подробнее об этом можно почитать, пройдя по ссылке http://ru.bem.info/tools/bem/bem-tools/levels/.
+2. Поместите элемент **greeting** с текстом приветствия пользователя в блок **hello**.
-Все необходимые блоки добавлены. Так будет выглядеть полный код страницы `desktop.bundles/hello/hello.bemjson.js`:
+3. Возьмите готовые реализации блоков **input** и **button** из библиотеки `bem-components` и добавьте их в элемент **greeting**.
-```
+```js
({
block: 'page',
title: 'hello',
@@ -120,145 +80,138 @@
{ elem: 'css', url: '_hello.css' }
],
scripts: [{ elem: 'js', url: '_hello.js' }],
+ mods: { theme: 'islands' },
content: [
{
- block: 'content',
- content: [
- {
- block: 'hello',
- name: 'BEMHTML',
- content: [
- {
- elem: 'greeting',
- content: 'Привет, %пользователь%!'
- }, {
- block: 'input',
- mods: {theme: 'islands', size: 'm'},
- placeholder: 'Имя пользователя'
- }, {
- block : 'button',
- text : 'Нажать',
- mods : { theme : 'islands', size : 'm' }
- }
- ]
- }
+ block: 'hello',
+ content: [
+ {
+ elem: 'greeting',
+ content: 'Привет, %пользователь%!'
+ },
+ {
+ block: 'input',
+ mods: { theme: 'islands', size: 'm' },
+ mix: { block: 'hello', elem: 'input' }, // подмешиваем элемент для добавления CSS-правил
+ name: 'name',
+ placeholder: 'Имя пользователя'
+ },
+ {
+ block : 'button',
+ mods : { theme : 'islands', size : 'm', type : 'submit' },
+ text : 'Нажать'
+ }
]
}
]
})
```
-Чтобы проверить запустился ли файл, откройте браузер по адресу:
+Если вы хотите внести какие-либо изменения в существующие блоки, это можно сделать на своем [уровне переопределения](https://ru.bem.info/tools/bem/bem-tools/levels/).
- http://localhost:8080/desktop.bundles/hello/hello.html
+Чтобы убедиться, что страница работает, откройте [http://localhost:8080/desktop.bundles/hello/hello.html](http://localhost:8080/desktop.bundles/hello/hello.html).
-## Создание блока
-
-На уровне `desktop.blocks` создаем директорию блока **hello**. По умолчанию блок будет представлен набором файлов для всех технологий реализации (`CSS/STYL`, `JS`, `BEMHTML`).
-
- bem create -l desktop.blocks -b hello
-
-* `-l desktop.blocks` –– указывает на уровень переопределения `desktop.blocks`;
-* `-b hello` –– задает имя директории блока, в нашем случае `hello`.
-
-Другой способ –– создание блока вручную. Для этого на уровне `desktop.blocks` создадим папку **hello** и разместим в ней необходимые для проекта файлы технологий реализации блока.
-
-
-
-### Создание блока с файлом определенной технологии
+### 2. Создайте блок
-Блок можно создавать с файлом определенной технологии. Более подробную информацию об этом можно найти в командах [bem-tools](http://ru.bem.info/tools/bem/bem-tools/commands/#Создание-блока-в-определённой-технологии).
+1. Создайте вручную директорию блока **hello** на уровне `desktop.blocks`.
+2. Разместите в ней необходимые для проекта [файлы технологий реализации блока](https://ru.bem.info/method/filesystem/) (`CSS`, `JS`, `BEMHTML`).
-## Переопределение блока `hello`
-Чтобы наш проект заработал должным образом, нужно переопределить файлы технологий реализации.
+### 3. Реализуйте блок `hello`
-### Реализация блока в технологии JS
-
-В файле `desktop.blocks/hello/hello.js` описываем реакцию блока на выполнение действия, в нашем случае нажатие кнопки, с помощью специального свойства `onSetMode`. При нажатии кнопки в приветствие будет автоматически подставляться имя пользователя, введенное в поле **input**.
-
-```
-onSetMod: {
- 'js': {
- 'inited': function() {
- this._input = this.findBlockInside('input');
- this._button = this.findBlockInside('button');
-
- this._button.on('click', function() {
- this.elem('greeting').text('Hello, ' + this._input.getVal() + '!');
- }, this);
- }
- }
-}
-
-```
-Данный JavaScript заворачиваем в [модульную систему YModules](http://ru.bem.info/tools/bem/modules/):
-
-```
-modules.define(
- 'hello',
- ['i-bem__dom'],
- function(provide, BEMDOM) {
- provide(BEMDOM.decl('hello', {
- onSetMod: {
- 'js': {
- 'inited': function() {
- this._input = this.findBlockInside('input');
- this._button = this.findBlockInside('button');
-
- this._button.on('click', function() {
- this.elem('greeting').text('Hello, ' + this._input.getVal() + '!');
- }, this);
- }
- }
- }
- }));
- });
-```
+#### 3.1 Реализуйте блок в технологии JavaScript
+
+1. В файле `desktop.blocks/hello/hello.js` опишите реакцию блока на выполнение действий пользователем с помощью специального свойства `onSetMode`. При нажатии кнопки в текст приветствия будет подставляться имя пользователя, введенное в поле **input**.
+JavaScript-код написан с использованием декларативного JavaScript-фреймворка – [i-bem.js](https://ru.bem.info/technology/i-bem/).
+
+ ```js
+ onSetMod: {
+ 'js': {
+ 'inited': function() {
+ this._input = this.findBlockInside('input');
+
+ this.bindTo('submit', function(e) {
+ e.preventDefault();
+ this.elem('greeting').text('Привет, ' + this._input.getVal() + '!');
+ });
+ }
+ }
+ }
+
+ ```
+
+2. Данный JavaScript-код оберните в модульную систему [YModules](https://ru.bem.info/tools/bem/modules/):
+
+ ```js
+ modules.define(
+ 'hello', // имя блока
+ ['i-bem__dom'], // подключение зависимости
+ function(provide, BEMDOM) { // функция, в которую передаем имена используемых модулей
+ provide(BEMDOM.decl('hello', { // декларация блока
+ onSetMod: { // конструктор для описания реакции на события
+ 'js': {
+ 'inited': function() {
+ this._input = this.findBlockInside('input');
+
+ this.bindTo('submit', function(e) { // событие, на которое будет реакция
+ e.preventDefault(); // предотвращение работы события по умолчанию (отправка данных формы на сервер с перезагрузкой страницы)
+ this.elem('greeting').text('Привет, ' + this._input.getVal() + '!');
+ });
+ }
+ }
+ }
+ }));
+ });
+ ```
-### Реализация блока в технологии BEMHTML
+#### 3.2 Реализуйте блок в технологии BEMHTML
-Для того, чтобы наш JavaScript применился пишем BEMHTML-шаблон, в котором указываем, что наш блок **hello** имеет JavaScript-реализацию:
+1. Напишите BEMHTML-шаблон, в котором укажите, что блок **hello** имеет JavaScript-реализацию.
+2. Оберните блок `hello` в форму, добавив моду `tag`.
-```
-block hello, js: true
+```js
+block('hello')(
+ js()(true),
+ tag()('form')
+);
```
-### Реализация блока в технологии CSS
+#### 3.3 Реализацуйте блок в технологии CSS
-Для блока **hello** создаем свои CSS-правила. К примеру, такие:
+Для блока `hello` создайте свои CSS-правила. Например, такие:
-```
+```js
.hello
- color: green
-```
-
-
-## Сборка проекта
+{
+ color: green;
+ padding: 10%;
+}
-При обновлении страницы сервер пересобирал только ту часть проекта, которую затронули наши изменения. Для сборки всего проекта целиком воспользуемся командой `ENB`:
+.hello__greeting
+{
+ margin-bottom: 12px;
+}
- $ node_modules/.bin/enb make
+.hello__input
+{
+ margin-right: 12px;
+}
+```
+
-# Результат
+## Результат
-Обновляем страницу в браузере с адресом
+Чтобы увидеть итог проделанной работы обновите страницу:
http://localhost:8080/desktop.bundles/hello/hello.html
-и видим страницу приветствия:
-
-*скрин*
-
-Заполняем поле ввода любым именем, например, Вася, нажимаем кнопку и получаем результат:
-
-*скрин*
+Поскольку проект состоял всего из одной страницы, то в полной сборке не было необходимости. О том, как написать более сложный проект описано в статье [Создаем свой проект на БЭМ](http://ru.bem.info/tutorials/start-with-project-stub/).
From 3cca8ce419d706b834d207d88c06ef00546210c5 Mon Sep 17 00:00:00 2001
From: 4exova <4exova@yandex-team.ru>
Date: Tue, 30 Dec 2014 16:41:32 +0300
Subject: [PATCH 02/11] fix typo
---
QuickStart.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/QuickStart.md b/QuickStart.md
index f5a1a54..63244c5 100644
--- a/QuickStart.md
+++ b/QuickStart.md
@@ -185,7 +185,7 @@ block('hello')(
-#### 3.3 Реализацуйте блок в технологии CSS
+#### 3.3 Реализуйте блок в технологии CSS
Для блока `hello` создайте свои CSS-правила. Например, такие:
From 535785849c4c23c7ac72faa167432090d770140f Mon Sep 17 00:00:00 2001
From: 4exova <4exova@yandex-team.ru>
Date: Mon, 12 Jan 2015 10:26:08 +0300
Subject: [PATCH 03/11] doc update
---
QuickStart.md | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/QuickStart.md b/QuickStart.md
index 63244c5..14053c9 100644
--- a/QuickStart.md
+++ b/QuickStart.md
@@ -6,7 +6,7 @@
Страница приветствия пользователя, содержащая поле ввода, кнопку и текст приветствия. При обновлении страницы (кнопка **Нажать**) текст дополняется значением, введенным в поле **Имя пользователя**.
-
+
## С чего начать
@@ -173,7 +173,7 @@ JavaScript-код написан с использованием деклара
#### 3.2 Реализуйте блок в технологии BEMHTML
-1. Напишите BEMHTML-шаблон, в котором укажите, что блок **hello** имеет JavaScript-реализацию.
+1. Напишите [BEMHTML-шаблон](https://ru.bem.info/technology/bemhtml/current/reference/), в котором укажите, что блок **hello** имеет JavaScript-реализацию.
2. Оберните блок `hello` в форму, добавив моду `tag`.
```js
@@ -214,4 +214,4 @@ block('hello')(
http://localhost:8080/desktop.bundles/hello/hello.html
-Поскольку проект состоял всего из одной страницы, то в полной сборке не было необходимости. О том, как написать более сложный проект описано в статье [Создаем свой проект на БЭМ](http://ru.bem.info/tutorials/start-with-project-stub/).
+Поскольку проект состоял всего из одной страницы, то в полной сборке не было необходимости. О том, как написать более сложный проект читайте в статье [Создаем свой проект на БЭМ](http://ru.bem.info/tutorials/start-with-project-stub/).
From a7d9911df73878025996e29d7d56679a008ea0da Mon Sep 17 00:00:00 2001
From: 4exova <4exova@yandex-team.ru>
Date: Tue, 13 Jan 2015 10:45:32 +0300
Subject: [PATCH 04/11] doc update
---
QuickStart.md | 252 +++++++++++++++++++++++++++++---------------------
1 file changed, 145 insertions(+), 107 deletions(-)
diff --git a/QuickStart.md b/QuickStart.md
index 14053c9..3edf5a6 100644
--- a/QuickStart.md
+++ b/QuickStart.md
@@ -4,7 +4,7 @@
## Что должно получиться
-Страница приветствия пользователя, содержащая поле ввода, кнопку и текст приветствия. При обновлении страницы (кнопка **Нажать**) текст дополняется значением, введенным в поле **Имя пользователя**.
+Страница приветствия пользователя, содержащая поле ввода, кнопку и текст. При нажатии на кнопку страница обновляется и текст дополняется значением, введенным в поле.
@@ -12,44 +12,44 @@
### Минимальные требования
-Установленная платформа [Node.js](http://nodejs.org).
+Установленная платформа [Node.js 0.10](http://nodejs.org).
### Локальная копия и настройка окружения
-Для создания БЭМ-проекта потребуется [шаблонный репозиторий](https://github.com/bem/project-stub), содержащий необходимый минимум конфигурационных файлов и папок.
+Для быстрого и простого создания БЭМ-проекта потребуется [шаблонный репозиторий](https://github.com/bem/project-stub), содержащий необходимый минимум конфигурационных файлов и папок.
-1. Сделайте локальную копию `project-stub`.
+1. Сделайте локальную копию `project-stub`.
- **NB** В данном документе описана процедура установки для ревизии [13ae0e18ef8f48bc552b4944f7e5971c5b5f4768](https://github.com/bem/project-stub/ commit/13ae0e18ef8f48bc552b4944f7e5971c5b5f4768). Процесс установки последующих версий может отличаться.
+ **NB** В данном документе описана процедура установки для ревизии [13ae0e18ef8f48bc552b4944f7e5971c5b5f4768](https://github.com/bem/project-stub/ commit/13ae0e18ef8f48bc552b4944f7e5971c5b5f4768). Процесс установки последующих версий может отличаться.
- ```bash
- git clone https://github.com/bem/project-stub.git start-project
- cd start-project
- git checkout 13ae0e18ef8f48bc552b4944f7e5971c5b5f4768
- npm install
- ```
+ ```bash
+ git clone https://github.com/bem/project-stub.git start-project
+ cd start-project
+ git checkout 13ae0e18ef8f48bc552b4944f7e5971c5b5f4768
+ npm install
+ ```
-2. Запустите сервер с помощью [ENB](https://ru.bem.info/tools/bem/enb-bem-techs/):
+2. Запустите сервер с помощью [ENB](https://ru.bem.info/tools/bem/enb-bem-techs/):
- ```bash
- node_modules/.bin/npm start
- ```
+ ```bash
+ node_modules/.bin/npm start
+ ```
-3. Проверьте результат по ссылке [http://localhost:8080/desktop.bundles/index/index.html](http://localhost:8080/desktop.bundles/index/index.html).
+3. Проверьте результат по ссылке [http://localhost:8080/desktop.bundles/index/index.html](http://localhost:8080/desktop.bundles/index/index.html).
- Должна открыться следующая страница:
+ Должна открыться страница с примерами блоков библиотеки:
- 
+ 
## Пошаговая инструкция по созданию проекта
-1. [Создайте страницу](#page_creation)
- 1.1 [Опишите страницу в BEMJSON-файле](#BEMJSON_declaration)
-2. [Создайте блок](#block_creation)
-3. [Реализуйте блок hello](#block_hello_modification)
- 3.1 [В технологии JavaScript](#JS_modification)
- 3.2 [В технологии BEMHTML](#BEMHTML_modification)
- 3.3 [В технологии CSS](#CSS_modification)
+1. [Создайте страницу](#page_creation)
+ 1.1 [Опишите страницу в BEMJSON-файле](#BEMJSON_declaration)
+2. [Создайте блок](#block_creation)
+3. [Реализуйте блок hello](#block_hello_modification)
+ 3.1 [В технологии JavaScript](#JS_modification)
+ 3.2 [В технологии BEMHTML](#BEMHTML_modification)
+ 3.3 [В технологии CSS](#CSS_modification)
@@ -57,7 +57,7 @@
Исходники страниц размещаются в каталоге `desktop.bundles`. Изначально в проекте присутствует главная страница `index.html` с примерами блоков библиотеки [bem-components](http://ru.bem.info/libs/bem-components/).
-Создайте новую страницу. Для этого в каталоге `desktop.bundles` разместите папку с именем `hello` и добавьте в нее файл `hello.bemjson.js`.
+Для начала работы с собственным проектом создайте новую страницу. Разместите в каталоге `desktop.bundles` папку с именем `hello` и добавьте в нее файл `hello.bemjson.js`.
@@ -66,57 +66,81 @@
[BEMJSON-файл](https://ru.bem.info/technology/bemjson/) – это структура страницы, описанная в терминах блоков, элементов и модификаторов.
-1. Добавьте блок **hello** в файл `desktop.bundles/hello/hello.bemjson.js`.
+1. Добавьте описание блока **hello** в файл `desktop.bundles/hello/hello.bemjson.js`.
+ Блок **hello** - это сущность, которая содержит в себе все необходимые для проекта элементы.
-2. Поместите элемент **greeting** с текстом приветствия пользователя в блок **hello**.
+ ```js
+ { block: 'hello' }
+ ```
-3. Возьмите готовые реализации блоков **input** и **button** из библиотеки `bem-components` и добавьте их в элемент **greeting**.
+2. Поместите элемент **greeting** с текстом приветствия пользователя (поле **content**) в блок **hello**.
+ Элемент **greeting** - это подсущность, в которую вкладывается фраза приветствия и готовые реализации блоков.
-```js
-({
- block: 'page',
- title: 'hello',
- head: [
- { elem: 'css', url: '_hello.css' }
- ],
- scripts: [{ elem: 'js', url: '_hello.js' }],
- mods: { theme: 'islands' },
+ ```js
content: [
- {
- block: 'hello',
- content: [
- {
- elem: 'greeting',
- content: 'Привет, %пользователь%!'
- },
- {
- block: 'input',
- mods: { theme: 'islands', size: 'm' },
- mix: { block: 'hello', elem: 'input' }, // подмешиваем элемент для добавления CSS-правил
- name: 'name',
- placeholder: 'Имя пользователя'
- },
- {
- block : 'button',
- mods : { theme : 'islands', size : 'm', type : 'submit' },
- text : 'Нажать'
- }
- ]
- }
- ]
-})
-```
+ {
+ block: 'hello',
+ content: [
+ {
+ elem: 'greeting',
+ content: 'Привет, %пользователь%!'
+ }
+ ]
+ }
+ ]
+ ```
+
+3. Чтобы создать поле ввода и кнопку возьмите готовые реализации блоков **input** и **button** из библиотеки `bem-components` и добавьте их в элемент **greeting**.
+Так будет выглядеть полный код страницы `desktop.bundles/hello/hello.bemjson.js`:
+
+ ```js
+ ({
+ block: 'page',
+ title: 'hello',
+ head: [
+ { elem: 'css', url: '_hello.css' }
+ ],
+ scripts: [{ elem: 'js', url: '_hello.js' }],
+ mods: { theme: 'islands' },
+ content: [
+ {
+ block: 'hello',
+ content: [
+ {
+ elem: 'greeting',
+ content: 'Привет, %пользователь%!'
+ },
+ {
+ block: 'input',
+ mods: { theme: 'islands', size: 'm' },
+ name: 'name',
+ placeholder: 'Имя пользователя'
+ },
+ {
+ block : 'button',
+ mods : { theme : 'islands', size : 'm', type : 'submit' },
+ text : 'Нажать'
+ }
+ ]
+ }
+ ]
+ })
+ ```
+Чтобы убедиться, что страница отображает все необходимые элементы, откройте [http://localhost:8080/desktop.bundles/hello/hello.html](http://localhost:8080/desktop.bundles/hello/hello.html).
Если вы хотите внести какие-либо изменения в существующие блоки, это можно сделать на своем [уровне переопределения](https://ru.bem.info/tools/bem/bem-tools/levels/).
-Чтобы убедиться, что страница работает, откройте [http://localhost:8080/desktop.bundles/hello/hello.html](http://localhost:8080/desktop.bundles/hello/hello.html).
-
### 2. Создайте блок
+Чтобы элементы на странице работали должным образом необходимо прописать дополнительную функциональность блока **hello** на своем уровне переопределения.
+
1. Создайте вручную директорию блока **hello** на уровне `desktop.blocks`.
-2. Разместите в ней необходимые для проекта [файлы технологий реализации блока](https://ru.bem.info/method/filesystem/) (`CSS`, `JS`, `BEMHTML`).
+2. Разместите в ней необходимые для проекта [файлы технологий реализации блока](https://ru.bem.info/method/filesystem/) (`CSS`, `JS`, `BEMHTML`). Файлы и директория блока должны иметь одинаковое название.
+
+ **hello.js**, **hello.bemhtml** описывают динамическую функциональность страницы.
+ **hello.css** изменяет внешний вид элементов на странице.
@@ -129,51 +153,53 @@
1. В файле `desktop.blocks/hello/hello.js` опишите реакцию блока на выполнение действий пользователем с помощью специального свойства `onSetMode`. При нажатии кнопки в текст приветствия будет подставляться имя пользователя, введенное в поле **input**.
JavaScript-код написан с использованием декларативного JavaScript-фреймворка – [i-bem.js](https://ru.bem.info/technology/i-bem/).
- ```js
- onSetMod: {
- 'js': {
- 'inited': function() {
- this._input = this.findBlockInside('input');
-
- this.bindTo('submit', function(e) {
- e.preventDefault();
- this.elem('greeting').text('Привет, ' + this._input.getVal() + '!');
- });
- }
- }
- }
-
- ```
-
-2. Данный JavaScript-код оберните в модульную систему [YModules](https://ru.bem.info/tools/bem/modules/):
-
- ```js
- modules.define(
- 'hello', // имя блока
- ['i-bem__dom'], // подключение зависимости
- function(provide, BEMDOM) { // функция, в которую передаем имена используемых модулей
- provide(BEMDOM.decl('hello', { // декларация блока
- onSetMod: { // конструктор для описания реакции на события
- 'js': {
- 'inited': function() {
- this._input = this.findBlockInside('input');
-
- this.bindTo('submit', function(e) { // событие, на которое будет реакция
- e.preventDefault(); // предотвращение работы события по умолчанию (отправка данных формы на сервер с перезагрузкой страницы)
- this.elem('greeting').text('Привет, ' + this._input.getVal() + '!');
- });
- }
- }
- }
- }));
- });
- ```
+ ```js
+ onSetMod: {
+ 'js': {
+ 'inited': function() {
+ this._input = this.findBlockInside('input');
+
+ this.bindTo('submit', function(e) {
+ e.preventDefault();
+ this.elem('greeting').text('Привет, ' + this._input.getVal() + '!');
+ });
+ }
+ }
+ }
+
+ ```
+
+2. Данный JavaScript-код представьте с помощью модульной системы [YModules](https://ru.bem.info/tools/bem/modules/):
+
+ ```js
+ modules.define(
+ 'hello', // имя блока
+ ['i-bem__dom'], // подключение зависимости
+ function(provide, BEMDOM) { // функция, в которую передаются имена используемых модулей
+ provide(BEMDOM.decl('hello', { // декларация блока
+ onSetMod: { // конструктор для описания реакции на события
+ 'js': {
+ 'inited': function() {
+ this._input = this.findBlockInside('input');
+
+ this.bindTo('submit', function(e) { // событие, на которое будет реакция
+ e.preventDefault(); // предотвращение работы события по умолчанию (отправка данных формы на сервер с перезагрузкой страницы)
+ this.elem('greeting').text('Привет, ' + this._input.getVal() + '!');
+ });
+ }
+ }
+ }
+ }));
+ });
+ ```
#### 3.2 Реализуйте блок в технологии BEMHTML
-1. Напишите [BEMHTML-шаблон](https://ru.bem.info/technology/bemhtml/current/reference/), в котором укажите, что блок **hello** имеет JavaScript-реализацию.
+[BEMHTML](http://ru.bem.info/technology/bemhtml/current/rationale/) - технология, которая преобразует входные данные из BEMJSON-файла в HTML.
+
+1. Напишите [BEMHTML-шаблон](http://ru.bem.info/technology/bemhtml/current/reference/), в котором укажите, что блок **hello** имеет JavaScript-реализацию.
2. Оберните блок `hello` в форму, добавив моду `tag`.
```js
@@ -185,7 +211,7 @@ block('hello')(
-#### 3.3 Реализуйте блок в технологии CSS
+#### 3.3 Реализауйте блок в технологии CSS
Для блока `hello` создайте свои CSS-правила. Например, такие:
@@ -206,6 +232,18 @@ block('hello')(
margin-right: 12px;
}
```
+Чтобы изменить положение блока на странице и при этом оставить его в первоначальном виде в библиотеке, подмешайте элемент с помощью метода микс во входных данных (BEMJSON).
+
+```js
+{
+ block: 'input',
+ mods: { theme: 'islands', size: 'm' },
+ mix: { block: 'hello', elem: 'input' }, // подмешиваем элемент для добавления CSS-правил
+ name: 'name',
+ placeholder: 'Имя пользователя'
+}
+```
+
## Результат
@@ -214,4 +252,4 @@ block('hello')(
http://localhost:8080/desktop.bundles/hello/hello.html
-Поскольку проект состоял всего из одной страницы, то в полной сборке не было необходимости. О том, как написать более сложный проект читайте в статье [Создаем свой проект на БЭМ](http://ru.bem.info/tutorials/start-with-project-stub/).
+Поскольку проект состоял всего из одной страницы, то в полной сборке не было необходимости. О том, как написать более сложный проект описано в статье [Создаем свой проект на БЭМ](http://ru.bem.info/tutorials/start-with-project-stub/).
From 4fb8f981314defe00a2799370b7d8f24a6c9a556 Mon Sep 17 00:00:00 2001
From: 4exova <4exova@yandex-team.ru>
Date: Tue, 13 Jan 2015 10:48:12 +0300
Subject: [PATCH 05/11] doc update
---
QuickStart.md | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/QuickStart.md b/QuickStart.md
index 3edf5a6..f89f4d6 100644
--- a/QuickStart.md
+++ b/QuickStart.md
@@ -43,13 +43,13 @@
## Пошаговая инструкция по созданию проекта
-1. [Создайте страницу](#page_creation)
- 1.1 [Опишите страницу в BEMJSON-файле](#BEMJSON_declaration)
+1. [Создайте страницу](#page_creation)
+ 1.1 [Опишите страницу в BEMJSON-файле](#BEMJSON_declaration)
2. [Создайте блок](#block_creation)
-3. [Реализуйте блок hello](#block_hello_modification)
- 3.1 [В технологии JavaScript](#JS_modification)
- 3.2 [В технологии BEMHTML](#BEMHTML_modification)
- 3.3 [В технологии CSS](#CSS_modification)
+3. [Реализуйте блок hello](#block_hello_modification)
+ 3.1 [В технологии JavaScript](#JS_modification)
+ 3.2 [В технологии BEMHTML](#BEMHTML_modification)
+ 3.3 [В технологии CSS](#CSS_modification)
From b7c20c64467ee6576be7310972eb5b06303150af Mon Sep 17 00:00:00 2001
From: 4exova <4exova@yandex-team.ru>
Date: Tue, 13 Jan 2015 10:49:54 +0300
Subject: [PATCH 06/11] doc update
---
QuickStart.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/QuickStart.md b/QuickStart.md
index f89f4d6..31dfad6 100644
--- a/QuickStart.md
+++ b/QuickStart.md
@@ -90,8 +90,8 @@
]
```
-3. Чтобы создать поле ввода и кнопку возьмите готовые реализации блоков **input** и **button** из библиотеки `bem-components` и добавьте их в элемент **greeting**.
-Так будет выглядеть полный код страницы `desktop.bundles/hello/hello.bemjson.js`:
+3. Чтобы создать поле ввода и кнопку возьмите готовые реализации блоков **input** и **button** из библиотеки `bem-components` и добавьте их в элемент **greeting**.
+ Так будет выглядеть полный код страницы `desktop.bundles/hello/hello.bemjson.js`:
```js
({
From 58d5ba69264668532dc21e50fa550e4af3732a29 Mon Sep 17 00:00:00 2001
From: 4exova <4exova@yandex-team.ru>
Date: Tue, 13 Jan 2015 10:55:50 +0300
Subject: [PATCH 07/11] fix typo
---
QuickStart.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/QuickStart.md b/QuickStart.md
index 31dfad6..ed7b82f 100644
--- a/QuickStart.md
+++ b/QuickStart.md
@@ -211,7 +211,7 @@ block('hello')(
-#### 3.3 Реализауйте блок в технологии CSS
+#### 3.3 Реализуйте блок в технологии CSS
Для блока `hello` создайте свои CSS-правила. Например, такие:
From 2e4d88413f583cebfd89d76e9f36a4471a9f71b7 Mon Sep 17 00:00:00 2001
From: 4exova <4exova@yandex-team.ru>
Date: Tue, 13 Jan 2015 11:52:41 +0300
Subject: [PATCH 08/11] doc update
---
QuickStart.md | 41 ++++++++++++++++++++++++++++-------------
1 file changed, 28 insertions(+), 13 deletions(-)
diff --git a/QuickStart.md b/QuickStart.md
index ed7b82f..6fd5571 100644
--- a/QuickStart.md
+++ b/QuickStart.md
@@ -67,14 +67,27 @@
[BEMJSON-файл](https://ru.bem.info/technology/bemjson/) – это структура страницы, описанная в терминах блоков, элементов и модификаторов.
1. Добавьте описание блока **hello** в файл `desktop.bundles/hello/hello.bemjson.js`.
- Блок **hello** - это сущность, которая содержит в себе все необходимые для проекта элементы.
+ Блок **hello** – это сущность, которая содержит в себе все необходимые для проекта элементы.
```js
- { block: 'hello' }
+ {
+ block: 'page',
+ title: 'hello',
+ head: [
+ { elem: 'css', url: '_hello.css' }
+ ],
+ scripts: [{ elem: 'js', url: '_hello.js' }],
+ mods: { theme: 'islands' }
+ content: [
+ {
+ block: 'hello'
+ }
+ ]
+ }
```
2. Поместите элемент **greeting** с текстом приветствия пользователя (поле **content**) в блок **hello**.
- Элемент **greeting** - это подсущность, в которую вкладывается фраза приветствия и готовые реализации блоков.
+ Элемент **greeting** – это подсущность, в которую вкладывается фраза приветствия и готовые реализации блоков.
```js
content: [
@@ -91,7 +104,6 @@
```
3. Чтобы создать поле ввода и кнопку возьмите готовые реализации блоков **input** и **button** из библиотеки `bem-components` и добавьте их в элемент **greeting**.
- Так будет выглядеть полный код страницы `desktop.bundles/hello/hello.bemjson.js`:
```js
({
@@ -126,7 +138,8 @@
]
})
```
-Чтобы убедиться, что страница отображает все необходимые элементы, откройте [http://localhost:8080/desktop.bundles/hello/hello.html](http://localhost:8080/desktop.bundles/hello/hello.html).
+
+Чтобы убедиться, что страница отображает все необходимые объекты, откройте [http://localhost:8080/desktop.bundles/hello/hello.html](http://localhost:8080/desktop.bundles/hello/hello.html).
Если вы хотите внести какие-либо изменения в существующие блоки, это можно сделать на своем [уровне переопределения](https://ru.bem.info/tools/bem/bem-tools/levels/).
@@ -137,10 +150,11 @@
Чтобы элементы на странице работали должным образом необходимо прописать дополнительную функциональность блока **hello** на своем уровне переопределения.
1. Создайте вручную директорию блока **hello** на уровне `desktop.blocks`.
-2. Разместите в ней необходимые для проекта [файлы технологий реализации блока](https://ru.bem.info/method/filesystem/) (`CSS`, `JS`, `BEMHTML`). Файлы и директория блока должны иметь одинаковое название.
+2. Разместите в ней необходимые для проекта [файлы технологий реализации блока](https://ru.bem.info/method/filesystem/) (`CSS`, `JS`, `BEMHTML`). Название директории блока и вложенных в неё файлов должны совпадать с именем блока, которое прописано в BEMJSON-файле.
- **hello.js**, **hello.bemhtml** описывают динамическую функциональность страницы.
- **hello.css** изменяет внешний вид элементов на странице.
+ **hello.js** - описывает динамическую функциональность страницы
+ **hello.bemhtml** - шаблоны для генерации HTML-представления блока
+ **hello.css** - изменяет внешний вид объектов на странице
@@ -150,8 +164,8 @@
#### 3.1 Реализуйте блок в технологии JavaScript
-1. В файле `desktop.blocks/hello/hello.js` опишите реакцию блока на выполнение действий пользователем с помощью специального свойства `onSetMode`. При нажатии кнопки в текст приветствия будет подставляться имя пользователя, введенное в поле **input**.
-JavaScript-код написан с использованием декларативного JavaScript-фреймворка – [i-bem.js](https://ru.bem.info/technology/i-bem/).
+1. В файле `desktop.blocks/hello/hello.js` опишите реакцию блока на выполнение действий пользователем с помощью специального свойства `onSetMode`. При нажатии кнопки в текст приветствия будет подставляться имя пользователя, введенное в поле **input**.
+ JavaScript-код написан с использованием декларативного JavaScript-фреймворка – [i-bem.js](https://ru.bem.info/technology/i-bem/).
```js
onSetMod: {
@@ -169,7 +183,7 @@ JavaScript-код написан с использованием деклара
```
-2. Данный JavaScript-код представьте с помощью модульной системы [YModules](https://ru.bem.info/tools/bem/modules/):
+2. Используйте модульную систему [YModules](https://ru.bem.info/tools/bem/modules/), чтобы представить данный JavaScript-код:
```js
modules.define(
@@ -197,7 +211,7 @@ JavaScript-код написан с использованием деклара
#### 3.2 Реализуйте блок в технологии BEMHTML
-[BEMHTML](http://ru.bem.info/technology/bemhtml/current/rationale/) - технология, которая преобразует входные данные из BEMJSON-файла в HTML.
+[BEMHTML](http://ru.bem.info/technology/bemhtml/current/rationale/) – технология, которая преобразует входные данные из BEMJSON-файла в HTML.
1. Напишите [BEMHTML-шаблон](http://ru.bem.info/technology/bemhtml/current/reference/), в котором укажите, что блок **hello** имеет JavaScript-реализацию.
2. Оберните блок `hello` в форму, добавив моду `tag`.
@@ -232,7 +246,7 @@ block('hello')(
margin-right: 12px;
}
```
-Чтобы изменить положение блока на странице и при этом оставить его в первоначальном виде в библиотеке, подмешайте элемент с помощью метода микс во входных данных (BEMJSON).
+Чтобы изменить положение блока на странице и при этом оставить его в первоначальном виде в библиотеке, подмешайте элемент с помощью метода mix во входных данных (BEMJSON).
```js
{
@@ -243,6 +257,7 @@ block('hello')(
placeholder: 'Имя пользователя'
}
```
+[Полный код BEMJSON-файла](https://gist.github.com/4exova/981a36cedceffa472742).
From be3b097283a0e86b9a6428623ad6a65c1aa73905 Mon Sep 17 00:00:00 2001
From: 4exova <4exova@yandex-team.ru>
Date: Tue, 13 Jan 2015 14:50:32 +0300
Subject: [PATCH 09/11] doc update
---
QuickStart.md | 2 ++
1 file changed, 2 insertions(+)
diff --git a/QuickStart.md b/QuickStart.md
index 6fd5571..5e65d80 100644
--- a/QuickStart.md
+++ b/QuickStart.md
@@ -160,6 +160,8 @@
### 3. Реализуйте блок `hello`
+Для представления блока в терминах БЭМ необходимо описать его в файлах технологий реализации.
+
#### 3.1 Реализуйте блок в технологии JavaScript
From 0a4dcb280ab99ecd208e7f9542f7ed3b040f657f Mon Sep 17 00:00:00 2001
From: 4exova <4exova@yandex-team.ru>
Date: Tue, 20 Jan 2015 17:15:17 +0300
Subject: [PATCH 10/11] doc update
---
QuickStart.en.md | 274 +++++++++++++++++++++++++++++++++++++++++++++++
QuickStart.md | 72 +++++++------
2 files changed, 312 insertions(+), 34 deletions(-)
create mode 100644 QuickStart.en.md
diff --git a/QuickStart.en.md b/QuickStart.en.md
new file mode 100644
index 0000000..b4c8595
--- /dev/null
+++ b/QuickStart.en.md
@@ -0,0 +1,274 @@
+## Quick start for static page creation with BEM
+
+This article describes implementation example of static page using [BEM methodology](https://en.bem.info/method/).
+
+## Expected outcome
+
+User greeting page, that contains an input field, a button and a text. The page refreshes after button clicking and text is filled up with the value entered in the input field.
+
+
+
+## Starting with
+
+### Minimal requirements
+
+Installed platform [Node.js 0.10](http://nodejs.org).
+
+### Local copy and environment setting
+
+For quick and easy creation of BEM project use [template repository](https://github.com/bem/project-stub). It contains the minimal configuration files and folders.
+
+1. Make local copy of `project-stub`.
+
+ **NB** This document describes an installation procedure for revision [13ae0e18ef8f48bc552b4944f7e5971c5b5f4768](https://github.com/bem/project-stub/ commit/13ae0e18ef8f48bc552b4944f7e5971c5b5f4768). The installation procedure of next versions may differ.
+
+ ```bash
+ git clone https://github.com/bem/project-stub.git start-project
+ cd start-project
+ git checkout 13ae0e18ef8f48bc552b4944f7e5971c5b5f4768
+ npm install
+ ```
+
+2. Run the server with help of [ENB](https://ru.bem.info/tools/bem/enb-bem-techs/)(for the moment this article is available only in russian language).
+
+ ```bash
+ node_modules/.bin/npm start
+ ```
+
+3. Check the result on [http://localhost:8080/desktop.bundles/index/index.html](http://localhost:8080/desktop.bundles/index/index.html).
+
+ Page with library blocks implementations should open:
+
+ 
+
+## Step-by-step instruction for project creation
+
+1. [Create page](#page_creation)
+ 1.1 [Describe page in BEMJSON file](#BEMJSON_declaration)
+2. [Create block](#block_creation)
+3. [Implement block hello](#block_hello_modification)
+ 3.1 [In JavaScript technology](#JS_modification)
+ 3.2 [In BEMHTML technology](#BEMHTML_modification)
+ 3.3 [In CSS technology](#CSS_modification)
+
+When all steps have been completed you can watch the [result](#result).
+
+
+
+### 1. Create page
+
+Pages source code are stored in the `start-project/desktop.bundles` directory. The main page `index.html` contains blocks implementations of the [bem-components](https://en.bem.info/libs/bem-components/) library.
+
+Create new page to start your own project. Paste `hello` directory in the `desktop.bundles` and add `hello.bemjson.js` file into it.
+
+
+
+#### 1.1 Describe page in BEMJSON file
+
+A [BEMJSON file](https://en.bem.info/technology/bemjson/) describes a page structure in BEM terms: blocks, elements and modifiers.
+
+1. Add in your project description of block `hello` in the `desktop.bundles/hello/hello.bemjson.js` file.
+ **hello** block is an entity, that contains all necessary elements for the project.
+
+ ```js
+ {
+ block: 'page',
+ title: 'hello',
+ head: [
+ { elem: 'css', url: '_hello.css' }
+ ],
+ scripts: [{ elem: 'js', url: '_hello.js' }],
+ mods: { theme: 'islands' }
+ content: [
+ {
+ block: 'hello'
+ }
+ ]
+ }
+ ```
+
+2. Place `greeting` element with text of user greeting (**content** field) in `hello` block.
+ **greeting** element is a sub-entity, that contains greeting phrase and ready-made blocks implementations.
+
+ ```js
+ content: [
+ {
+ block: 'hello',
+ content: [
+ {
+ elem: 'greeting',
+ content: 'Hello, %user%!'
+ }
+ ]
+ }
+ ]
+ ```
+
+3. To create an input field and a button take provided by the `bem-components` library `input` and `button` blocks and add them to the `greeting` element.
+
+ ```js
+ ({
+ block: 'page',
+ title: 'hello',
+ head: [
+ { elem: 'css', url: '_hello.css' }
+ ],
+ scripts: [{ elem: 'js', url: '_hello.js' }],
+ mods: { theme: 'islands' },
+ content: [
+ {
+ block: 'hello',
+ content: [
+ {
+ elem: 'greeting',
+ content: 'Hello, %user%!'
+ },
+ {
+ block: 'input',
+ mods: { theme: 'islands', size: 'm' },
+ name: 'name',
+ placeholder: 'User name'
+ },
+ {
+ block : 'button',
+ mods : { theme : 'islands', size : 'm', type : 'submit' },
+ text : 'Click'
+ }
+ ]
+ }
+ ]
+ })
+ ```
+
+To consider that page shows all necessary objects, open [http://localhost:8080/desktop.bundles/hello/hello.html](http://localhost:8080/desktop.bundles/hello/hello.html).
+
+You may provide some changes into existing blocks on your [redefinition level](https://en.bem.info/tools/bem/bem-tools/levels/).
+
+
+
+### 2. Create block
+
+To provide appropriate work of all object on the page, it is necessary to specify additional functionality of `hello` block on your redefinition level.
+
+1. Manually create directory of `hello` block on the `desktop.blocks` level.
+2. Place required for the project [block's implementation technology files](https://en.bem.info/method/filesystem/) (`CSS`, `JS`, `BEMHTML`) into **hello** directory.
+ Block directory name and its nested files should coincide with block name specified in BEMJSON file.
+
+ * `hello.js` – describes dynamic page functionality;
+ * `hello.bemhtml` – template for generation of block HTML representation;
+ * `hello.css` – changes objects design on the page.
+
+
+
+### 3. Implement hello block
+
+For block representation in BEM terms it is necessary to describe it in the implementation technology files.
+
+
+
+#### 3.1 Implement block in JavaScript technology
+
+1. Describe a block reaction depending on user action with help of `onSetMod` property in the `desktop.blocks/hello/hello.js` file. After button clicking greeting text will be replaced with the user name entered in the input field.
+JavaScript code is written using the [i-bem.js](https://ru.bem.info/technology/i-bem/) (for the moment this article is available only in russian language) declarative JavaScript framework.
+
+ ```js
+ onSetMod: {
+ 'js': {
+ 'inited': function() {
+ this._input = this.findBlockInside('input');
+
+ this.bindTo('submit', function(e) {
+ e.preventDefault();
+ this.elem('greeting').text('Hello, ' + this._input.getVal() + '!');
+ });
+ }
+ }
+ }
+
+ ```
+
+2. To represent current JavaScript code, use modular system [YModules](https://en.bem.info/tools/bem/modules/).
+
+ ```js
+ modules.define(
+ 'hello', // block name
+ ['i-bem__dom'], // dependence connection
+ function(provide, BEMDOM) { // function to which names of the used modules are transferred
+ provide(BEMDOM.decl('hello', { // block declaration
+ onSetMod: { // constructor for reaction description on event
+ 'js': {
+ 'inited': function() {
+ this._input = this.findBlockInside('input');
+
+ this.bindTo('submit', function(e) { // event on which there will be a reaction
+ e.preventDefault(); // prevention of event work by default (form data sending to the server with page reload)
+ this.elem('greeting').text('Hello, ' + this._input.getVal() + '!');
+ });
+ }
+ }
+ }
+ }));
+ });
+ ```
+
+
+
+#### 3.2 Implement block in BEMHTML technology
+
+[BEMHTML](https://en.bem.info/technology/bemhtml/current/rationale/) – technology that processes BEMJSON declaration to create HTML layout of a web page.
+
+1. Write [BEMHTML tempate](https://en.bem.info/technology/bemhtml/current/reference/) and specify that `hello` block has JavaScript implementation.
+2. Implement `hello` block with form, adding `tag` mode.
+
+```js
+block('hello')(
+ js()(true),
+ tag()('form')
+);
+```
+
+
+
+#### 3.3 Implement block in CSS technology
+
+Create your own CSS rules for `hello` block. For example:
+
+```js
+.hello
+{
+ color: green;
+ padding: 10%;
+}
+
+.hello__greeting
+{
+ margin-bottom: 12px;
+}
+
+.hello__input
+{
+ margin-right: 12px;
+}
+```
+To change the position of the block on the page and leave it in its original form in the library, mix element using the method `mix` in the input data (BEMJSON).
+
+```js
+{
+ block: 'input',
+ mods: { theme: 'islands', size: 'm' },
+ mix: { block: 'hello', elem: 'input' }, // mix element to add CSS rules
+ name: 'name',
+ placeholder: 'User name'
+}
+```
+[Code sample](https://gist.github.com/4exova/683b6da16aa7aa0399f3) hello.bemjson.js.
+
+
+
+## Result
+
+To see the result of this project, please refresh the page:
+
+ http://localhost:8080/desktop.bundles/hello/hello.html
+
+Since the project consisted only of one page, in full build was no need. How to write a more complex project is described in [Starting your own project](https://en.bem.info/tutorials/start-with-project-stub/) article.
diff --git a/QuickStart.md b/QuickStart.md
index 5e65d80..54c2d7c 100644
--- a/QuickStart.md
+++ b/QuickStart.md
@@ -39,35 +39,39 @@
Должна открыться страница с примерами блоков библиотеки:
- 
+ 
## Пошаговая инструкция по созданию проекта
-1. [Создайте страницу](#page_creation)
- 1.1 [Опишите страницу в BEMJSON-файле](#BEMJSON_declaration)
-2. [Создайте блок](#block_creation)
-3. [Реализуйте блок hello](#block_hello_modification)
+Процедура разработки страницы приветствия состоит из следующих этапов:
+
+1. [Создание страницы](#page_creation)
+ 1.1 [Описание страницы в BEMJSON-файле](#BEMJSON_declaration)
+2. [Создание блока](#block_creation)
+3. [Реализация блока hello](#block_hello_modification)
3.1 [В технологии JavaScript](#JS_modification)
3.2 [В технологии BEMHTML](#BEMHTML_modification)
3.3 [В технологии CSS](#CSS_modification)
+После выполнения всех шагов можно смотреть [результат](#result).
+
-### 1. Создайте страницу
+### 1. Создание страницы
-Исходники страниц размещаются в каталоге `desktop.bundles`. Изначально в проекте присутствует главная страница `index.html` с примерами блоков библиотеки [bem-components](http://ru.bem.info/libs/bem-components/).
+Исходники страниц размещаются в каталоге `start-project/desktop.bundles`. Изначально в проекте присутствует главная страница `index.html` с примерами блоков библиотеки [bem-components](https://ru.bem.info/libs/bem-components/).
-Для начала работы с собственным проектом создайте новую страницу. Разместите в каталоге `desktop.bundles` папку с именем `hello` и добавьте в нее файл `hello.bemjson.js`.
+Для начала работы с собственным проектом создайте новую страницу. Разместите в `desktop.bundles` каталог с именем `hello` и добавьте в него файл `hello.bemjson.js`.
-#### 1.1 Опишите страницу в BEMJSON-файле
+#### 1.1 Описание страницы в BEMJSON-файле
[BEMJSON-файл](https://ru.bem.info/technology/bemjson/) – это структура страницы, описанная в терминах блоков, элементов и модификаторов.
-1. Добавьте описание блока **hello** в файл `desktop.bundles/hello/hello.bemjson.js`.
- Блок **hello** – это сущность, которая содержит в себе все необходимые для проекта элементы.
+1. Добавьте на своем проекте описание блока `hello` в файле `desktop.bundles/hello/hello.bemjson.js`.
+ Блок **hello** – это сущность, которая содержит в себе все необходимые для проекта элементы.
```js
{
@@ -83,11 +87,11 @@
block: 'hello'
}
]
- }
+ }
```
-2. Поместите элемент **greeting** с текстом приветствия пользователя (поле **content**) в блок **hello**.
- Элемент **greeting** – это подсущность, в которую вкладывается фраза приветствия и готовые реализации блоков.
+2. Поместите элемент `greeting` с текстом приветствия пользователя (поле **content**) в блок **hello**.
+ Элемент **greeting** – это подсущность, в которую вкладывается фраза приветствия и готовые реализации блоков.
```js
content: [
@@ -103,7 +107,7 @@
]
```
-3. Чтобы создать поле ввода и кнопку возьмите готовые реализации блоков **input** и **button** из библиотеки `bem-components` и добавьте их в элемент **greeting**.
+3. Чтобы создать поле ввода и кнопку возьмите готовые реализации блоков `input` и `button` из библиотеки `bem-components` и добавьте их в элемент `greeting`.
```js
({
@@ -145,29 +149,29 @@
-### 2. Создайте блок
+### 2. Создание блока
-Чтобы элементы на странице работали должным образом необходимо прописать дополнительную функциональность блока **hello** на своем уровне переопределения.
+Чтобы элементы на странице работали должным образом необходимо прописать дополнительную функциональность блока `hello` на своем уровне переопределения.
-1. Создайте вручную директорию блока **hello** на уровне `desktop.blocks`.
-2. Разместите в ней необходимые для проекта [файлы технологий реализации блока](https://ru.bem.info/method/filesystem/) (`CSS`, `JS`, `BEMHTML`). Название директории блока и вложенных в неё файлов должны совпадать с именем блока, которое прописано в BEMJSON-файле.
+1. Создайте вручную каталог блока `hello` на уровне `desktop.blocks`.
+2. Разместите в нем необходимые для проекта [файлы технологий реализации блока](https://ru.bem.info/method/filesystem/) (`CSS`, `JS`, `BEMHTML`). Название каталога блока и вложенных в него файлов должны совпадать с именем блока, которое прописано в BEMJSON-файле.
- **hello.js** - описывает динамическую функциональность страницы
- **hello.bemhtml** - шаблоны для генерации HTML-представления блока
- **hello.css** - изменяет внешний вид объектов на странице
+ * `hello.js` – описывает динамическую функциональность страниц;
+ * `hello.bemhtml` – шаблоны для генерации HTML-представления блока;
+ * `hello.css` – изменяет внешний вид объектов на странице.
-### 3. Реализуйте блок `hello`
+### 3. Реализация блока hello
Для представления блока в терминах БЭМ необходимо описать его в файлах технологий реализации.
-#### 3.1 Реализуйте блок в технологии JavaScript
+#### 3.1 Реализация блока в технологии JavaScript
-1. В файле `desktop.blocks/hello/hello.js` опишите реакцию блока на выполнение действий пользователем с помощью специального свойства `onSetMode`. При нажатии кнопки в текст приветствия будет подставляться имя пользователя, введенное в поле **input**.
- JavaScript-код написан с использованием декларативного JavaScript-фреймворка – [i-bem.js](https://ru.bem.info/technology/i-bem/).
+1. Опишие в файле `desktop.blocks/hello/hello.js` реакцию блока на действие пользователя с помощью специального свойства `onSetMode`. При нажатии кнопки в текст приветствия будет подставляться имя пользователя, введенное в поле input.
+ JavaScript-код написан с использованием декларативного JavaScript-фреймворка – [i-bem.js](https://ru.bem.info/technology/i-bem/).
```js
onSetMod: {
@@ -211,11 +215,11 @@
-#### 3.2 Реализуйте блок в технологии BEMHTML
+#### 3.2 Реализация блока в технологии BEMHTML
-[BEMHTML](http://ru.bem.info/technology/bemhtml/current/rationale/) – технология, которая преобразует входные данные из BEMJSON-файла в HTML.
+[BEMHTML](https://ru.bem.info/technology/bemhtml/current/rationale/) – технология, которая преобразует входные данные из BEMJSON-файла в HTML.
-1. Напишите [BEMHTML-шаблон](http://ru.bem.info/technology/bemhtml/current/reference/), в котором укажите, что блок **hello** имеет JavaScript-реализацию.
+1. Напишите [BEMHTML-шаблон](https://ru.bem.info/technology/bemhtml/current/reference/) и укажите в нем, что блок `hello` имеет JavaScript-реализацию.
2. Оберните блок `hello` в форму, добавив моду `tag`.
```js
@@ -227,7 +231,7 @@ block('hello')(
-#### 3.3 Реализуйте блок в технологии CSS
+#### 3.3 Реализация блока в технологии CSS
Для блока `hello` создайте свои CSS-правила. Например, такие:
@@ -248,7 +252,7 @@ block('hello')(
margin-right: 12px;
}
```
-Чтобы изменить положение блока на странице и при этом оставить его в первоначальном виде в библиотеке, подмешайте элемент с помощью метода mix во входных данных (BEMJSON).
+Чтобы изменить положение блока на странице и при этом оставить его в первоначальном виде в библиотеке, подмешайте элемент с помощью метода `mix` во входных данных (BEMJSON).
```js
{
@@ -259,9 +263,9 @@ block('hello')(
placeholder: 'Имя пользователя'
}
```
-[Полный код BEMJSON-файла](https://gist.github.com/4exova/981a36cedceffa472742).
+[Полный код](https://gist.github.com/4exova/981a36cedceffa472742) BEMJSON-файла.
-
+
## Результат
@@ -269,4 +273,4 @@ block('hello')(
http://localhost:8080/desktop.bundles/hello/hello.html
-Поскольку проект состоял всего из одной страницы, то в полной сборке не было необходимости. О том, как написать более сложный проект описано в статье [Создаем свой проект на БЭМ](http://ru.bem.info/tutorials/start-with-project-stub/).
+Поскольку проект состоял всего из одной страницы, то необходимость в полной сборке отсутствует. Информация о том, как написать более сложный проект приведена в статье [Создаем свой проект на БЭМ](https://ru.bem.info/tutorials/start-with-project-stub/).
From 248f44b43a713d6481561de3054c81dbe3d32d9c Mon Sep 17 00:00:00 2001
From: 4exova <4exova@yandex-team.ru>
Date: Wed, 4 Feb 2015 11:45:02 +0300
Subject: [PATCH 11/11] RationalForJS added
---
QuickStart.en.md | 119 +++++++++---------
QuickStart.md | 20 +--
RationaleForJS.md | 315 ++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 386 insertions(+), 68 deletions(-)
create mode 100644 RationaleForJS.md
diff --git a/QuickStart.en.md b/QuickStart.en.md
index b4c8595..4075643 100644
--- a/QuickStart.en.md
+++ b/QuickStart.en.md
@@ -1,26 +1,26 @@
## Quick start for static page creation with BEM
-This article describes implementation example of static page using [BEM methodology](https://en.bem.info/method/).
+The article describes step-by-step implementation of a static page using [BEM methodology](https://bem.info/method/).
## Expected outcome
-User greeting page, that contains an input field, a button and a text. The page refreshes after button clicking and text is filled up with the value entered in the input field.
+A page that contains an input field, a button, and a greeting text. A value from the input field will be added to the greeting text when the user clicks the button.
-
+
-## Starting with
+## First steps to start
### Minimal requirements
-Installed platform [Node.js 0.10](http://nodejs.org).
+An installed platform [Node.js 0.10](http://nodejs.org).
-### Local copy and environment setting
+### A local copy and environment setting
-For quick and easy creation of BEM project use [template repository](https://github.com/bem/project-stub). It contains the minimal configuration files and folders.
+A [template repository](https://github.com/bem/project-stub) is the quickest and easiest way to start your BEM project. It contains the minimal configuration files and folders.
1. Make local copy of `project-stub`.
- **NB** This document describes an installation procedure for revision [13ae0e18ef8f48bc552b4944f7e5971c5b5f4768](https://github.com/bem/project-stub/ commit/13ae0e18ef8f48bc552b4944f7e5971c5b5f4768). The installation procedure of next versions may differ.
+ **NB** The document describes an installation procedure based on the revision [13ae0e18ef8f48bc552b4944f7e5971c5b5f4768](https://github.com/bem/project-stub/ commit/13ae0e18ef8f48bc552b4944f7e5971c5b5f4768). The installation procedure of next versions may differ.
```bash
git clone https://github.com/bem/project-stub.git start-project
@@ -29,7 +29,7 @@ For quick and easy creation of BEM project use [template repository](https://git
npm install
```
-2. Run the server with help of [ENB](https://ru.bem.info/tools/bem/enb-bem-techs/)(for the moment this article is available only in russian language).
+2. Run a server with help of [ENB](https://ru.bem.info/tools/bem/enb-bem-techs/)(this article is available only in russian language).
```bash
node_modules/.bin/npm start
@@ -37,38 +37,41 @@ For quick and easy creation of BEM project use [template repository](https://git
3. Check the result on [http://localhost:8080/desktop.bundles/index/index.html](http://localhost:8080/desktop.bundles/index/index.html).
- Page with library blocks implementations should open:
+ A page with library blocks examples should open:
- 
+ 
-## Step-by-step instruction for project creation
+## Step-by-step instruction for the project creation
-1. [Create page](#page_creation)
- 1.1 [Describe page in BEMJSON file](#BEMJSON_declaration)
-2. [Create block](#block_creation)
-3. [Implement block hello](#block_hello_modification)
- 3.1 [In JavaScript technology](#JS_modification)
- 3.2 [In BEMHTML technology](#BEMHTML_modification)
- 3.3 [In CSS technology](#CSS_modification)
+1. [Create a page](#page_creation)
+ 1.1 [Describe the page in BEMJSON file](#BEMJSON_declaration)
+2. [Create a block](#block_creation)
+3. [Implement hello block](#block_hello_modification)
+ 3.1 [Use JavaScript technology](#JS_modification)
+ 3.2 [Use BEMHTML technology](#BEMHTML_modification)
+ 3.3 [Use CSS technology](#CSS_modification)
-When all steps have been completed you can watch the [result](#result).
+When all steps have been completed you can watch the [result](#result).
-### 1. Create page
+### 1. Create a page
-Pages source code are stored in the `start-project/desktop.bundles` directory. The main page `index.html` contains blocks implementations of the [bem-components](https://en.bem.info/libs/bem-components/) library.
+Pages source code are stored in the `start-project/desktop.bundles` directory. The main page `index.html` contains blocks implementations of [bem-components](https://en.bem.info/libs/bem-components/) library.
-Create new page to start your own project. Paste `hello` directory in the `desktop.bundles` and add `hello.bemjson.js` file into it.
+Create a new page to start your own project.
+
+1. Create `hello` directory in the `desktop.bundles`.
+2. Add `hello.bemjson.js` file into `hello` directory.
-#### 1.1 Describe page in BEMJSON file
+#### 1.1 Describe the page in BEMJSON file
A [BEMJSON file](https://en.bem.info/technology/bemjson/) describes a page structure in BEM terms: blocks, elements and modifiers.
-1. Add in your project description of block `hello` in the `desktop.bundles/hello/hello.bemjson.js` file.
- **hello** block is an entity, that contains all necessary elements for the project.
+1. Add a description of `hello` block in the `desktop.bundles/hello/hello.bemjson.js` file.
+ **hello** block is an entity that will contain all necessary elements for the project.
```js
{
@@ -87,8 +90,8 @@ A [BEMJSON file](https://en.bem.info/technology/bemjson/) describes a page struc
}
```
-2. Place `greeting` element with text of user greeting (**content** field) in `hello` block.
- **greeting** element is a sub-entity, that contains greeting phrase and ready-made blocks implementations.
+2. Place `greeting` element with the greeting text (**content** field) into `hello` block.
+ **greeting** element is a sub-entity, that contains the greeting phrase and ready-made blocks implementations of `bem-components` library.
```js
content: [
@@ -98,13 +101,13 @@ A [BEMJSON file](https://en.bem.info/technology/bemjson/) describes a page struc
{
elem: 'greeting',
content: 'Hello, %user%!'
- }
+ `bem-components` library}
]
}
]
```
-3. To create an input field and a button take provided by the `bem-components` library `input` and `button` blocks and add them to the `greeting` element.
+3. To create an input field and a button use `input` and `button` blocks from `bem-components` library. Add these blocks to `greeting` element.
```js
({
@@ -140,36 +143,36 @@ A [BEMJSON file](https://en.bem.info/technology/bemjson/) describes a page struc
})
```
-To consider that page shows all necessary objects, open [http://localhost:8080/desktop.bundles/hello/hello.html](http://localhost:8080/desktop.bundles/hello/hello.html).
+To consider that the page shows all necessary objects, open [http://localhost:8080/desktop.bundles/hello/hello.html](http://localhost:8080/desktop.bundles/hello/hello.html).
-You may provide some changes into existing blocks on your [redefinition level](https://en.bem.info/tools/bem/bem-tools/levels/).
+You can provide additional changes to existing blocks on your [redefinition level](https://en.bem.info/tools/bem/bem-tools/levels/).
-### 2. Create block
+### 2. Create a block
-To provide appropriate work of all object on the page, it is necessary to specify additional functionality of `hello` block on your redefinition level.
+To provide correct work to all object on the page, it is necessary to specify additional functionality of `hello` block on your redefinition level.
-1. Manually create directory of `hello` block on the `desktop.blocks` level.
-2. Place required for the project [block's implementation technology files](https://en.bem.info/method/filesystem/) (`CSS`, `JS`, `BEMHTML`) into **hello** directory.
- Block directory name and its nested files should coincide with block name specified in BEMJSON file.
+1. Create a directory of `hello` block on `desktop.blocks` level.
+2. Create [the implementation technology files](https://bem.info/method/filesystem/) (`CSS`, `JS`, `BEMHTML`) required to the block in **hello** directory.
+ A block directory name and its nested files must coincide with block name specified in a BEMJSON file.
- * `hello.js` – describes dynamic page functionality;
- * `hello.bemhtml` – template for generation of block HTML representation;
- * `hello.css` – changes objects design on the page.
+ * `hello.js` – describes dynamic page functionality
+ * `hello.bemhtml` – a template for generation of the block HTML representation
+ * `hello.css` – changes a custom design on the page
-### 3. Implement hello block
+### 3. Implement `hello` block
-For block representation in BEM terms it is necessary to describe it in the implementation technology files.
+To implement the block in BEM terms, use the created technology files.
-#### 3.1 Implement block in JavaScript technology
+#### 3.1 Implement `hello` block in JavaScript technology
-1. Describe a block reaction depending on user action with help of `onSetMod` property in the `desktop.blocks/hello/hello.js` file. After button clicking greeting text will be replaced with the user name entered in the input field.
-JavaScript code is written using the [i-bem.js](https://ru.bem.info/technology/i-bem/) (for the moment this article is available only in russian language) declarative JavaScript framework.
+1. Describe a block reaction depending on a user action using `onSetMod` property in the `desktop.blocks/hello/hello.js` file. A click on the button adds the user name from the input field into the greeting phrase.
+JavaScript code is written using [i-bem.js](https://ru.bem.info/technology/i-bem/) (this article is available only in russian language) declarative JavaScript framework.
```js
onSetMod: {
@@ -187,20 +190,20 @@ JavaScript code is written using the [i-bem.js](https://ru.bem.info/technology/i
```
-2. To represent current JavaScript code, use modular system [YModules](https://en.bem.info/tools/bem/modules/).
+2. To represent current JavaScript code, use [YModules](https://bem.info/tools/bem/modules/) modular system .
```js
modules.define(
- 'hello', // block name
+ 'hello', // a block name
['i-bem__dom'], // dependence connection
- function(provide, BEMDOM) { // function to which names of the used modules are transferred
- provide(BEMDOM.decl('hello', { // block declaration
- onSetMod: { // constructor for reaction description on event
+ function(provide, BEMDOM) { // a function that received names of the used modules
+ provide(BEMDOM.decl('hello', { // a block declaration
+ onSetMod: { // a constructor that describes reaction on an event
'js': {
'inited': function() {
this._input = this.findBlockInside('input');
- this.bindTo('submit', function(e) { // event on which there will be a reaction
+ this.bindTo('submit', function(e) { // the event that causes reaction
e.preventDefault(); // prevention of event work by default (form data sending to the server with page reload)
this.elem('greeting').text('Hello, ' + this._input.getVal() + '!');
});
@@ -213,11 +216,11 @@ JavaScript code is written using the [i-bem.js](https://ru.bem.info/technology/i
-#### 3.2 Implement block in BEMHTML technology
+#### 3.2 Implement `hello` block in BEMHTML technology
-[BEMHTML](https://en.bem.info/technology/bemhtml/current/rationale/) – technology that processes BEMJSON declaration to create HTML layout of a web page.
+[BEMHTML](https://bem.info/technology/bemhtml/current/rationale/) – technology that processes BEMJSON declaration to create HTML layout of a web page.
-1. Write [BEMHTML tempate](https://en.bem.info/technology/bemhtml/current/reference/) and specify that `hello` block has JavaScript implementation.
+1. Write [BEMHTML tempate](https://bem.info/technology/bemhtml/current/reference/) and specify that `hello` block has JavaScript implementation.
2. Implement `hello` block with form, adding `tag` mode.
```js
@@ -229,7 +232,7 @@ block('hello')(
-#### 3.3 Implement block in CSS technology
+#### 3.3 Implement `hello` block in CSS technology
Create your own CSS rules for `hello` block. For example:
@@ -265,10 +268,10 @@ To change the position of the block on the page and leave it in its original for
-## Result
+## The final result
-To see the result of this project, please refresh the page:
+To see the result of the project, please refresh the page:
http://localhost:8080/desktop.bundles/hello/hello.html
-Since the project consisted only of one page, in full build was no need. How to write a more complex project is described in [Starting your own project](https://en.bem.info/tutorials/start-with-project-stub/) article.
+Since the project consists only of one page, in full build was no need. Description of a more complex project is in [Starting your own project](https://bem.info/tutorials/start-with-project-stub/) article.
diff --git a/QuickStart.md b/QuickStart.md
index 54c2d7c..033bb7d 100644
--- a/QuickStart.md
+++ b/QuickStart.md
@@ -45,12 +45,12 @@
Процедура разработки страницы приветствия состоит из следующих этапов:
-1. [Создание страницы](#page_creation)
+1. [Создание страницы](#page_creation)
1.1 [Описание страницы в BEMJSON-файле](#BEMJSON_declaration)
2. [Создание блока](#block_creation)
-3. [Реализация блока hello](#block_hello_modification)
- 3.1 [В технологии JavaScript](#JS_modification)
- 3.2 [В технологии BEMHTML](#BEMHTML_modification)
+3. [Реализация блока hello](#block_hello_modification)
+ 3.1 [В технологии JavaScript](#JS_modification)
+ 3.2 [В технологии BEMHTML](#BEMHTML_modification)
3.3 [В технологии CSS](#CSS_modification)
После выполнения всех шагов можно смотреть [результат](#result).
@@ -70,7 +70,7 @@
[BEMJSON-файл](https://ru.bem.info/technology/bemjson/) – это структура страницы, описанная в терминах блоков, элементов и модификаторов.
-1. Добавьте на своем проекте описание блока `hello` в файле `desktop.bundles/hello/hello.bemjson.js`.
+1. Добавьте на своем проекте описание блока `hello` в файле `desktop.bundles/hello/hello.bemjson.js`.
Блок **hello** – это сущность, которая содержит в себе все необходимые для проекта элементы.
```js
@@ -90,7 +90,7 @@
}
```
-2. Поместите элемент `greeting` с текстом приветствия пользователя (поле **content**) в блок **hello**.
+2. Поместите элемент `greeting` с текстом приветствия пользователя (поле **content**) в блок **hello**.
Элемент **greeting** – это подсущность, в которую вкладывается фраза приветствия и готовые реализации блоков.
```js
@@ -156,8 +156,8 @@
1. Создайте вручную каталог блока `hello` на уровне `desktop.blocks`.
2. Разместите в нем необходимые для проекта [файлы технологий реализации блока](https://ru.bem.info/method/filesystem/) (`CSS`, `JS`, `BEMHTML`). Название каталога блока и вложенных в него файлов должны совпадать с именем блока, которое прописано в BEMJSON-файле.
- * `hello.js` – описывает динамическую функциональность страниц;
- * `hello.bemhtml` – шаблоны для генерации HTML-представления блока;
+ * `hello.js` – описывает динамическую функциональность страниц;
+ * `hello.bemhtml` – шаблоны для генерации HTML-представления блока;
* `hello.css` – изменяет внешний вид объектов на странице.
@@ -170,7 +170,7 @@
#### 3.1 Реализация блока в технологии JavaScript
-1. Опишие в файле `desktop.blocks/hello/hello.js` реакцию блока на действие пользователя с помощью специального свойства `onSetMode`. При нажатии кнопки в текст приветствия будет подставляться имя пользователя, введенное в поле input.
+1. Опишие в файле `desktop.blocks/hello/hello.js` реакцию блока на действие пользователя с помощью специального свойства `onSetMode`. При нажатии кнопки в текст приветствия будет подставляться имя пользователя, введенное в поле input.
JavaScript-код написан с использованием декларативного JavaScript-фреймворка – [i-bem.js](https://ru.bem.info/technology/i-bem/).
```js
@@ -252,7 +252,7 @@ block('hello')(
margin-right: 12px;
}
```
-Чтобы изменить положение блока на странице и при этом оставить его в первоначальном виде в библиотеке, подмешайте элемент с помощью метода `mix` во входных данных (BEMJSON).
+Чтобы изменить положение блока на странице используйте метод и при этом оставить его в первоначальном виде в библиотеке, подмешайте элемент с помощью метода `mix` во входных данных (BEMJSON).
```js
{
diff --git a/RationaleForJS.md b/RationaleForJS.md
new file mode 100644
index 0000000..853dd70
--- /dev/null
+++ b/RationaleForJS.md
@@ -0,0 +1,315 @@
+## БЭМ для JavaScript
+
+В разработке интерфейсов важно помнить, что сайт – это растущий организм.
+Ситуации, когда в коде сайта нет определенной структуры и фиксированных правил написания, приводят к сложностям в процессе разработки и поддержки. Чтобы обеспечить долгую и безоблачную жизнь вашему проекту следует начать с общего подхода, с методологии.
+
+### Зачем в JavaScript компонентный подход
+
+Те времена, когда веб-сайты состояли из статического контента и нескольких скриптов для обработки, остались позади.
+
+Современные пользователи становятся все требовательнее: веб должен быть быстрыми, динамическим, удобным, интерактивным и уметь адаптироваться под запросы потребителя. Сайты уже не представляют собой несколько страниц текста с картинками и ссылками; сейчас они обрабатывают информацию и решают многие задачи. Возрастание роли веб-приложений очевидны – они не требуют установки у пользователя и их гораздо проще настраивать под этого самого пользователя. Программами «из коробки» теперь все чаще можно воспользоваться непосредственно в вашем любимом браузере.
+Разработка становится все сложнее и интереснее: сайты увеличиваются в объемах, растет количество постоянных пользователей, владельцы сайта хотят угодить всем, так как напрямую от этого зависит их прибыль, повышается конкуренция. Сайт должен быть очень мобильным и уметь реагировать на все изменения окружающей среды практически мгновенно. А что же в таком случае остается делать разработчику? Ответ один: чтобы выжить, ему необходимо учиться оптимизировать разработку, умело пользоваться всем своим кодом и быстро отыскивать проблемные места, устраняя ошибку локально, не затрагивая никакие другие части кода.
+
+Как все это воплотить в жизнь? Типичный человеческий подход к преодолению сложной проблемы — дробление ее на более простые части. Идея разделения на компоненты не нова. Она в полном объеме реализована в ООП. Нам остается только перенять этот богатый опыт.
+
+Будущее (кажется, что это уже настоящее) веб-приложений – за переходом на компонентную структуру.
+
+Компонентный подход в JavaScript позволяет объединять сущности по общему признаку и организовывать их в соответствии с определенными правилами и ограничениями. Не имеет значения, как этот подход реализован, потому что у каждого компонента есть свои методы, которые знают все о себе. [Общение с внешними блоками](#independent-blocks) происходит либо через родителя, либо через каких-то посредников.
+
+Компонентная структура обеспечивает гибкость контроля версий и помогает избежать конфликтов во время ведения параллельной разработки. Перенос логики, связанной с конкретными блоками, в отдельные файлы, улучшает читаемость кода и ускоряет процесс создания и корректировки проекта. Именно эту задачу решает БЭМ.
+
+## Применение методологии БЭМ к JavaScript
+
+В процессе эволюции технологий написания сайтов появился БЭМ. Суть данного подхода – разбиение страницы на блоки и элементы. Определение свойств, их значений и дополнительного функционала блоков и элементов выполняется с помощью модификаторов. Еще одно ключевое понятие БЭМа – [уровни переопределения](https://ru.bem.info/tools/bem/bem-tools/levels/). Они позволяют расширять и дополнять поведение одного и того же блока.
+
+Изначально перед разработчиками ставились задачи отображения внешнего вида страницы, поэтому методология БЭМ применялась больше для именования классов в CSS. Как и CSS JavaScript пишется к каждому блоку отдельно и располагается непосредственно в самом блоке. Блок становится независимым и в функциональном плане. JavaScript приводит в действие какие-то модификаторы и это те самые модификаторы, которые приводят в действие какие-то CSS свойства. Они напрямую связаны и разделять их нет смысла, поскольку JavaScript и CSS оперирует одними терминами.
+
+Как же применить БЭМ-методологию к JavaScript? БЭМ вводит единую семантику на всех уровнях (HTML, CSS, JavaScript, шаблоны, дизайн интерфейсов) и предоставляет единый гибкий API поверх разнообразного набора методов работы с DOM. А на уровне файловой системы все про одну сущность складывает в одну папку, предназначенную для повторного использования и расширения.
+
+Чтобы на деле понять как работает подход БЭМ, понадобиться разобраться в следующих определениях, особенностях подхода и принципах:
+
+* [декларативный подход](#declaration)
+* [взаимодействие блоков](#independent-blocks)
+* [модификатор](#modifier)
+* [метод](#method)
+* [событие](#event)
+* [изменение поведения блока](#customization)
+* [инициализация](#initialization)
+
+
+
+
+### Декларативный подход
+
+Важной особенностью БЭМ технологии является декларативный принцип. Подобно работе декларативных языков программирования, JavaScript-код содержит не последовательный алгоритм работы блока, а набор действий и условий, при которых эти действия необходимо выполнять.
+
+Декларативность проявляется в объявлении того, к каким блокам или их модификациям применим код компонента. При декларировании какой-то сущности известно, что она имеет определенные состояния и при переходе в эти состояния с ней происходят конкретные действия, а при возвращении к предыдущему состоянию с ней случаются обратные действия.
+
+<Пример>
+
+<Расшифровка примера>
+
+
+
+### Способы взаимодействия блоков
+
+Блок в БЭМ – это независимый компонент, который можно переместить в любое место на странице, в том числе и в другой блок или же на другой проект. Блок может поддерживать разные технологии – HTML, CSS, JavaScript и т.п. БЭМ-методолгия позволяет на уровне проекта изменить внешний вид или поведение существующего блока, добавить новые блоки. Однако, несмотря на независимость блоков, на уровне JavaScript они обязаны общаться друг с другом.
+
+### Написание JavaScript-кода с сохранением независимости блоков
+
+Простой пример поможет понять как происходит взаимодействие блоков.
+
+**Описание**
+
+Есть форма, перед отправкой которой необходимо проверить, что введено корректное значение, и в случае ошибки показать попап с предупреждением.
+
+Выглядит это следующим образом:
+
+```html
+
+```
+
+```css
+.popup {
+ display: none;
+}
+
+.popup_visible {
+ display: block;
+}
+```
+Чтобы описанная конструкция заработала необходимо написать JavaScript-код.
+
+### Реализация в старом стиле
+
+Приведенный пример показывает, как делать **не надо**.
+
+```js
+$('.button').on('click', function(e) {
+ if (!/\S+@\S+\.\S+/.test($('.input').val())) {
+ $('.popup').addClass('popup_visible');
+ return false;
+ }
+});
+```
+Согласно представленному коду, кнопка «знает» про поле ввода и попап, кроме того явно предполагается, что она находится внутри формы.
+
+Однако реальность такова, что проекты не стоят на месте, они развиваются. Приходит момент, когда необходимо что-то добавить, переместить или изменить. Процесс реорганизации внутренней структуры в представленном коде, будь то удаление одного из компонентов или появление новых элементов, приведет к его поломке. При возможном переиспользовании такой кнопки, обязательно придется применить все компоненты с такими же классами и гарантировать, что больше нигде на странице они не встретятся.
+
+**Результат**
+Данный код сложно и поддерживать, и нерационально реиспользовать, если только не делать точную копию проекта.
+
+#### Улучшенная реализация
+
+```js
+$('.form').on('submit', function(e) {
+ if (/\S+@\S+\.\S+/.test($('.input', this).val())) return true;
+ e.preventDefault();
+ $('.popup', this).addClass('popup_visible');
+});
+```
+**Изменения**
+Согласно новому коду, форма, за все что происходит с ней, отвечает сама. Теперь компоненты внутри ничего не знают о существовании друг друга. При необходимости можно взять кнопку и перенести ее на другой проект, поскольку она стала независимой. В этом случае кнопка не будет нести в себе знание о какой-то форме, поле ввода и попапе.
+
+**Результат**
+Все селекторы вынесены за рамки контекста формы и теперь можно добавлять любое количество новых полей ввода, попапов и кнопок за пределами формы – ничего не сломается.
+Но, если добавить еще одно поле, придется реорганизовывать код. Кроме того, чтобы гарантировать перекрытие попапом любых других элементов на странице, необходимо положить его в самом конце DOM-дерева, перед закрывающим тегом ` `.
+
+#### Миксы
+
+**Изменения**