Шаблон Front-End проектов

Репозиторий, служащий шаблоном для начала работ над Front-End проектами

Компиляция и сборка осуществляется с помощью Gulp

Требования

Для корректной работы шаблона в системе должны быть глобально установлены bower и nodejs (вместе с npm)

Установка шаблона

$ git clone https://github.com/cotang/fuel-technology.git folder-name
$ cd folder-name
$ npm i -D
$ bower i

По окончанию выполнения будут установлены все необходимые пакеты и их зависимости. По умолчанию в шаблоне используется сетка на flexbox, построенная по типу сетки из Bootstrap 4.

Компиляция с помощью Gulp

После установки шаблона можно приступать к работе над проектом.

Задачи Gulp

$ gulp pug - сборка HTML проекта с использованием препроцессора pug
$ gulp sass - компилиция Sass (в вариации scss)
$ gulp js - сборка JavaScript проекта
$ gulp img - оптимизация изображений
$ gulp png-sprites - создание PNG-спрайта
$ gulp svg-sprites - создание SVG-спрайта
$ gulp fonts - копирование файлов шрифтов
$ gulp clean - очистка каталога build/
$ gulp browserSync - запуск локального веб-сервера тестирования в разных браузерах
$ gulp deploy- размещение скомпилированного проекта на Github Pages
$ gulp build - полная сборка проекта
$ gulp watch - запуск задачи browserSync и отслеживания изменений
$ gulp default - запуск задачи watch

Development и production

Для ускорения разработки некоторые задачи в gulp инициализируются только для финальной стадии (production). для переключения между типами выполнения задач в начале gulpfile.js в разделе Set Env раскомментировать требуемую стадию и закомментировать неактивную стадию.

Общая концепция

src/ - каталог для размещения рабочих файлов (pug-шаблоны, scss-файлы, файлы и библиотеки js, изображения для сборки в спрайты и т.д.)
build/ - каталог для размещения скомпилированной верстки
design/ - (если есть) каталог для локального хранения файлов макета. Содержимое не отслеживается в Git и не будет в последствии залито в репозиторий

Вся работа осуществляется в каталоге src/. В каталоге build/ никакие изменения напрямую в файлы не вносятся. Back-End разработчикам и/или Заказчиками передается содержимое каталога build/ или предоставляется доступ к репозиторию проекта.

Концепции работы

HTML-разметка

Задача $ gulp pug

Разметка осуществляется с помощью препроцессора pug (ex jade) Страницы, которые необходимо сверстать размещаются в каталоге src/html/ (например index.pug). В коде каждой страницы первой строкой подключен шаблон, по которому она сверстана, включающий общие элементы (например, общий header, footer, модальные окна и т.д.). В тело страницы помещаются отличающиеся блоки содержания.

src/html/partials/components/ - файлы отдельных pug-компонентов. Первой строкой кода файлов компонентов должен быть подключен плагин bemto. Добавляются в код файла страницы через include
src/html/partials/templates/ - файлы шаблонов pug-страниц.
src/html/partials/abstracts/bemto - плагин bemto для более удобного присваивания классов сущностям, в соответствии с методологией БЭМ (синтаксис bemto рассмотрен ниже)
src/html/partials/abstracts/mixins - файлы миксинов, использующихся в компонентах pug-страниц (в компоненте должен быть прописан путь до используемого миксина)
src/html/partials/abstracts/_variables - pug-переменные (на данный момент общий файл переменных не используется, при необходимости переменные задаются в каждом компоненте отдельно)

БЭМ

В проектах используется методология БЭМ. Используемый синтаксис наименования сущностей: блок - .block элемент блока - .block__element модификатор блока - .block--modificator модификатор элемента блока - .block__element--modificator

Bemto

Для того чтобы задать блок, дописываем перед тэгом +b.
Для того чтобы задать элемент, относящийся к блоку, дописываем перед дочерними сущностями блока +e. В соответствии с синтаксисом pug, вложенность элементов выражается через отступы, то есть по количеству отступов bemto сам определяет к какому блоку относится элемент. Исключение - связь теряется, если в коде между блоком и элементом появляется конструкция include
Для того чтобы задать модификатор, необходимо дописать к блоку/элементу модифицирующее слово через разделитель, к примеру --mod. Если требуется второй модификатор, он добавляется через точку ., например +b.block--green.--small.
Если тэг отличается от div для блочных и span для строчных элементов, необходимо прописывать его между буквой и названием класса, например +b.SECTION.page или +e.A.link(href="#")
Атрибуты пишутся в скобках после имени класса. Настройки bemto (в т.ч. разделителей) здесь src/html/partials/abstracts/bemto/lib/settings.pug

Компиляция Sass

Задача $ gulp sass

Файл src/css/styles.scss является диспетчером подключений для всех прочих scss-файлов.
Секция Third party предназначена для подключения scss/css файлов сторонних библиотек и фреймворков.
Секция Abstracts - для подключения общих частей стилей. Секция Base - для подключения базовых стилей и типографики. Секция Components - для подключения компонентов собственных стилей.

При компиляции происходит объединение всех файлов, компиляция в CSS, форматирование стиля кодирования, добавление вендорных префиксов, минификация (+ при необходимости запись sourcemaps). Итоговые файлы стилевых таблиц помещаются в каталог build/css (style.css, style.min.css, (style.min.css.map))

Компиляция JavaScript

Задача $ gulp js в двух вариантах

