From 6f9343755d127f713aa9293f4a21610cbf8f7486 Mon Sep 17 00:00:00 2001 From: Inna Belaya Date: Thu, 28 Jun 2018 16:52:28 +0300 Subject: [PATCH] review changes --- .../dist-html-generation.ru.md | 109 ++++++ .../dist-quick-start/dist-quick-start.ru.md | 333 +++++++++--------- 2 files changed, 273 insertions(+), 169 deletions(-) create mode 100644 platform/tutorials/dist-quick-start/dist-html-generation.ru.md diff --git a/platform/tutorials/dist-quick-start/dist-html-generation.ru.md b/platform/tutorials/dist-quick-start/dist-html-generation.ru.md new file mode 100644 index 000000000..2d2e67cb6 --- /dev/null +++ b/platform/tutorials/dist-quick-start/dist-html-generation.ru.md @@ -0,0 +1,109 @@ +# Dist bem-components: генерация HTML-разметки блока в браузере + +Руководство показывает, как генерировать HTML-разметку блока в браузере с помощью [предсобранных бандлов](https://tech.yandex.ru/jslibs/) библиотеки [bem-components](https://ru.bem.info/platform/libs/bem-components/). + +* [Начало работы](#Начало-работы) +* [Подключение библиотеки](#Подключение-библиотеки) +* [Добавление блока на страницу](#Добавление-блока-на-страницу) +* [Что дальше?](#Что-дальше) + +## Начало работы + +Создайте локально HTML-файл с минимальным набором элементов (например, `hello.html`): + + ```html + + + + + Try Bem Components + + + + ``` + +## Подключение библиотеки + +Предсобранные бандлы библиотеки bem-components можно скопировать с [CDN Яндекса](https://tech.yandex.ru/jslibs/). + +Чтобы генерировать HTML-разметку блока в браузере, необходимо подключить бандл с шаблонизатором (`*.js+bemhtml.js`): + +```diff + + + + + bem-components as a library + + + + +
+
Hello, %user name%!
+
++ + + +``` + +В бандлы с расширением `*.js+bemhtml.js` включен шаблонизатор [BEMHTML](https://ru.bem.info/platform/bem-xjst/8/), который преобразует [BEMJSON](https://ru.bem.info/platform/bemjson/) в HTML. + +## Добавление блока на страницу + +Чтобы добавить блоки на страницу, выполните следующие действия: + 1. Откройте документацию блока (например, [input](https://ru.bem.info/platform/libs/bem-components/current/touch-phone/input)). + 2. Выберите подходящий вариант использования блока (например, блок [input с модификатором type в значении search](https://ru.bem.info/platform/libs/bem-components/6.0.0/touch-phone/input/#Модификатор-type-10)). + 3. Перейдите во вкладку BEMJSON. + ![Вкладка BEMJSON в примере блока input](https://cdn.rawgit.com/bem-site/bem-method/bem-info-data/platform/tutorials/dist-quick-start/dist-quick-start-bemjson.png) + 4. Скопируйте код и вставьте его в скрипт с шаблоном на страницу: + +```diff + + + + + bem-components as a library + + + ++ + + + + +``` + +Чтобы проверить результат, откройте файл `hello.html` в браузере. + +> Проект в [JSFiddle](https://jsfiddle.net/inna__neige/df6uuw7u/). Содержит реализацию [формы приветствия](./dist-quick-start.ru.md#) с помощью генерации HTML-разметки блока в браузере. + +## Что дальше? + +Библиотека bem-components в виде Dist не позволяет использовать все преимущества БЭМ-проекта: [уровни переопределения](../../../method/key-concepts/key-concepts.ru.md#Уровень-переопределения), [миксы](../../../method/key-concepts/key-concepts.ru.md#Микс) и возможность [точечной сборки проекта](../../../method/build/build.ru.md#Определение-списка-БЭМ-сущностей). Для максимально эффективного использования библиотеки, воспользуйтесь поставками [source или compiled](https://ru.bem.info/platform/libs/bem-components/6.0.0/#source-compiled). + +**Не получилось?** + +Если при создании формы возникли сложности, поищите решение на [форуме](https://ru.bem.info/forum/). Если готового ответа не нашлось, создайте пост со своим вопросом. diff --git a/platform/tutorials/dist-quick-start/dist-quick-start.ru.md b/platform/tutorials/dist-quick-start/dist-quick-start.ru.md index 5ab4db59f..3d5f5625e 100644 --- a/platform/tutorials/dist-quick-start/dist-quick-start.ru.md +++ b/platform/tutorials/dist-quick-start/dist-quick-start.ru.md @@ -1,232 +1,227 @@ -# Dist bem-components: подключаем блоки на страницу +# Dist bem-components: быстрый старт и работа с блоками -## Описание урока +Предварительно собранные файлы ([бандлы](https://ru.bem.info/methodology/build/#Введение)) библиотеки [bem-components](https://ru.bem.info/platform/libs/bem-components/) — это самый быстрый способ попробовать блоки библиотеки в действии. -Один из [вариантов поставки](https://ru.bem.info/platform/libs/bem-components/6.0.0/#Использование) библиотеки [bem-components](https://ru.bem.info/platform/libs/bem-components/6.0.0/) — это предварительно собранные файлы ([бандлы](https://ru.bem.info/methodology/build/#Введение)), которые подключаются ссылками в HTML страницы. Это самый быстрый способ попробовать [блоки](https://ru.bem.info/methodology/key-concepts/#Блок) библиотеки в действии. +Руководство содержит пошаговую инструкцию по созданию формы приветствия пользователя и включает следующие разделы: -> **Важно!** Данный вариант поставки не позволяет использовать все преимущества БЭМ-проекта: [уровни переопределения](../../../method/key-concepts/key-concepts.ru.md#Уровень-переопределения), [миксы](../../../method/key-concepts/key-concepts.ru.md#Микс) и возможность [точечной сборки проекта](../../../method/build/build.ru.md#Определение-списка-БЭМ-сущностей). Для максимально эффективного использования библиотеки, воспользуйтесь поставками [source или compiled](https://ru.bem.info/platform/libs/bem-components/6.0.0/#source-compiled). +* [Быстрый старт](#Быстрый-старт). Как подключить библиотеку и вставить блок на страницу. +* [Руководство](#Работа-с-блоками-библиотеки). Как работать с блоками библиотеки. -В этом уроке вы научитесь: -* [Подключать библиотеку в проект](#Подключение-библиотеки-в-проект) -* [Работать с блоками из библиотеки](#Работа-с-блоками) +## Быстрый старт -Мы подключим блоки `button` и `input` из библиотеки в форму приветствия, как показано на рисунке ниже. В [результате](#Результат) получим форму, в которой имя пользователя при нажатии на кнопку отобразится в приветствии. - -![Страница приветствия](https://cdn.rawgit.com/bem-site/bem-method/bem-info-data/articles/quick-start-static/quick-start-static__hello-user.svg) - -> [HTML-код](https://jsfiddle.net/inna__neige/jbrtwwcp/) страницы с формой приветствия. - -Для работы с примерами необходимы: - -* базовые навыки - * HTML - * CSS - * JavaScript - * БЭМ - -* понимание технологий БЭМ - * [i-bem.js](https://ru.bem.info/platform/i-bem/) - * [BEMHTML](https://ru.bem.info/platform/bem-xjst/8/) - -### Как выполнить урок - -Есть несколько способов выполнить этот урок: вы можете писать код локально или использовать любую среду веб-разработки (например, [JSFiddle](https://jsfiddle.net), [CodePen](https://codepen.io/), [JS Bin](http://jsbin.com/?html,output)), которая позволяет редактировать и запускать код HTML, JavaScript и CSS. - -> Все примеры выполнены в JSFiddle. - -## Подключение библиотеки - -Существует [несколько способов](https://ru.bem.info/platform/libs/bem-components/6.0.0/#Подключение-предсобранных-файлов-библиотеки-dist) получить предсобранные бандлы библиотеки. В документе рассмотрен способ подключения файлов с [CDN Яндекса](https://tech.yandex.ru/jslibs/). - -Схема подключения файла с CDN: `//yastatic.net/название-библиотеки/версия/платформа/имя-файла`. - -Чтобы подключить скрипты и стили библиотеки в проект, скопируйте ссылки на бандлы в теги `` и ` + + + ``` + +3. Вставьте блок на страницу + 3.1 Откройте документацию блока (например, [input](https://ru.bem.info/platform/libs/bem-components/current/touch-phone/input)). + 3.2 Выберите подходящий вариант использования блока (например, блок [input с модификатором type в значении search](https://ru.bem.info/platform/libs/bem-components/6.0.0/touch-phone/input/#Модификатор-type-10)). + 3.3 Перейдите во вкладку HTML и скопируйте код. + ![Вкладка HTML в примере блока input](https://cdn.rawgit.com/bem-site/bem-method/bem-info-data/platform/tutorials/dist-quick-start/dist-quick-start-html.png) + 3.4 Вставьте код блока в файл `hello.html`. + + ```diff + + + + + Try Bem Components + + + + + + + + + + + + + + + + + ``` + +4. Проверьте результат + Откройте файл `hello.html` в браузере. + +## Работа с блоками библиотеки + +Не всегда достаточно увидеть, как выглядит блок на странице, часто нужно понять, как блоки могут взаимодействовать друг с другом. + +Чтобы научиться работать с блоками bem-components, создадим форму приветствия пользователя. Форма будет состоять из поля ввода, кнопки и фразы с приветствием. Если в поле ввода указать имя и нажать на кнопку, это имя отобразится в приветствии. + +### Создание формы приветствия + +* Откройте файл `hello.html`, который вы получили в результате [быстрого старта](#Быстрый-старт). +* Добавьте в него форму приветствия — блок `hello`. + ```diff - bem-components as a library -+ + Try Bem Components + -+ + ++
++
Hello, %user name%!
++ ++ ... ++ ++
+ ``` -> **Важно!** Библиотека содержит бандлы без [автоинициализации](https://ru.bem.info/platform/i-bem/init/) (`*.no-autoinit.js`), которые позволяют доопределять JavaScript-реализацию блоков библиотеки. - -## Работа с блоками +### Добавьте блок `button` -Чтобы добавить блок на страницу, необходимо: - -1. Выбрать блок - Зайдите в описание блока на сайте [bem.info](https://ru.bem.info/platform/libs/bem-components/6.0.0/) и выберите подходящий пример: - * [input](https://ru.bem.info/platform/libs/bem-components/6.0.0/touch-phone/input/#Модификатор-type-10) - * [button](https://ru.bem.info/platform/libs/bem-components/6.0.0/touch-phone/button/#Кнопка-отправки-формы-модификатор-type-в-значении-submit-1) - -2. Получить HTML-разметку выбранного блока - Воспользуйтесь примером из документации, чтобы получить HTML. HTML-код блока можно получить несколькими способами: - * [Использовать готовый HTML](#Использование-готового-html) - > Если новая версия библиотеки будет содержать шаблоны, которые изменят HTML-разметку, потребуется исправлять каждый блок вручную. - * [Генерировать HTML в браузере](#Генерация-html-в-браузере) - > Если в новой версии библиотеки обновленные шаблоны изменят разметку, исправлять шаблоны вручную не потребуется. Но генерируемая в браузере разметка хуже индексируется поисковыми системами. - -### Использование готового HTML - -Чтобы получить готовую HTML-разметку блока, перейдите во вкладку `HTML` в примере блока: - -![Вкладка HTML в примере блока input](https://cdn.rawgit.com/bem-site/bem-method/bem-info-data/platform/tutorials/dist-quick-start/dist-quick-start-html.png) - -Скопируйте код и вставьте на страницу: +Вставьте HTML-код блока `button` в код файла `hello.html` по аналогии с блоком `input`: +1. Откройте описание блока [button](https://ru.bem.info/platform/libs/bem-components/6.0.0/touch-phone/button/#Кнопка-отправки-формы-модификатор-type-в-значении-submit-1). +2. Перейдите во вкладку HTML в примере блока и скопируйте код. +3. Вставьте код блока в файл `hello.html`. ```diff - bem-components as a library + Try Bem Components
Hello, %user name%!
- -+ -+ -+ -+ -+ - -+ + + + + + + + ++
``` -Блоки `input` и `button` отобразились [на странице](https://jsfiddle.net/inna__neige/0hLmLmzn/6/). Чтобы имя из поля ввода появлялось в приветствии, опишите поведение блоков: - -```javascript -modules.define('hello', ['i-bem-dom', 'input', 'button'], - function(provide, bemDom, Input, Button) { - - provide(bemDom.declBlock('hello', { - onSetMod: { - js: { - inited: function() { - this._input = this.findChildBlock(Input); - } - } - }, - - _onSubmit: function(e) { - e.preventDefault(); - this._elem('greeting').domElem.text('Hello, ' + this._input.getVal() + '!'); - } - }, { - lazyInit: true, - onInit: function() { - this._domEvents().on('submit', this.prototype._onSubmit); - } - })); - -}); -// Вызов `init();`. Hеобходимо явно вызвать `init();`, чтобы инициализировать блоки, заранее присутствующие в HTML-разметке. -modules.require('i-bem-dom__init', function(init) { init(); }); -``` - -Чтобы изменять поведение блоков, используется фреймворк [i-bem.js](https://ru.bem.info/platform/i-bem/), который является частью библиотеки [bem-core](https://ru.bem.info/platform/libs/bem-core/4.2.0/). Чтобы писать код на i-bem.js, дополнительно подключать на страницу предсобранные бандлы библиотеки `bem-core` не нужно, они уже включены в сборку. +Чтобы проверить, что блоки `input` и `button` отобразились на странице, откройте файл `hello.html` в браузере. -Проект в [JSFiddle](https://jsfiddle.net/inna__neige/0hLmLmzn/). +### Добавление JavaScript-реализации блокам -### Генерация HTML в браузере +> **Важно!** Чтобы изменять JavaScript-реализацию блоков библиотеки bem-components, необходимо [подключать](#Подключите-библиотеку) бандлы без [автоинициализации](https://ru.bem.info/platform/i-bem/init/) (`*.no-autoinit.js`). +> +> `https://yastatic.net/bem-components/latest/desktop/bem-components.no-autoinit.js` -Чтобы генерировать HTML-разметку блока в браузере, необходимо использовать шаблонизатор [BEMHTML](https://ru.bem.info/platform/bem-xjst/8/), который преобразует [BEMJSON](https://ru.bem.info/platform/bemjson/) в HTML. Для этого [подключите](##Подключение-библиотеки-в-проект) бандл с шаблонизатором (`*.js+bemhtml.js`): +Добавьте скрипт с описанием поведения блоков, чтобы имя из поля ввода появлялось в приветствии: -```diff +```diff hello.html - bem-components as a library + Try Bem Components - +
Hello, %user name%!
+ + + + + + + +
-- -+ + ++ ``` -Чтобы получить `BEMJSON`-код блока, перейдите во вкладку `BEMJSON` в примере блока: +Чтобы описывать поведение блоков, используется фреймворк [i-bem.js](https://ru.bem.info/platform/i-bem/), который является частью библиотеки [bem-core](https://ru.bem.info/platform/libs/bem-core/4.2.0/). Дополнительно подключать bem-core на страницу не нужно, библиотека уже включена в предсобранные бандлы `bem-components. -![Вкладка BEMJSON в примере блока input](https://cdn.rawgit.com/bem-site/bem-method/bem-info-data/platform/tutorials/dist-quick-start/dist-quick-start-bemjson.png) +Проект в [JSFiddle](https://jsfiddle.net/inna__neige/0hLmLmzn/). -Скопируйте код и вставьте его в скрипт с шаблоном на страницу: +## Что дальше? -```diff -modules.define('hello', ['i-bem-dom', 'BEMHTML', 'input', 'button'], - function(provide, bemDom, BEMHTML, Input, Button) { - - provide(bemDom.declBlock('hello', { - onSetMod: { - js: { - inited: function() { - bemDom.append(this.domElem, BEMHTML.apply([ // Выполнение шаблона -+ { -+ block: 'input', -+ mods: { -+ theme: 'islands', -+ size: 'm' -+ }, -+ placeholder: 'User name' -+ }, -+ { -+ block: 'button', -+ mods: { -+ theme: 'islands', -+ size: 'm', -+ type: 'submit' -+ }, -+ text: 'Click' -+ } - ])); - - this._input = this.findChildBlock(Input); - } - } - }, - - _onSubmit: function(e) { - e.preventDefault(); - this._elem('greeting').domElem.text('Hello, ' + this._input.getVal() + '!'); - } - }, { - onInit: function() { - this._domEvents().on('submit', this.prototype._onSubmit); - } - })); -}); - -// Вызов `init();` -modules.require('i-bem-dom__init', function(init) { init(); }); -``` +Использовать готовый HTML-код — это не единственный способ получить готовый блок на странице. HTML блоков можно не копировать из примера, а генерировать в браузере. + +Оба способа имеют свои ограничения: -Проект в [JSFiddle](https://jsfiddle.net/inna__neige/df6uuw7u/). +* [Использование готового HTML](#Работа-с-блоками-библиотеки) + Если в новой версии библиотеки изменится код шаблонов, которые изменят HTML-разметку блоков, потребуется исправлять разметку каждого блока на странице вручную. +* [Генерация HTML в браузере](./dist-html-generation.ru.md) + Если в новой версии библиотеки обновленные шаблоны изменят разметку, исправлять шаблоны вручную не потребуется. Но генерируемая в браузере разметка хуже индексируется поисковыми системами. -## Результат -Форма приветствия готова. Чтобы она выглядела, как на рисунке в начале документа, добавьте блокам новые [стили](https://gist.github.com/innabelaya/dacca124dc486e7a3b0854752d9013e7). +Библиотека bem-components в виде Dist не позволяет использовать все преимущества БЭМ-проекта: [уровни переопределения](../../../method/key-concepts/key-concepts.ru.md#Уровень-переопределения), [миксы](../../../method/key-concepts/key-concepts.ru.md#Микс) и возможность [точечной сборки проекта](../../../method/build/build.ru.md#Определение-списка-БЭМ-сущностей). Для максимально эффективного использования библиотеки, воспользуйтесь поставками [source или compiled](https://ru.bem.info/platform/libs/bem-components/6.0.0/#source-compiled). **Не получилось?**