Gulp — сборка MaxGraph

Используется Gulp 5. Тестировалось на node.js 20.12.2

Начало работы

Для работы с данной сборкой в новом проекте, склонируйте все содержимое репозитория
git clone <this repo> Затем, находясь в корне проекта, запустите команду npm i, которая установит все находящиеся в package.json зависимости. После этого вы можете использовать любую из предложенных команд сборки (подробнее - ниже, в разделе npm-скрипты).

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

├── gulp/                         # Все настройки Gulp-сборки, разделенные по отдельным файлам
├── src/                          # Исходники
│   ├── js                        # Скрипты
│   │   └── main.js               # Главный скрипт
│   │   ├── _vars.js              # файл с переменными проекта
│   │   ├── _functions.js         # файл с готовыми функциями на js
│   │   ├── _components.js        # файл с подключениями компонентов
│   │   ├── components            # js-компоненты
│   ├── scss                      # Стили сайта (препроцессор sass в scss-синтаксисе)
│   │   └── main.scss             # Главный файл стилей
│   │   └── vendor.scss           # Файл для подключения стилей библиотек из папки vendor
│   │   └── _fonts.scss           # Файл для подключения шрифтов (можно использовать миксин)
│   │   └── _mixins.scss          # Файл для подключения миксинов из папки mixins
│   │   └── _vars.scss            # Файл для написания css- или scss-переменных
│   │   └── _settings.scss        # Файл для написания глобальных стилей
│   │   ├── components            # scss-компоненты
│   │   ├── mixins                # папка для сохранения готовых scss-компонентов
│   │   ├── vendor                # папка для хранения локальных css-стилей библиотек
│   ├── partials                  # папка для хранения html-частей страницы
│   ├── img                       # папка для хранения картинок
│   │   ├── svg                   # специальная папка для преобразования svg в спрайт
│   ├── resources                 # папка для хранения иных ассетов - php, видео-файлы, favicon и т.д.
│   │   ├── fonts                 # папка для хранения шрифтов в формате woff2
│   └── index.html                # Главный html-файл
└── gulpfile.js                   # Результирующий файл с настройками Gulp
└── package.json                  # файл с настройками сборки и установленными пакетами
└── .editorconfig                 # файл с настройками форматирования кода
└── .ecrc                         # файл с настройками пакета editorconfig-checker (исключает ненужные папки)
└── .stylelintrc.json             # файл с настройками stylelint
└── .stylelintignore              # файл с исключениями для stylelint
└── .htmlhintrc                   # файл с настройками htmlhint
└── README.md                     # документация сборки

npm-скрипты
Работа с html
Работа с CSS
Работа с JavaScript
Работа со шрифтами
Работа с изображениями
Работа с иными ресурсами
Типограф
Рекомендуемые плагины VS Code
Локальные сниппеты
Готовые модули
Изменения в версии 3.0.0 (от 21.04.2024)
Заключение

npm-скрипты

Вызывать различные Gulp-задачи нужно только через npm-команды, т.к. обычные Gulp-команды работают неполноценно.

npm run stylelint — команда, запускающая проверку всех scss-файлов на соответствие stylelint.
npm run style-fix — проверка и одновременный фикс scss-файлов на соответствие stylelint. Лично я сам все исправляю вручную, боясь, что автофикс что-то сломает.
npm run code — команда, запускающая проверку всех файлов на соответствие editorconfig.
npm run dev — базовая команда, которая запускает Gulp в режиме разработки.
npm run build — команда, запускающая продакшн-версию сборки. В эту команду также включена проверка stylelint и editorconfig, и если файлы не соответсвуют правилам - ваш проект не соберется.
npm run cache — команда, которую стоит запускать после npm run build__, если вам нужно загрузить новые файлы на хостинг без кэширования.
npm run backend — команда для бэкенд-сборки проекта. Она лишена ненужных вещей из dev-сборки, но не сжата, для удобства бэкендера.
npm run zip — команда собирает ваш готовый код в zip-архив.

Работа с html

Благодаря плагину gulp-file-include вы можете разделять html-файл на различные шаблоны, которые должны храниться в папке partials. Удобно делить html-страницу на секции.

Для вставки html-частей в главный файл используйте @include('partials/filename.html')

Если вы хотите создать многостраничный сайт - копируйте index.html, переименовывайте как вам нужно, и используйте.

При использовании команды npm run build, вы получите минифицированный html-код в одну строку для всех html-файлов.

Работа с CSS

В сборке используется препроцессор sass в синтаксисе scss.

Стили, написанные в components, следует подключать в main.scss. ВАЖНО: Обязательно удалить стили, которые написаны в main.scss для .page__body.

