"
148 | ],
149 | "description": "Snippet for basic tabs structure"
150 | },
151 | "transparent video (need special video-file)": {
152 | "prefix": "g-tr-video",
153 | "body": [
154 | ""
158 | ],
159 | "description": "Snippet for transparent video"
160 | }
161 | }
162 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Gulp — сборка MaxGraph
2 |
3 | > Используется Gulp 5. Тестировалось на node.js 20.12.2
4 |
5 | ## Начало работы
6 |
7 | Для работы с данной сборкой в новом проекте, склонируйте все содержимое репозитория
8 | `git clone `
9 | Затем, находясь в корне проекта, запустите команду `npm i`, которая установит все находящиеся в package.json зависимости.
10 | После этого вы можете использовать любую из предложенных команд сборки (подробнее - ниже, в разделе __npm-скрипты__).
11 |
12 | ## Структура папок и файлов
13 |
14 | ```
15 | ├── gulp/ # Все настройки Gulp-сборки, разделенные по отдельным файлам
16 | ├── src/ # Исходники
17 | │ ├── js # Скрипты
18 | │ │ └── main.js # Главный скрипт
19 | │ │ ├── _vars.js # файл с переменными проекта
20 | │ │ ├── _functions.js # файл с готовыми функциями на js
21 | │ │ ├── _components.js # файл с подключениями компонентов
22 | │ │ ├── components # js-компоненты
23 | │ ├── scss # Стили сайта (препроцессор sass в scss-синтаксисе)
24 | │ │ └── main.scss # Главный файл стилей
25 | │ │ └── vendor.scss # Файл для подключения стилей библиотек из папки vendor
26 | │ │ └── _fonts.scss # Файл для подключения шрифтов (можно использовать миксин)
27 | │ │ └── _mixins.scss # Файл для подключения миксинов из папки mixins
28 | │ │ └── _vars.scss # Файл для написания css- или scss-переменных
29 | │ │ └── _settings.scss # Файл для написания глобальных стилей
30 | │ │ ├── components # scss-компоненты
31 | │ │ ├── mixins # папка для сохранения готовых scss-компонентов
32 | │ │ ├── vendor # папка для хранения локальных css-стилей библиотек
33 | │ ├── partials # папка для хранения html-частей страницы
34 | │ ├── img # папка для хранения картинок
35 | │ │ ├── svg # специальная папка для преобразования svg в спрайт
36 | │ ├── resources # папка для хранения иных ассетов - php, видео-файлы, favicon и т.д.
37 | │ │ ├── fonts # папка для хранения шрифтов в формате woff2
38 | │ └── index.html # Главный html-файл
39 | └── gulpfile.js # Результирующий файл с настройками Gulp
40 | └── package.json # файл с настройками сборки и установленными пакетами
41 | └── .editorconfig # файл с настройками форматирования кода
42 | └── .ecrc # файл с настройками пакета editorconfig-checker (исключает ненужные папки)
43 | └── .stylelintrc.json # файл с настройками stylelint
44 | └── .stylelintignore # файл с исключениями для stylelint
45 | └── .htmlhintrc # файл с настройками htmlhint
46 | └── README.md # документация сборки
47 | ```
48 |
49 | ## Оглавление
50 | 1. [npm-скрипты](#npm-скрипты)
51 | 2. [Работа с html](#работа-с-html)
52 | 3. [Работа с CSS](#работа-с-css)
53 | 4. [Работа с JavaScript](#работа-с-javascript)
54 | 5. [Работа со шрифтами](#работа-со-шрифтами)
55 | 6. [Работа с изображениями](#работа-с-изображениями)
56 | 7. [Работа с иными ресурсами](#работа-с-иными-ресурсами)
57 | 8. [Типограф](#типограф)
58 | 9. [Рекомендуемые плагины VS Code](#рекомендуемые-плагины-для-vs-code)
59 | 10. [Локальные сниппеты](#локальные-сниппеты)
60 | 11. [Готовые модули](#готовые-модули)
61 | 12. [Изменения в версии 3.0.0 (от 21.04.2024)](#изменения-в-версии-300-от-21042024)
62 | 13. [Заключение](#заключение)
63 |
64 | ## npm-скрипты
65 |
66 | Вызывать различные Gulp-задачи нужно __только__ через npm-команды, т.к. обычные Gulp-команды работают неполноценно.
67 |
68 | * `npm run stylelint` — команда, запускающая проверку всех scss-файлов на соответствие stylelint.
69 | * `npm run style-fix` — проверка и одновременный фикс scss-файлов на соответствие stylelint. Лично я сам все исправляю вручную, боясь, что автофикс что-то сломает.
70 | * `npm run code` — команда, запускающая проверку всех файлов на соответствие editorconfig.
71 | * `npm run dev` — базовая команда, которая запускает Gulp в режиме разработки.
72 | * `npm run build` — команда, запускающая продакшн-версию сборки. В эту команду также включена проверка stylelint и editorconfig, и если файлы не соответсвуют правилам - ваш проект не соберется.
73 | * `npm run cache` — команда, которую стоит запускать после npm run build__, если вам нужно загрузить новые файлы на хостинг без кэширования.
74 | * `npm run backend` — команда для бэкенд-сборки проекта. Она лишена ненужных вещей из dev-сборки, но не сжата, для удобства бэкендера.
75 | * `npm run zip` — команда собирает ваш готовый код в zip-архив.
76 |
77 | ## Работа с html
78 |
79 | Благодаря плагину __gulp-file-include__ вы можете разделять html-файл на различные шаблоны, которые должны храниться в папке __partials__. Удобно делить html-страницу на секции.
80 |
81 | > Для вставки html-частей в главный файл используйте `@include('partials/filename.html')`
82 |
83 | Если вы хотите создать многостраничный сайт - копируйте __index.html__, переименовывайте как вам нужно, и используйте.
84 |
85 | При использовании команды `npm run build`, вы получите минифицированный html-код в одну строку для всех html-файлов.
86 |
87 | ## Работа с CSS
88 |
89 | В сборке используется препроцессор __sass__ в синтаксисе __scss__.
90 |
91 | Стили, написанные в __components__, следует подключать в __main.scss__.
92 | __ВАЖНО:__ Обязательно удалить стили, которые написаны в __main.scss__ для `.page__body`.
93 |
94 | Чтобы подключить сторонние css-файлы (библиотеки) - положите их в папку __vendor__ и подключите в файле ___vendor.scss__
95 |
96 | Если вы хотите создать свой миксин - делайте это в папке __mixins__, а затем подключайте в файл ___mixins.scss__.
97 |
98 | Если вы хотите использовать scss-переменные - подключите ___vars.scss__ также в main.scss или в любое другое место, где он нужен, но обязательно удалите __:root__.
99 |
100 | > Для подключения css-файлов используйте директиву `@import`
101 |
102 | В итоговой папке __app/css__ создаются два файла: __main.css__ - для стилей страницы, __vendor.css__ - для стилей всех библиотек, использующихся в проекте.
103 |
104 | При использовании команды `npm run build`, вы получите минифицированный css-код в одну строку для всех css-файлов.
105 |
106 | ## Работа с JavaScript
107 |
108 | Для сборки JS-кода используется webpack.
109 |
110 | JS-код лучше делить на компоненты - небольшие js-файлы, которые содержат свою, изолированную друг от друга реализацию. Такие файлы помещайте в папку __components__, а потом импортируйте в файл ___components.js__
111 |
112 | В файле __vars.js__ должны храниться базовые переменные проекта, вроде нахождения элементов и т.д.
113 |
114 | В файле __main.js__ ничего менять не нужно, он сделан просто как результирующий.
115 |
116 | Подключать библиотеки в сборку можно только с помощью npm. Для этого установите нужный пакет с помощью его команды, создайте в папке __components__ файлик, импортируйте туда библиотеку и работайте с ней. Не забудьте импортировать этот файл в файл ___components.js__.
117 |
118 | При использовании команды `npm run build`, вы получите минифицированный js-код в одну строку для всех js-файлов.
119 |
120 | ## Работа со шрифтами
121 |
122 | В сборке реализована поддержка только формата __woff2__, т.к. другие форматы шрифтов не актуальны (это значит, что в миксине подключения шрифтов используется только данный формат).
123 |
124 | Загружайте файлы __woff2__ в папку __resources/fonts__, а затем вызывайте миксин `@font-face` в файле ___fonts.scss__.
125 |
126 | Также не забудьте прописать эти же шрифты в `` в html.
127 |
128 | ## Работа с изображениями
129 |
130 | Любые изображения, кроме __favicon__ кладите в папку __img__.
131 |
132 | Если вам нужно сделать svg-спрайт, кладите нужные для спрайта svg-файлы в папку __img/svg__. При этом, такие атрибуты как fill, stroke, style будут автоматически удаляться. Иные svg-файлы просто оставляйте в папке __img__.
133 |
134 | При использовании команды `npm run build`, вы получите минифицированные изображения в итоговой папке __img__.
135 |
136 | В сборке доступна поддержка __webp__ формата. Подключить его вы можете через тег `picture`. Для background можно использовать обычные __jpg__ или __png__, либо использовать `image-set` там, где это возможно.
137 |
138 | ## Работа с иными ресурсами
139 |
140 | Любые ресурсы (ассеты) проекта, под которые не отведена соответствующая папка, должны храниться в папке __resources__. Это могут быть видео-файлы, php-файлы (как, например, файл отправки формы), favicon и прочие.
141 |
142 | ## Типограф
143 |
144 | Для корректного отображения текста на странице был подключен плагин типограф, которые автоматически добавит неразрывные пробелы и иные символы, чтобы текст везде отображался по всем правилам русского языка.
145 |
146 | ## Рекомендуемые плагины для VS Code
147 |
148 | Я рекомендую использовать именно VS Code, и в сборке реализовано взаимодействие именно с этим редактором. Так, при открытии папки со сборкой в VS Code, редактор предложит вам ранее не установленные плагины, которые подойдут для корректной работы сборки.
149 |
150 | Самый важный из них – __projects snippets__, этот плагин "включает" локально написанные сниппеты для сборки. Данный плагин не всегда работает корректно, в этом случае просто перезапустите VS Code.
151 |
152 | ## Локальные сниппеты
153 |
154 | Для удобства и быстроты разработки были добавление локальные сниппеты (находятся в папке .vscode/snippets), которые работают благодаря плагину, описанному выше. Все сниппеты начинаются с префикса __g-__. В сниппетах пока только html (быстрое создание навигации, соцсетей, корректного тега picture с webp и avif и так далее).
155 |
156 | Некоторые сниппеты тесно связаны с scss-миксинами, например кнопка-бургер. Сниппет __g-burger__ создаст вам html-разметку бургера, а подключение миксина __@include burger__ добавит для него стили, что крайне удобно.
157 |
158 | ## Готовые модули
159 |
160 | В сборке присутствуют готовые, часто-используемые модули под различные задачи. Ниже будет перечислен уже добавленный функционал.
161 |
162 | __Внимание!__ В файле _functions.js_ описаны лишь подключения всех нужных модулей. Рекомендуется использовать все это в отдельных файлах. Например, если вам нужно создать модальное окно, создаете файл _modal.js_ в папке components, подключаете его в файл components.js и уже в файле _modal.js_ используете код подключения.
163 |
164 | ### Бургер меню
165 |
166 | Вы можете очень быстро добавить рабочий бургер к себе на страницу, для этого нужно:
167 |
168 | 1. В html вызвать сниппет `g-burger`
169 | 2. На ваше потенциальное меню в html добавить атрибут `data-menu`
170 | 3. В scss вызвать миксин `burger`
171 |
172 | ```scss
173 | .burger { @include burger }
174 | ```
175 |
176 | 4. Зайти в файл js/_functions.js и скопировать строку с подключением js-файла бургера, после подключить в вашем файле для бургера.
177 | 5. Настроить стили показа меню под себя с помощью класса `menu--active`
178 |
179 | ### Модальное окно
180 |
181 | Вы можете очень быстро добавить рабочее модальное окно к себе на страницу, для этого нужно:
182 |
183 | 1. В html вызвать сниппет `g-graph-btn`. Он создаст кнопку для модального окна, ваша задача лишь заполнить атрибут `data-graph-path`
184 | 2. Далее вызвать сниппет `g-graph-modal`. Он создаст базовую разметку окна. Ваша задача - сделать окно по макету, заполнить контент и обязательно обозначить атрибут `data-graph-target` с тем же значением, что и у `data-graph-path`
185 | 3. Зайти в файл vendor.scss и раскомментировать строку с подключением файла graph-modal.min.css
186 | 4. Зайти в файл js/_functions.js и скопировать строку с импортом и подключением библиотеки `GraphModal`, после подключить в вашем файле для модального окна.
187 |
188 | ### Управление скроллом
189 |
190 | Вы можете отключать\включать скролл на странице (работает даже на iPhone). Для этого нужно:
191 |
192 | 1. Зайти в файл js/_functions.js и скопировать строку с импортом функций `disableScroll`, `enableScroll`. После подключить в вашем файле для отключения/включения скролла.
193 | __Важно!__. Если на странице присутствуют блоки с фиксированным позиционированием (например, шапка), добавьте ей класс `fixed-block`, чтобы этот блок не прыгал при отключении скролла.
194 |
195 | ### Табы
196 |
197 | Вы можете очень быстро добавить рабочие табы к себе на страницу, для этого нужно:
198 |
199 | 1. В html вызвать сниппет `g-tabs`. Он создаст разметку для табов, ваша задача лишь заполнить атрибут `data-tabs`
200 | 2. Для класса `.tabs` вызвать миксин `tabs` в scss (или же использовать подключение скрипта библиотеки из npm в файле vendor.scss)
201 | 4. Зайти в файл js/_functions.js и скопировать строку с импортом и подключением библиотеки `GraphTabs`, после подключить в вашем файле для табов.
202 |
203 | ### Валидация и отправка данных на почту
204 |
205 | Вы можете быстро настроить валидацию и отправку данных на почту. Как это использовать:
206 |
207 | 1. Создать форму, указав у нее уникальный класс. Также указать уникальные классы для полей ввода.
208 | 2. Создать массив, в котором будут переданы правила плагина just-validate, например:
209 | ```js
210 | const rules1 = [
211 | {
212 | ruleSelector: '.input-name',
213 | rules: [
214 | {
215 | rule: 'minLength',
216 | value: 3
217 | },
218 | {
219 | rule: 'required',
220 | value: true,
221 | errorMessage: 'Заполните имя!'
222 | }
223 | ]
224 | },
225 | {
226 | ruleSelector: '.input-tel',
227 | tel: true,
228 | telError: 'Введите корректный телефон',
229 | rules: [
230 | {
231 | rule: 'required',
232 | value: true,
233 | errorMessage: 'Заполните телефон!'
234 | }
235 | ]
236 | },
237 | ];
238 | ```
239 | __ВАЖНО__. Если в вашей форме есть поле с телефоном, обязательно пропишите в массиве с правилами новые поля: `tel: true, telError: 'Ошибка при вводе телефона'`.
240 | 3. Подключить функцию `validateForms`, она находится в _functions.js_, передав туда три параметра:
241 | 3.1. Строку с классом формы
242 | 3.2. Массив правил
243 | 3.3. Если нужно, можно создать свою функцию, которая выполнится после отправки, тогда ее тоже нужно будет передать как аргумент функции `validateForms`.
244 | 4. Также эта функция поддерживает работы с множественными чекбоксами/радиокнопками. Третьим параметром в функцию можно передать массив с настройками:
245 | ```js
246 | const checks = [
247 | {
248 | selector: ".checkbox-group",
249 | errorMessage: "Выберите чекбоксы",
250 | }
251 | ];
252 | ```
253 | Пример кода:
254 | ```js
255 | import { validateForms } from './functions/validate-forms';
256 | const checks = [
257 | {
258 | selector: ".checkbox-group",
259 | errorMessage: "Выберите чекбоксы",
260 | }
261 | ];
262 | const rules1 = [
263 | {
264 | ruleSelector: '.input-name',
265 | rules: [
266 | {
267 | rule: 'minLength',
268 | value: 3
269 | },
270 | {
271 | rule: 'required',
272 | value: true,
273 | errorMessage: 'Заполните имя!'
274 | }
275 | ]
276 | },
277 | {
278 | ruleSelector: '.input-tel',
279 | tel: true,
280 | telError: 'Введите корректный телефон',
281 | rules: [
282 | {
283 | rule: 'required',
284 | value: true,
285 | errorMessage: 'Заполните телефон!'
286 | }
287 | ]
288 | },
289 | ];
290 |
291 | const afterForm = () => {
292 | console.log('Произошла отправка, тут можно писать любые действия');
293 | };
294 |
295 | validateForms('.form-1', rules1, checks, afterForm);
296 | ```
297 |
298 | ### Throttle-функция
299 |
300 | Чтобы сгладить управление частоиспользуемыми событиями, вы можете использовать готовую функцию __throttle__. Для этого нужно:
301 |
302 | 1. В нужном месте импортировать функцию __throttle()__
303 | 2. Написать нужную вам функцию, например, __func()__
304 | 3. Создать переменную, в которую поместить вызов вашей фукнции внутри throttle, например: `let f = throttle(func)`
305 | 4. Использовать эту переменную как функцию в вызове, например: `window.addEventListener('resize', f)`
306 |
307 | ### Фикс фулскрин блоков
308 |
309 | Нередко блоки с высотой 100vh вызывают проблемы в мобильных браузерах. Решить это поможет готовый модуль fix-fullheight:
310 |
311 | 1. Раскомментируйте строку с импортом файла __fix-fullheight.js__
312 | 2. Назначьте на нужный вам блок высоту не 100vh, а `var(--vh)`
313 |
314 | Для этой функции используется ранее упомянутый throttle. Вы можете убрать его, либо изменить время внутри файла __fix-fullheight.js__.
315 |
316 | ### Получение высоты шапки
317 |
318 | Иногда требуется получить точную высоту шапки, если она сделана абсолютным или фиксированным позиционированием, и для этого есть функция `getHeaderHeght`. Как ее использовать:
319 |
320 | 1. Раскомментируйте строку с импортом файла __header-height.js__
321 | 2. Используйте css-переменную `--header-height` в нужном вам месте
322 |
323 | Необязательно использовать функции именно в файле __functions__, делайте как удобно вам.
324 |
325 | ### Кастомный скролл
326 |
327 | Для реализации кастомного скролла в сборку установлен плагин __simplebar.js__. Как его использовать:
328 |
329 | 1. Раскомментируйте строку с импортом плагина __simplebar__
330 | 2. Добавьте нужному блоку максимальную высоту и атрибут `data-simplebar`
331 |
332 | ### Функции определения вьюпорта
333 |
334 | Вы можете запускать скрипты на определенной ширине (пока что поддержка ресайза не реализована) с помощью готовых функций `isMobile()`, `isTablet()`, `isDesktop()`. Для этого нужно лишь подключить нужную из них из файла, а затем использовать внутри условия `if`.
335 |
336 | ### Тултипы
337 |
338 | Вы можете быстро создать рабочий, доступный тултип, который к тому же будет сам рассчитывать отступы с помощью js. Как это использовать:
339 |
340 | 1. В html вызвать сниппет `g-tooltip`. Он создаст кнопку для модального окна, ваша задача лишь заполнить атрибуты `aria-describedby` и `id`.
341 | 2. Далее нужно подключить тултипы (код в файле _functions.js_), и вместо el передать id или class кнопки тултипа, а вместо tooltip передать id или class самого тултипа.
342 | 3. После этого можете стилизовать тултип как вам угодно.
343 |
344 | ### Слайдер
345 |
346 | Вы можете быстро создать рабочий swiper-слайдер. Как это использовать:
347 |
348 | 1. В html вызвать сниппет `g-swiper`. Он создаст базовую структуру свайпер-слайдера, вам нужно добавить свой класс для свайпер-контейнера.
349 | 2. Раскомментировать строку с подключением стилей в файле _vendor.scss_
350 | 3. Подключить сам свайпер (код в файле _functions.js_) и использовать его, следуя документации.
351 |
352 | ### Анимации по скроллу
353 |
354 | Вы можете быстро набросать анимаций по скроллу с помощью плагина. Как это использовать:
355 |
356 | 1. Подключить код библиотеки AOS.js (код в файле _functions.js_) и инициализировать его.
357 | 2. С помощью атрибутов из документации плагина вызывать те или иные анимации, или написать свою.
358 |
359 | ### Параллакс по скроллу
360 |
361 | Вы можете быстро набросать параллакс элементов по скроллу с помощью плагина. Как это использовать:
362 |
363 | 1. Подключить код библиотеки rellax.js (код в файле _functions.js_) и инициализировать его, передав класс элемента (элементов).
364 | 2. Задать этот класс нужным элементам, а также использовать атрибуты из документации для кастомизации анимаций.
365 |
366 | ### Свайпы на мобильных устройствах
367 |
368 | Вы можете реализовывать различные взаимодействия со страницей через свайпы на мобильных устройствах с помощью плагина. Как это использовать:
369 |
370 | 1. Подключить код библиотеки swiped-events.js (код в файле _functions.js_).
371 | 2. Использовать различные события из библиотеки плагина.
372 |
373 | ### Миксин для flex-расстановки элементов.
374 |
375 | В последней версии сборки я добавил миксин flex-layout (можно найти в папке mixins), в котором реализована типичная сетка для карточек. Вы можете выбирать нужные вам настройки, чтобы сделать сетку быстро и без проблем. Например:
376 |
377 | ```html
378 |
13 | ![\"$3\"](\"$1.webp\")
",
108 | "