Работа с шаблоном
================

## Установка gulp ###

Для работы Gulp необходимо:

1. Установить на ПК [Node.js](https://nodejs.org/en/download/) *(на сервере разработки уже установлен, для него шаг пропускается)*
2. Установить Gulp глобально, команда в терминале: npm install -g gulp. *(на сервере разработки уже установлен, для него шаг пропускается)*
3. Установить локальные зависимости сборщика. В папке \_sources/ запустить команду: npm install
4. После завершения загрузки и установки зависимостей, можно запустить сборщик командой терминала gulp в папке \_sources/ *ключи запуска указаны ниже*

## Структура файлов и папок

```
(00) .
(01) +-- blocks
(02) |   +-- block-name
(03) |   |   +-- block-name.js
(03a)|   |   +-- block-name.dummy.js
(04) |   |   +-- block-name.scss
(05) |   |   +-- block-name.jade
(06) |   +-- ...
(07) +-- docs
(08) +-- fonts
(09) |   +-- FontAwesome
(10) +-- gulp_tasks
(11) |   +-- config.js
(12) |   +-- tasks
(13) |   |   +-- taskName.js
(14) |   |   +-- ...
(15) +-- gulpfile.js
(16) +-- img
(17) |   +-- content
(18) |   +-- logo.png
(19) |   +-- logo@2x.png
(20) |   +-- ...
(21) +-- js
(22) |   +-- vendor
(23) |   +-- global.js
(24) |   +-- script.js
(25) |   +-- tech.js
(26) +-- package.json
(27) +-- pages
(27a)|   +-- layout
(28) |   +-- page-name.jade
(29) |   +-- ...
(30) +-- public
(31) +-- sass
(32) |   +-- _layout.scss
(33) |   +-- _variables.scss
(34) |   +-- fontawesome.scss
(35) |   +-- global.scss
(36) |   +-- helpers
(37) |   |   +-- FontAwesome
(38) |   |   +-- _grid.scss
(39) |   |   +-- _mixins.scss
(40) |   |   +-- fonts.scss
(41) |   |   +-- optimize.scss
(42) |   +-- print.scss
(43) |   +-- tech.scss
(44) +-- tmp
```

#### (01) blocks

Тут располагаются блоки, каждый в своей папке. Папка блока должна называться строго названием блока. Внутри папки могут быть файлы scss, js, jade, каждый из которых называется строго по названию блока.
Не допускается в файле блока хранить более одного блока.

#### (03) block-name.js

Если для работы блока требуется js-код, он должен быть описан здесь. Js-функции должны быть обёрнуты в свой scope ```$(function() { ... });```.
Скрипт должен быть готов к тому, что блока на странице может не быть, либо он может встречаться несколько раз.

#### (03a) block-name.dummy.js

Если для демонстрации работы блока в статической версии требутся JSON-данные, либо аякс-запросы c "рыбными" ответами — это должно быть в отдельном файле (в этом). Файлы *.dummy.js не попадают в production-версию.

#### (04) block-name.scss

SCSS стили блока. Как правило имеют следующий вид:

```
.block-name {
   &__element {
      some-style: some-value;
   }
   &__another-element {
      some-style: some-value;
	  &.is-modificator {
	     some-style: some-value;
	  }
   }
   
   @media #{$media-phone-landscape} {
      &__element {
	     // модификация стилей для мобильной версии
	  }
	  &__another-element {
	     // модификация стилей для мобильной версии
	  }
   }
}

.block-name.is-modificator {
   .block-name {
      &__element {
	     // Стили элемента для блока с модификатором
		 // Эта конструкция компилируется в ".block-name.is-modificator .block-name__element"
	  }
   }
}
```

#### (05) block-name.jade

Jade (pug) разметка блока. Позволяет собирать страницы из блоков локально. Иногда может расходиться с тем, что привязано на сайте.
Используется для вёрстки новых блоков перед их привязкой в шаблон компонента.

#### (07) docs

Кое-какая документация. Здесь лежит инструкция по адаптивной сетке (Webrofy Grid)

#### (08) fonts

Шрифты. Здесь лежит FontAwesome, здесь должен лежать кастомный иконочный шрифт, если он используется на проекте. Здесь в __редких__ случаях должны лежать файлы web-шрифтов, используемых на сайте.
Обычно шрифты подключаются через GoogleFonts или Adobe TypeKit и не требуют локальных файлов.

#### (10) gulp_tasks

Задачи для Gulp. Разложены по отдельным файлам.

#### (16) img

Картинки. Должны лежать все в корне, кроме картинок для контента.

#### (17) content

Изображения для контента — фотографии, баннеры. Всё то, что потом будет загружаться через админку (и изменит свой URL).
В SCSS-стилях не должно быть ссылок на изображения из этой папки.

#### (19) logo@2x.png

Ретина-версии картинок (в удвоенном разрешении) должны называться аналогично стандартной версии картинки, но с окончанием @2x

#### (21) js

Общие скрипты

#### (22) vendor

jQuery, jQuery-ui, fancybox, slick slider и прочие вендорные скрипты.

Для добавления нового js плагина нужно положить его в /js/vendor/%Название скрипта%/%файл скрипта%.js, а также **обязательно** добавить файл /js/vendor/%Название скрипта%/%файл скрипта%.jade, в котором прописан код 
```- scriptList[1].push('./js/vendor/%Название скрипта%/%файл скрипта%.js');```
Примеры есть в папке, так он автоматически включится в сборку.

#### (23) global.js и (24) script.js

Глобальные функции. По нелепой случайности оказавшиеся разеделенными на два разных файла. В будущем будут слиты в один общий.

#### (25) tech.js

Скрипт используется только в локальной сборке для демонстрации блоков.

#### (27) pages

Статическая вёрстка страниц в формате jade (pug). В теле страницы как правило переопределяются только конкретные области дефолтного шаблона страницы.

#### (27a) layout

Шаблоны страниц, наследуются конкретными страницами.

#### (30) public

В эту папку генерируются файлы при локальной сборке. Безопасно её очищать.

#### (31) sass

Папка с общими sass-стилями

#### (32) _layout.scss

Блок layout отвечает за основную разметку страницы. Управляет расположением других блоков (позиционирует их друг относительно друга).

#### (33) _variables.scss

Переменные. Для удобства большая часть стилей "по-умолчанию" завязана за переменные. Стилизацию вёрстки следует начинать именно с этого файла.
Все переменные для конкретного проекта также должны быть добавлены сюда.

#### (35) global.scss

Глобальные стили. Здесь определяются общие стили (h1, h2, p, ul...), стили контента (.content-area) 

#### (36) helpers

Прочие включаемые файлы

#### (38) _grid.scss

Адаптивная сетка. См. описание в папке /docs

#### (39) _mixins.scss

Наши миксины. Обязательно изучить

#### (40) fonts.scss

Подключение иконочных и кастомных шрифтов

#### (41) optimize.scss

Аналог reset.css

#### (42) print.scss

Стили для печати

#### (43) tech.scss

Используется только в локальной сборке для демонстрации блоков

#### (44) tmp

Временная папка, используется сборщиком

## Ключи запуска ##
- --local 

Исключает ключ --production, сборка идёт в папки public/js, public/css и т.п.; собираются блоки в public/blocks.html, страницы в public/*.html, изображения копируются в public/img, шрифты в public/fonts, запускается browserSync.

Ключ используется в случае локальной сборки (без битрикс).

- --production 

Исключает ключ --local, сборка идёт в папку шаблона сайта: ../css, ../js, ../img, ../fonts (т. е на уровень выше, в корень шаблона сайта на битрикс); не собираются блоки и страницы, собирается быстро

- --fast 

Используется с ключом --local, позволяет собирать только изменённые страницы, а не все, работает быстрее

- --page название-страницы

Локальная сборка базовой страницы. Заменяет ключи --local и --fast, пересобирает jade конкретной страницы на каждом изменении jade блока или страницы. Например: gulp --jade news-list-default

## Команды запуска ##
- gulp

Сборка вёрстки. Скрипт компилирует sass и собирает в один css, собирает и объединяет js, логика сборки определяется ключами запуска

- gulp clean. 

Удаляет автоматически собираемые файлы. Нужно использовать с ключами --local или --production. Если появляется ошибка, связанная с правами файлов, запускается эта команда. *По умолчанию один из модулей пытается выполнить chmod, на что прав не хватает. Но при этом у gulp хватает прав эти файлы удалять.*

## Как добавить вендорный js ##



## Что ещё нужно знать ##
Не надо запускать отдельные таски, например gulp sass --production. В сборщике есть неочевидные зависимости, каких-то файлов может не хватать при запуске одной команды. Все возможные отдельные команды запуска указаны выше.

Почему jade, а не pug? Несмотря на то, что jade уже переименовался в pug, мы продолжаем его использовать из-за проблем с производительностью. Пока мы ждём исправления этой ошибки или другого решения, приходится создавать файлы jade и запускать соответствующие устаревшие модули.

Сборка с ключом --local на сервере работает медленно, эта проблема известна, но нормального решения пока нет. Локально собирается обычно быстрее. В плане есть небольшое обходное решение: указывать параметром название страницы, чтобы он не собирал всё подряд, но это пока не реализовано.