Содержание

• О плагине
• Файлы блока
  • Обязательные
  • Необязательные
• Компилирование SCSS (необязательно)
• Как добавить новый блок
  • Регистрация блока
  • Добавление ACF
• Как изменить 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.

Компилирование 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, пункты 2-3.

Как изменить общий ACF всех блоков

ACF для всех блоков находятся в корневой папке acf плагина.

Изменить их можно так же, как и ACF блоков - смотрите Как изменить ACF конкретного блока.

Как использовать template parts

Использование стандартной функции 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.
  • НЕ используйте сторонние библиотеки без необходимости.