Чтобы подключить сторонние css-файлы (библиотеки) - положите их в папку vendor и подключите в файле _vendor.scss

Если вы хотите создать свой миксин - делайте это в папке mixins, а затем подключайте в файл _mixins.scss.

Если вы хотите использовать scss-переменные - подключите _vars.scss также в main.scss или в любое другое место, где он нужен, но обязательно удалите :root.

Для подключения css-файлов используйте директиву @import

В итоговой папке app/css создаются два файла:
main.css - для стилей страницы,
vendor.css - для стилей всех библиотек, использующихся в проекте.

При использовании команды npm run build, вы получите минифицированный css-код в одну строку для всех css-файлов.

Работа с JavaScript

Для сборки JS-кода используется webpack.

JS-код лучше делить на компоненты - небольшие js-файлы, которые содержат свою, изолированную друг от друга реализацию. Такие файлы помещайте в папку components, а потом импортируйте в файл _components.js

В файле vars.js должны храниться базовые переменные проекта, вроде нахождения элементов и т.д.

В файле main.js ничего менять не нужно, он сделан просто как результирующий.

Подключать библиотеки в сборку можно только с помощью npm. Для этого установите нужный пакет с помощью его команды, создайте в папке components файлик, импортируйте туда библиотеку и работайте с ней. Не забудьте импортировать этот файл в файл _components.js.

При использовании команды npm run build, вы получите минифицированный js-код в одну строку для всех js-файлов.

Работа со шрифтами

В сборке реализована поддержка только формата woff2, т.к. другие форматы шрифтов не актуальны (это значит, что в миксине подключения шрифтов используется только данный формат).

Загружайте файлы woff2 в папку resources/fonts, а затем вызывайте миксин @font-face в файле _fonts.scss.

Также не забудьте прописать эти же шрифты в <link preload> в html.

Работа с изображениями

Любые изображения, кроме favicon кладите в папку img.

Если вам нужно сделать svg-спрайт, кладите нужные для спрайта svg-файлы в папку img/svg. При этом, такие атрибуты как fill, stroke, style будут автоматически удаляться. Иные svg-файлы просто оставляйте в папке img.

При использовании команды npm run build, вы получите минифицированные изображения в итоговой папке img.

В сборке доступна поддержка webp формата. Подключить его вы можете через тег picture. Для background можно использовать обычные jpg или png, либо использовать image-set там, где это возможно.

Работа с иными ресурсами

Любые ресурсы (ассеты) проекта, под которые не отведена соответствующая папка, должны храниться в папке resources. Это могут быть видео-файлы, php-файлы (как, например, файл отправки формы), favicon и прочие.

Типограф

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

Локальные сниппеты

Для удобства и быстроты разработки были добавление локальные сниппеты (находятся в папке .vscode/snippets), которые работают благодаря плагину, описанному выше. Все сниппеты начинаются с префикса g-. В сниппетах пока только html (быстрое создание навигации, соцсетей, корректного тега picture с webp и avif и так далее).

Некоторые сниппеты тесно связаны с scss-миксинами, например кнопка-бургер. Сниппет g-burger создаст вам html-разметку бургера, а подключение миксина @include burger добавит для него стили, что крайне удобно.

Готовые модули

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

Внимание! В файле functions.js описаны лишь подключения всех нужных модулей. Рекомендуется использовать все это в отдельных файлах. Например, если вам нужно создать модальное окно, создаете файл modal.js в папке components, подключаете его в файл components.js и уже в файле modal.js используете код подключения.

Бургер меню

Вы можете очень быстро добавить рабочий бургер к себе на страницу, для этого нужно:

В html вызвать сниппет g-burger
На ваше потенциальное меню в html добавить атрибут data-menu
В scss вызвать миксин burger

.burger { @include burger }

Зайти в файл js/_functions.js и скопировать строку с подключением js-файла бургера, после подключить в вашем файле для бургера.
Настроить стили показа меню под себя с помощью класса menu--active

Модальное окно

Вы можете очень быстро добавить рабочее модальное окно к себе на страницу, для этого нужно:

В html вызвать сниппет g-graph-btn. Он создаст кнопку для модального окна, ваша задача лишь заполнить атрибут data-graph-path
Далее вызвать сниппет g-graph-modal. Он создаст базовую разметку окна. Ваша задача - сделать окно по макету, заполнить контент и обязательно обозначить атрибут data-graph-target с тем же значением, что и у data-graph-path
Зайти в файл vendor.scss и раскомментировать строку с подключением файла graph-modal.min.css
Зайти в файл js/_functions.js и скопировать строку с импортом и подключением библиотеки GraphModal, после подключить в вашем файле для модального окна.

Управление скроллом

