From 5212317832c86cad29a44f7d48d7995b7ae64f63 Mon Sep 17 00:00:00 2001 From: Inna Belaya Date: Fri, 17 Jul 2015 13:08:34 +0300 Subject: [PATCH] dist usage --- README.ru.md | 185 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 172 insertions(+), 13 deletions(-) diff --git a/README.ru.md b/README.ru.md index 41af3e74b..1a93878a9 100644 --- a/README.ru.md +++ b/README.ru.md @@ -1,4 +1,4 @@ -BEM Components Library +bem-components ====================== [![GitHub Release](https://img.shields.io/github/release/bem/bem-components.svg?style=flat)](https://github.com/bem/bem-components/releases) [![Build Status](https://img.shields.io/travis/bem/bem-components/v2.svg?style=flat)](https://travis-ci.org/bem/bem-components) @@ -19,7 +19,6 @@ BEM Components Library * Технологии * Инструменты * Использование -* Варианты поставки библиотеки * Разработка * Команда основной разработки * Рабочий процесс @@ -127,26 +126,186 @@ BEM Components Library ## Использование -Библиотека в проект подключается с помощью [bem-tools](https://ru.bem.info/tools/bem/bem-tools/) или [ENB](http://enb-make.info/). Укажите название и версию библиотеки в конфигурационном файле выбранного вами сборщика. +Существует несколько способов начать работу с `bem-components`. Выбор подходящего способа использования зависит от требований проекта и его совместимости с [технологиями](#techs) и [инструментами](#tools) библиотеки, а также от вашего опыта работы с БЭМ-проектами. -При разработке проекта на основе [project-stub](https://ru.bem.info/tutorials/project-stub/) библиотека подключена по умолчанию. +Выберите способ поставки, наиболее подходящий вашему проекту: - -## Варианты поставки библиотеки +| Dist | Source | Compiled | +|---------|--------|----------| +| Предсобранный CSS- и JavaScript-код и шаблоны библиотеки. Подключается ссылками на страницу. Не требует сборки и совместимости с вашим проектом.| Полный исходный код библиотеки. Для использования необходима предварительная сборка. Требует полной совместимости проекта с [технологиями](#techs) и [инструментами](#tools) библиотеки. | Полный исходный код библиотеки. Для использования необходима предварительная сборка. Требует частичной совместимости проекта с [технологиями](#techs) и [инструментами](#tools) библиотеки. Подходит для проектов, не использующих [Stylus](https://learnboost.github.io/stylus/). | -**Source** +Способ использования библиотеки определяет порядок ее подключения в проект: -Для технически идентичных сервисов и проектов, которые используют препроцессор и шаблонизатор, указанные в разделе [Инструменты](#tools). +* [Подключение исходного кода библиотеки (Source и Compiled)](#) +* [Подключение предсобранных файлов библиотеки (Dist)](#) -**Compiled** +### Подключение исходного кода библиотеки (Source и Compiled) -Для сервисов и проектов, которые не используют препроцессор или используют отличный от указанного в разделе [Инструменты](#tools). +Рекомендуемый способ подключения — использование инструментов [ENB](http://enb-make.info/) или [bem-tools](https://ru.bem.info/tools/bem/bem-tools/). -**Library** +В качестве примера воспользуйтесь [project-stub](https://ru.bem.info/tutorials/project-stub/), где библиотека подключена по умолчанию. Также можно создать проект и подключить в него библиотеку с помощью генератора [Yo](https://ru.bem.info/tools/bem/bem-stub/), который позволяет создать необходимую конфигурацию проекта. -Для возможности подключения библиотеки ссылками на страницу, по аналогии с jQuery или Bootstrap. +### Подключение предсобранных файлов библиотеки (Dist) -Для выбора этого варианта поставки необходимо выполнить `npm run dist` в корне библиотеки после установки `npm`-зависимостей. В результате бандлы сформируются в папке `dist`. +Самый простой способ подключить библиотеку в проект — скачать предварительно собранные файлы библиотеки и добавить их в HTML страницы с помощью элементов `` и ` +``` + +Схема подключения файла с CDN: `//yastatic.net/название-библиотеки/версия/платформа/имя-файла`. + +Пример: `//yastatic.net/bem-components/latest/desktop/bem-components.dev.js+bh.js`. + +#### Загрузка в виде архива + +Выберите необходимую версию библиотеки и скачайте [архив](https://github.com/bem/bem-components-dist/releases). Распакуйте. Добавьте файлы на страницу с помощью элементов `` и ` +``` + +#### Сбор файлов из исходного кода + +Код библиотеки находится на Github: [https://github.com/bem/bem-components](https://github.com/bem/bem-components). + +Для сборки выполните следующие команды: + +``` +# Клонируйте исходный код библиотеки +git clone https://github.com/bem/bem-components.git +# Перейдите в папку библиотеки +cd bem-components +# Установите необходимые зависимости +npm install +# Соберите Dist +npm run dist +``` + +В результате сборки файлы будут доступны в папке `bem-components-dist`. Подключите файлы в HTML страницы: + +```html + + +``` + +#### Установка с помощью Bower + +При условии, что [Bower](http://bower.io/) уже установлен в ваш проект, выполните следующую команду: + +``` +bower i bem/bem-components-dist +``` + +В результате сборки файлы будут доступны в папке `bem-components-dist`. Подключение не отличается от предыдущего способа: + +```html + + +``` + +#### Работа с библиотекой + +Работу с библиотекой можно разбить на два шага: + +1. Найти нужный блок на сайте библиотеки: [bem.info](https://ru.bem.info). Например, [select](https://ru.bem.info/libs/bem-components/current/desktop/select/#Список-с-одиночным-обязательным-выбором-модификатор-mode-в-значении-radio). +1. Получить необходимый HTML. + +Первый шаг всегда одинаковый. Второй — выполняется тремя разными способами, которые можно произвольно комбинировать: + +**Способ I.** Скопировать нужный HTML из примера и поправить его при необходимости. Для этого перейдите во вкладку `HTML` в шапке примера. + +Этот вариант максимально простой, но при обновлении шаблонов в последующих версиях библиотеки потребуется вручную вносить изменения в каждый обновленный блок. + +**Способ II.** Использовать шаблонизацию в браузере. Сборка библиотеки `Dist` включает предсобранные шаблоны BEMHTML и BH на выбор. + +Для этого скопируйте из документации BEMJSON-код примера и вставьте его в HTML страницы. Используйте вкладку `BEMJSON` в шапке примера. + +HTML страницы будет выглядеть следующим образом: + +```html + + + + + bem-components as a library + + + + + + + +``` + +Такой код не потребует изменений в разметке при обновлении библиотеки до новой версии в отличие от способа I. Однако генерируемая на клиенте разметка может хуже индексироваться поисковыми системами. + +**Способ III.** Выполнять `{BEMHTML,BH}.apply()` в Node.js и отдавать браузеру уже готовый HTML: + +``` +var BEMHTML = require('./dist/desktop/bem-components.bemhtml.js').BEMHTML; + +BEMHTML.apply({ + block : 'select', + mods : { mode : 'check', theme : 'islands', size : 'm' }, + name : 'select1', + val : [2, 3], + text : 'Программа конференции', + options : [ + { val : 1, text : 'Доклад' }, + { val : 2, text : 'Мастер-класс' }, + { val : 3, text : 'Круглый стол' } + ] +}); // возвращает HTML-строку +``` ## Разработка