- О плагине
- Файлы блока
- Компилирование SCSS (необязательно)
- Как добавить новый блок
- Как изменить ACF конкретного блока
- Как изменить общий ACF всех блоков
- Как использовать 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. Будет скомпилирован в compilable.css и добавлен к остальным стилям вместе с style.css . |
Команда | Описание |
---|---|
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 можно добавить через админ панель.
- В
Settings - Location Rules
указать тип группыBlock
, название - добавленный ранее блок. - Экспортировать новую группу полей как JSON. Поместить
acf.json
файл в папку acf в диреактории блока. Вacf.json
удалить открывающую[
и]
закрывающую квадратные скобки. То есть ACF блока должен иметь такую{…}
структуру вместо такой[{…}]
. - В админ панели удалить или деактивировать группу полей, так чтобы ACF поля блока описывались только файлом
acf.json
, который хранится в папке блока.
ACF конретного блока находится в директории соответствующего блока в папке acf
.
Можно либо изменить файл напрямую в коде, либо импортировать файл средствами плагина ACF и изменить через GUI. Далее смотрите Добавление ACF, пункты 2-3.
ACF для всех блоков находятся в корневой папке acf
плагина.
Изменить их можно так же, как и ACF блоков - смотрите Как изменить ACF конкретного блока.
Использование стандартной функции WordPress get_template_part
невозможно при работе с файлами плагина. Вместо неё используется самописная функция cb_get_template($name, $args = [])
с похожим функционалом, которая берёт файлы из папки templates
.
- Для файлов плагина используйте только названия, указанные в Файлах блока.
- НЕ используйте квадратные скобки в файлах acf.json (смотрите Добавление ACF, пункт 2).
- Все ACF поля для конкретного блока должны храниться внутри группы Field Type: Group с обязательным селектором Field Name:
fields
.
- Общий подход
- Используйте отдельный шаблон страниц для CB Blocks - "Custom Blocks”.
- При создании блоков соблюдайте конвенцию: “одна секция = один блок”. Предпочтение отдаётся количеству и разнообразию секций в ущерб возможному переиспользованию кода.
- Если файл может иметь произвольное название (например, файлы .json), добавляйте ему осмысленное название. Например, 'blocks-background-color', 'blocks-alignment', etc.
- HTML
- Используйте data-атрибуты для элементов, предназначенных для использования в JS: data-js, data-slider, etc.
- Для иконок используйте синтаксис SVG спрайтов:
<svg><use href="sprite.svg#icon"></use></svg>
.
- CSS
- НЕ используйте легаси стили из старой темы.
- Используйте новейший синтаксис для более понятного и лаконичного кода: CSS Nesting, CSS variables, :has(), grid, flex.
- Инкапсулируйте стили лишь внутри своего блока с помощью CSS Nesting.
- НЕ используйте сторонние библиотеки без необходимости.
- JS
- Используйте IIFE.
- НЕ используйте сторонние библиотеки без необходимости.