Вы можете отключать\включать скролл на странице (работает даже на iPhone). Для этого нужно:

Зайти в файл js/_functions.js и скопировать строку с импортом функций disableScroll, enableScroll. После подключить в вашем файле для отключения/включения скролла. Важно!. Если на странице присутствуют блоки с фиксированным позиционированием (например, шапка), добавьте ей класс fixed-block, чтобы этот блок не прыгал при отключении скролла.

Табы

Вы можете очень быстро добавить рабочие табы к себе на страницу, для этого нужно:

В html вызвать сниппет g-tabs. Он создаст разметку для табов, ваша задача лишь заполнить атрибут data-tabs
Для класса .tabs вызвать миксин tabs в scss (или же использовать подключение скрипта библиотеки из npm в файле vendor.scss)
Зайти в файл js/_functions.js и скопировать строку с импортом и подключением библиотеки GraphTabs, после подключить в вашем файле для табов.

Валидация и отправка данных на почту

Вы можете быстро настроить валидацию и отправку данных на почту. Как это использовать:

Создать форму, указав у нее уникальный класс. Также указать уникальные классы для полей ввода.

Создать массив, в котором будут переданы правила плагина just-validate, например:

const rules1 = [
{
ruleSelector: '.input-name',
rules: [
  {
    rule: 'minLength',
    value: 3
  },
  {
    rule: 'required',
    value: true,
    errorMessage: 'Заполните имя!'
  }
]
},
{
ruleSelector: '.input-tel',
tel: true,
telError: 'Введите корректный телефон',
rules: [
  {
    rule: 'required',
    value: true,
    errorMessage: 'Заполните телефон!'
  }
]
},
];

ВАЖНО. Если в вашей форме есть поле с телефоном, обязательно пропишите в массиве с правилами новые поля: tel: true, telError: 'Ошибка при вводе телефона'.

Подключить функцию validateForms, она находится в functions.js, передав туда три параметра: 3.1. Строку с классом формы 3.2. Массив правил 3.3. Если нужно, можно создать свою функцию, которая выполнится после отправки, тогда ее тоже нужно будет передать как аргумент функции validateForms.

Также эта функция поддерживает работы с множественными чекбоксами/радиокнопками. Третьим параметром в функцию можно передать массив с настройками:

const checks = [
{
selector: ".checkbox-group",
errorMessage: "Выберите чекбоксы",
}
];

Пример кода:


import { validateForms } from './functions/validate-forms';
const checks = [
{
selector: ".checkbox-group",
errorMessage: "Выберите чекбоксы",
}
];
const rules1 = [
{
ruleSelector: '.input-name',
rules: [
  {
    rule: 'minLength',
    value: 3
  },
  {
    rule: 'required',
    value: true,
    errorMessage: 'Заполните имя!'
  }
]
},
{
ruleSelector: '.input-tel',
tel: true,
telError: 'Введите корректный телефон',
rules: [
  {
    rule: 'required',
    value: true,
    errorMessage: 'Заполните телефон!'
  }
]
},
];

const afterForm = () => { console.log('Произошла отправка, тут можно писать любые действия'); };

validateForms('.form-1', rules1, checks, afterForm);


### Throttle-функция

Чтобы сгладить управление частоиспользуемыми событиями, вы можете использовать готовую функцию __throttle__. Для этого нужно:

1. В нужном месте импортировать функцию __throttle()__
2. Написать нужную вам функцию, например, __func()__
3. Создать переменную, в которую поместить вызов вашей фукнции внутри throttle, например: `let f = throttle(func)`
4. Использовать эту переменную как функцию в вызове, например: `window.addEventListener('resize', f)`

### Фикс фулскрин блоков

Нередко блоки с высотой 100vh вызывают проблемы в мобильных браузерах. Решить это поможет готовый модуль fix-fullheight:

1. Раскомментируйте строку с импортом файла __fix-fullheight.js__
2. Назначьте на нужный вам блок высоту не 100vh, а `var(--vh)`

Для этой функции используется ранее упомянутый throttle. Вы можете убрать его, либо изменить время внутри файла __fix-fullheight.js__.

### Получение высоты шапки

Иногда требуется получить точную высоту шапки, если она сделана абсолютным или фиксированным позиционированием, и для этого есть функция `getHeaderHeght`. Как ее использовать:

1. Раскомментируйте строку с импортом файла __header-height.js__
2. Используйте css-переменную `--header-height` в нужном вам месте

Необязательно использовать функции именно в файле __functions__, делайте как удобно вам.

### Кастомный скролл

Для реализации кастомного скролла в сборку установлен плагин __simplebar.js__. Как его использовать:

