https://github.com/avcat/custom-blocks
Wordpress plugin based on ACF Blocks. A convenient way to create and maintain website UI system.
https://github.com/avcat/custom-blocks
acf acf-blocks css css-nesting php scss wordpress-plugin
Last synced: 3 months ago
JSON representation
Wordpress plugin based on ACF Blocks. A convenient way to create and maintain website UI system.
- Host: GitHub
- URL: https://github.com/avcat/custom-blocks
- Owner: avcat
- Created: 2023-12-23T20:05:50.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-20T16:52:51.000Z (3 months ago)
- Last Synced: 2025-02-20T17:42:29.441Z (3 months ago)
- Topics: acf, acf-blocks, css, css-nesting, php, scss, wordpress-plugin
- Language: PHP
- Homepage:
- Size: 9.29 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
Awesome Lists containing this project
README
## Содержание
- [О плагине](#о-плагине)
- [Файлы блока](#файлы-блока)
- [Обязательные](#обязательные)
- [Необязательные](#необязательные)
- [Компилирование SCSS (необязательно)](#компилирование-scss-необязательно)
- [Как добавить новый блок](#как-добавить-новый-блок)
- [Регистрация блока](#регистрация-блока)
- [Добавление ACF](#добавление-acf)
- [Как изменить ACF конкретного блока](#как-изменить-acf-конкретного-блока)
- [Как изменить общий ACF всех блоков](#как-изменить-общий-acf-всех-блоков)
- [Как использовать template parts](#как-использовать-template-parts)
- [Конвенции при разработке и использовании плагина](#конвенции-при-разработке-и-использовании-плагина)
- [Обязательно](#обязательно)
- [Рекомендуется](#рекомендуется)
## О плагине
Плагин призван стать новой версией дизайна контента, которая бы не конфликтовала с существующей дизайн-системой на основе легаси Content Builder и существующих стилей.
Плагин создан с идеей максимально упростить создание новых блоков и поддержку существующих блоков.
## Файлы блока
### Обязательные
| Название | Назначение |
| --- | --- |
| `render.php` | Логика рендера блока.
В этом же файле можно описывать дополнительную логику рендеринга ACF. |
| `template.php` | Шаблон блока.
Блок будет обёрнут в контейнер, описанный в `templates/blocks-wrapper.php`. |
### Необязательные
| Название | Назначение |
| --- | --- |
| `acf/*.json `| Настройки ACF полей блока.
ACF, общий для всех блоков, хранится в корневой папке `acf` плагина. |
| `index.php` | Дополнительная логика рендера ACF полей. |
| `preview.png` | Превью блока, которое будет показываться при наведении на иконку блока в сайдбаре блочного редактора. |
| `script.js` | JS, который будет добавлен на страницу вместе с данным блоком. |
| `style.css` | CSS, который будет добавлен на страницу вместе с данным блоком. |
| `compilable.scss` | Дополнительный файл стилей для обеспечения совместимости и как альтернатива [CSS Nesting](https://caniuse.com/css-nesting).
Будет скомпилирован в `compilable.css` и добавлен к остальным стилям вместе с `style.css`. |
## Компилирование SCSS (необязательно)
| Команда | Описание |
| --- | --- |
| `cd wp-content/plugins/custom-blocks` | Перейти в папку плагина. |
| `sass --version` | Проверить, что Sass установлен глобально. |
| `npm install` | Установить библиотеку для компилирования Sass локально.
Этот шаг можно пропустить, если Sass установлен глобально. |
| `npm run dev` | Скомпилировать `.scss`/`.sass` файлы из папки `blocks` один раз. |
| `npm run watch` | Следить за изменениями. |
| `npm run prod` | Скомпилировать и минифицировать. |
## Как добавить новый блок
Все блоки хранятся в папке `blocks`.
Сначала необходимо зарегистрировать новый блок, затем добавить к нему ACF.
### Регистрация блока
* Скопировать любой другой блок из папки `blocks`.
* Обновить файлы, описанные в [Файлах блока](#файлы-блока).
### Добавление ACF
ACF можно добавить через админ панель.
1. В `Settings - Location Rules` указать тип группы `Block`, название - добавленный ранее блок.
2. Экспортировать новую группу полей как JSON. Поместить `acf.json` файл в папку acf в диреактории блока. В `acf.json` удалить открывающую `[` и `]` закрывающую квадратные скобки. То есть ACF блока должен иметь такую `{…}` структуру **вместо** такой `[{…}]`.
3. В админ панели удалить или деактивировать группу полей, так чтобы ACF поля блока описывались только файлом `acf.json`, который хранится в папке блока.
## Как изменить ACF конкретного блока
ACF конретного блока находится в директории соответствующего блока в папке `acf`.
Можно либо изменить файл напрямую в коде, либо импортировать файл средствами плагина ACF и изменить через GUI. Далее смотрите [Добавление ACF](#добавление-acf), пункты 2-3.
## Как изменить общий ACF всех блоков
ACF для всех блоков находятся в корневой папке `acf` плагина.
Изменить их можно так же, как и ACF блоков - смотрите [Как изменить ACF конкретного блока](#как-изменить-acf-конкретного-блока).
## Как использовать template parts
Использование стандартной функции WordPress `get_template_part` невозможно при работе с файлами плагина. Вместо неё используется самописная функция `cb_get_template($name, $args = [])` с похожим функционалом, которая берёт файлы из папки `templates`.
## Конвенции при разработке и использовании плагина
### Обязательно
* Для файлов плагина используйте только названия, указанные в [Файлах блока](#файлы-блока).
* НЕ используйте квадратные скобки в файлах acf.json (смотрите [Добавление ACF](#добавление-acf), пункт 2).
* Все ACF поля для конкретного блока должны храниться внутри группы **Field Type: Group** с обязательным селектором **Field Name: `fields`**.
### Рекомендуется
* Общий подход
* Используйте отдельный **шаблон** страниц для CB Blocks - "Custom Blocks”.
* При создании блоков соблюдайте конвенцию: **“одна секция = один блок”**. Предпочтение отдаётся количеству и разнообразию секций в ущерб возможному переиспользованию кода.
* Если файл может иметь произвольное название (например, файлы _.json_), добавляйте ему осмысленное название. Например, '_blocks-background-color_', '_blocks-alignment_', etc.
* HTML
* Используйте [data-атрибуты](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes) для элементов, предназначенных для использования в JS: _data-js_, _data-slider_, etc.
* Для иконок используйте синтаксис [SVG спрайтов](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use): ``.
* CSS
* **НЕ** используйте легаси стили из старой темы.
* Используйте новейший синтаксис для более понятного и лаконичного кода: [CSS Nesting](https://caniuse.com/css-nesting), [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties), [:has()](https://caniuse.com/css-has), [grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Basic_Concepts_of_Grid_Layout), [flex](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox).
* Инкапсулируйте стили лишь внутри своего блока с помощью CSS Nesting.
* НЕ используйте сторонние библиотеки без необходимости.
* JS
* Используйте [IIFE](https://developer.mozilla.org/en-US/docs/Glossary/IIFE).
* НЕ используйте сторонние библиотеки без необходимости.