Файлы js подключаются через require и browserify.
Если библиотека jquery подключается не на фронтэнде и необходимо чтобы в итоговом script.min.js ее не было, require использовать нельзя. В таком случае все необходимые файлы js помещаются в папку src/js/. Подключение скриптов происходит по алфавиту, поэтому собственный скрипт назван z-script. На данный момент этот вариант считается основным для проектов.

При компиляции происходит объединение всех файлов, минификация (+ при необходимости запись sourcemaps). Итоговый файл помещается в каталог build/js (script.min.js, (script.min.js.map))

При использовании варианта 1, необходимо отключить подгрузку jquery из CDN в head. Установить необходимые js-библиотеки (предпочтительно через bower) и подключить их в требуемом порядке в собственном js-файле.

window.$ = window.jQuery =  require('jquery');
window.slick =              require('./vendor/bower/slick');
window.inputmask =          require('./vendor/bower/jquery.inputmask.bundle');

Оптимизация изображений

Задача $ gulp img

Все контентные изображения, а также любые изображения, которые не должны быть объединены в спрайт, необходимо помещать в каталог src/img/.
При выполнении задачи все изображения из этого каталога оптимизируются.
Итоговые файлы помещаются в каталог build/img/

Создание PNG-спрайта

Задача $ gulp png-sprites

Все изображения, которые необходимо собрать в спрайт (например, png-файлы иконок) необходимо помещать в каталог src/img/png-sprites/.
Итоговый спрайт png-sprite.png будет оптимизирован и помещен в каталог build/img/.
Также будет создан или дополнен файл src/css/partials/abstracts/_png-sprite.scss, содержащий примеси (mixins) для вызова изображений спрайта (должен быть подключен в основном файле style.scss) Имя примеси (mixin) всегда выглядит как @s-filename, где filename - имя изображения, добавленного к спрайту.

Пример работы с спрайтом описан в файле _png-sprite.scss.

Создание SVG-спрайта

Задача $ gulp svg-sprites

Все SVG, которые необходимо собрать в спрайт (например, svg-файлы иконок) необходимо помещать в каталог src/img/svg-sprites/.
Итоговый спрайт svg-sprite.svg будет оптимизирован и помещен в каталог build/img/, при этом будет создан дополнительный спрайт. Для использования svg-спрайта через localstorage, нужно подключить файл svg.js (при каждом изменении svg нужно менять номер ревизии в этом файле, т.к. спрайт кэшируется) Созданный svg-спрайт будет инлайново вставлен в разметку после открывающегося тега body со свойством 'display: none'. Использование спрайта - вставляем разметку спрайта в блок:

svg(width='30', height='30')
  use(xmlns:xlink='http://www.w3.org/1999/xlink', xlink:href='#icon')

Вручную ставим width и height у svg, и прописываем xlink:href='#icon', где icon - название картинки. Таким образом мы можем редактировать свойства svg-объекта через css.

Обработка файлов шрифтов

Задача $ gulp fonts

Файлы используемых шрифтов необходимо размещать в каталоге src/styles/fonts.
При обработке шрифты будут скопированы в каталог build/css/fonts.
Важно корректно прописать к ним пути в файле Less, описывающим типографику.

Sourcemaps

В gulpfile.js команды для создания sourcemaps закомментированы. При необходимости их можно раскомментировать.

Очистка каталога сборки

Задача $ gulp clean

При выполнении задачи полностью удаляется содержимое каталога build/

Полная сборка проекта

Задача $ gulp build

При запуске задачи выполняются задачи clean, затем параллельно pug, png-sprites, svg-sprites, img, sass, js, fonts.
В итоге выполнения в каталоге build/ формируется полная сборка проекта с нуля.

Livereload и синхронизация между браузерами

Задача $ gulp BrowserSync

При выполнении задачи запускается локальный веб-сервер BrowserSync и открыватся index.html проекта.

Подробнее о BrowserSync

Сервер использует каталог build/ в качестве корня проекта.

При запуске формируются следующие данные:

[App Front-End] Access URLs:
 ----------------------------------------------
       Local: http://localhost:8000 // локальный URL проекта
    External: http://192.168.0.100:8000 // внешний (в пределах локальной сети) URL проекта (по нему можно открыть на других устройствах в той же сети)
      Tunnel: https://iuvrvzmmli.localtunnel.me // Туннель - защищенный уникальный URL, можно дать человеку на другом конце мира и он также будет видеть все обновления в реальном времени
 ----------------------------------------------
          UI: http://localhost:3001 // локальный URL WebUI BrowserSync
 UI External: http://192.168.0.100:3001 // внешний (в пределах сети) URL WebUI BrowserSync
 ----------------------------------------------
[App Front-End] Serving files from: ./build // корень проекта для BrowserSync

Публикация на Github Pages

Задача $ gulp deploy

При запуске задачи будет создана ветка gh-pages и в нее залито текущее состояние каталога build/.

Подробнее о GitHub Pages

Отслеживание изменений

Задача $ gulp watch

При запуске сначала выполняется задача $ gulp BrowserSync, затем при изменении или добавлении в каталоге src/ каких
либо файлов, автоматически запускается соответсвующая задача по их обработке.

Настройки шаблона

В файле gulpfile.js в разделе 'Path settings' задаются пути к каталогам размещения обработанных файлов (итогов сборки), исходных файлов и путей для отслеживания изменений.

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