1. Раскомментируйте строку с импортом плагина __simplebar__
2. Добавьте нужному блоку максимальную высоту и атрибут `data-simplebar`

### Функции определения вьюпорта

Вы можете запускать скрипты на определенной ширине (пока что поддержка ресайза не реализована) с помощью готовых функций `isMobile()`, `isTablet()`, `isDesktop()`. Для этого нужно лишь подключить нужную из них из файла, а затем использовать внутри условия `if`.

### Тултипы

Вы можете быстро создать рабочий, доступный тултип, который к тому же будет сам рассчитывать отступы с помощью js. Как это использовать:

1. В html вызвать сниппет `g-tooltip`. Он создаст кнопку для модального окна, ваша задача лишь заполнить атрибуты `aria-describedby` и `id`.
2. Далее нужно подключить тултипы (код в файле _functions.js_), и вместо el передать id или class кнопки тултипа, а вместо tooltip передать id или class самого тултипа.
3. После этого можете стилизовать тултип как вам угодно.

### Слайдер

Вы можете быстро создать рабочий swiper-слайдер. Как это использовать:

1. В html вызвать сниппет `g-swiper`. Он создаст базовую структуру свайпер-слайдера, вам нужно добавить свой класс для свайпер-контейнера.
2. Раскомментировать строку с подключением стилей в файле _vendor.scss_
3. Подключить сам свайпер (код в файле _functions.js_) и использовать его, следуя документации.

### Анимации по скроллу

Вы можете быстро набросать анимаций по скроллу с помощью плагина. Как это использовать:

1. Подключить код библиотеки AOS.js (код в файле _functions.js_) и инициализировать его.
2. С помощью атрибутов из документации плагина вызывать те или иные анимации, или написать свою.

### Параллакс по скроллу

Вы можете быстро набросать параллакс элементов по скроллу с помощью плагина. Как это использовать:

1. Подключить код библиотеки rellax.js (код в файле _functions.js_) и инициализировать его, передав класс элемента (элементов).
2. Задать этот класс нужным элементам, а также использовать атрибуты из документации для кастомизации анимаций.

### Свайпы на мобильных устройствах

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

1. Подключить код библиотеки swiped-events.js (код в файле _functions.js_).
2. Использовать различные события из библиотеки плагина.

### Миксин для flex-расстановки элементов.

В последней версии сборки я добавил миксин flex-layout (можно найти в папке mixins), в котором реализована типичная сетка для карточек. Вы можете выбирать нужные вам настройки, чтобы сделать сетку быстро и без проблем. Например:

```html
<div class="cards">
  <div class="cards__item">Текст</div>
  <div class="cards__item">Текст</div>
  <div class="cards__item">Текст</div>
  <div class="cards__item">Текст</div>
  <div class="cards__item">Текст</div>
  <div class="cards__item">Текст</div>
</div>

$options: (
  parentClass: "cards",
  itemsClass: "cards__item",
  desktopGap: 30px,
  desktopElems: 3,
  tablet: "1024px",
  tabletElems: 2,
  tabletGap:  30px,
  mobile: "600px",
  mobileElems: 1,
  mobileGap: 20px
);

@include flex-layout($options);

В опциях можно выбрать класс-родитель (или же флекс-контейнер, класс для потомков, какой у них будет отступ, на каких разрешениях будет меняться кол-во элементов).

Изменения в версии 3.0.0 (от 21.04.2024)

Версия Gulp изменена на пятую.
Обновлены все нужные для работы пакеты.
Теперь сборка разделена на отдельные файлы, которые хранятся в папке gulp.
Удалены некоторые пакеты, такие как smooth-scroll или js-focus-visible, т.к. уже не нужны в 2024 году.
Обновлен конфиг-файл stylelint, т.к. старый не работал с новой версией.
Немного обновлены базовые стили сборки: 6.1. min-width по умолчанию теперь 360, т.к. телефонов меньше почти нет. 6.2. box-sizing: border-box задан глобально (без inherit), т.к. за все время использования сборки понял, что это лишено смысла. 6.3. по умолчанию у .page добавлено свойство scroll-behavior.
Немного обновлены скрипты и модули: 7.1. Изменился метод подключения swiper. 7.2. Изменился метод подключения Inputmask. 7.3. Изменилась функция валидации.
Все команды сборки теперь должны запускаться только через npm-команды.
Прочие мелочи.

Тестировал сборку на своих рабочих проектах, все запускалось без проблем.

Заключение

Спасибо всем, кто использует сборку! Если вы заметили какую-либо ошибку, пришлите пожалуйста issue с подробным описанием проблемы, я все смотрю и постараюсь решить. Спасибо!

maxdenaro / gulp-maxgraph

readme