Структура проекта и именования элементов

Данный документ описывает стандартную структуру папок проекта и правила формирования названий классов и файлов. Наши билд-скрипты по умолчанию настроены на работу именно с такой структурой.

Чтобы не начинать каждый проект с нуля можно взять готовую к использованию заготовку отсюда: jam-boilerplate.

Базовая структура проекта

blocks/
    _b-block-default/
        b-block-default.css
        b-block-default.ie.css
        b-block-default.js
        b-block-default__icons.png
    b-block-custom/
        b-block-custom.css
        b-block-custom.ie.css
        b-block-custom.js
        b-block-custom__icons.png
    config.styl
    style.css
    style.ie.css
lib/
publish/
tmp/
.htaccess
apple-touch-icon-114x114.png
apple-touch-icon-144x144.png
apple-touch-icon-57x57.png
apple-touch-icon-72x72.png
apple-touch-icon.png
crossdomain.xml
favicon.ico
Gruntfile.js
index.html
robots.txt

Описание файлов и папок

blocks/

В данной папке хранятся ресурсы используемые при верстке (css, js, изображения). Ресурсы сгруппированы по блокам, правила разделения по блоками и их именования описаны ниже.

Кроме собственно блоков в данной папке также присутствуют следующие файлы:

1. style.css — общий файл стилей проекта. В него через @import подключаются все остальные .css и .styl файлы. Он используется как основа для создания единого файла стиля при сборке ресурсов.
2. style.ie.css — файл в котором хранятся фиксы для IE версий 8 и ниже. В начало файла импортится style.css, поэтому для ie нужно подключать только его. Также используется как основа для сборки ресурсов.
3. config.styl — stylus-конфиг для стандартных блоков из базовой поставки (reset, text, grid). Позволяет менять типы и размеры шрифтов, свойства типографики и настройки сетки.

lib/

Папка для внешних библиотек. jQuery, Backbone.js и прочие зависимости нужно размещать здесь. если порядок их подключения в html-файл не важен можно на этом остановиться, если их нужно подключать в определенном порядке, то необходимо отредактировать файл build/grunt.js чтобы этот порядок отразить.

publish/

Папка куда сохраняются пожатые .js и .css файлы.

По-умолчанию создаются следующие файлы:

1. _style.css — объединенный css-файл без сжатия.
2. _style.ie.css — объединенный css-файл для IE без сжатия.
3. _style.min.css — сжатый css-файл.
4. _style.ie.min.css — сжатый css-файл для IE.
5. _script.js — объединенный js-файл.
6. _script.min.js — сжатый объединенный js-файл.

tmp/

В данную папку складываются служебные картинки для верстки (например примеры аватаров или иллюстраций к новостям). В качестве альтернативы для заглушек можно использовать картинки с http://lorempixel.com и других похожих сервисов.

Gruntfile.js

Build-скрипт проекта. Для использования нужно установить [https://github.com/i-akhmadullin/jet]()

Для разработки и финальной сборки ресурсов настроены следующие базовые скрипты:

1. grunt reloader — собирает ресурсы без сжатия, следит за обновлением файлов, при изменении пересохраняет файлы. Для обновления стилей без перезагрузки необходимо поставить расширение LiveReload.
2. grunt publish — собирает и сохраняет ресурсы с максимальной степенью сжатия, предварительно очистив папку publish/. Также валидирует получившиеся css и js файлы через csslint и jshint.

По умолчанию watch-скрипт следит за папками blocks/ и lib/ и реагирует на изменения файлов с расширениями .css, .styl, .js в них и во вложенных папках.

Прочие ресурсы в корне

• .htaccess — конфиг для сервера Apache с установленными настройками для GZip-сжатия, кеша и правильного выставления заголовков.
• apple-touch-icon-*.png — иконки для рабочего стола iOS-устройств в разных размерах.
• crossdomain.xml — конфиг для flash’а, запрешающий crossdomain scripting в целях безопасности.
• favicon.ico — фавикон.
• robots.txt — заготовка robots.txt.

Также в корень проекта складываются созданные html-файлы.

Структура блоков

Блоки в папке blocks/ бывают двух видов: с символом "_" в начале названия и без. Файлы с землей в начале являются системными, их не рекомендуется редактировать напрямую. Изменения их настроек обычно делается через внешний config.styl файл, либо в корне папки blocks/, либо в корне папки текущего блока.

Если возможностей конфига недостаточно, рекомендуется создать одноименную папку без земли в начале и переназначить там необходимые свойства.

Подобный подход позволит нам обновлять системные файлы не боясь что-нибудь поломать.

Все файлы ресурсов, относящиеся к блоку, хранятся внутри папки блока. Названия всех файлов ресурсов, относящихся к блоку, начинаются с названия блока. Если в папке только один файл подобного типа, то можно именем блока ограничится. Если файлов одного типа несколько, то к названию дополняется название элемента или модификатора к которым они относятся.

Ресурсы относящиеся к отдельным ресурсам и модификаторам можно выносить в подпапки с именем этого ресурса или модификатора. Например: "__title" или "_type_small".

Наименования классов

Все оформление в css вешается на классы. id и названия тегов для выбора элементов не используются. Каскады используются только внутри класса-модификатра.

Мы используем принцип формирования названий из БЭМ-методологии:

1. b-block — название блока, должен находиться на корневом теге блока, элементы блока не могут находиться вне тега блока.
2. b-block__element — название элемента, всегда включает название блока.
3. b-block_type_value — модификатор блока или элемента. Используется вторым классом на модифицируемым элементе. Может изменять свойства вложенных элементов через каскад.

Префикс ".b-" мы используем для создания собственно неймспейса, который с низкой вероятностью будет пересекаться с именами классов используемыми в подключаемых js-библиотеках. Вместо ".b-" при желании можно использовать любой другой уникальный префикс, данный используется в основном по историческим причинам.

Подробнее о синтаксисе БЭМ:

1. Что такое БЭМ?