Расширения
Расширения позволяют дополнять любой зарегистрированный блок в вашей установке WordPress с помощью простой конфигурации API на основе .json, похожей на конфигурацию block.json. Это относится к основным блокам, сторонним блокам и блокам, созданным с помощью Blockstudio.
Для любого блока можно добавлять все типы полей field types; данные сохраняются в атрибутах блока. Для расширений доступны все возможности полей, включая фильтрацию, отключение, условную логику и заполнение вариантов.
Типы расширений
Значения расширений можно применять разными способами:
- class: добавление классу блока значения атрибута
- style: добавление встроенных стилей блоку с помощью значения атрибута
- attributes: непосредственная установка значения любого атрибута блока
- data attributes: использование значений расширения для задания определённых атрибутов данных
Настройка
Представьте такой сценарий: вы хотите добавить поле select для пользовательского класса в каждый основной блок. Достаточно добавить этот файл .json в любое место папки блока, и он автоматически зарегистрируется как расширение.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"priority": 10,
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Custom color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
В каждый основной блок будет добавлено поле customColor, позволяющее задавать цвет текста блока.
Имя файла
Поскольку шаблона для рендеринга нет, расширению не нужен соответствующий файл index, поэтому его не обязательно называть block.json. Благодаря этому все расширения удобно хранить в одной папке. Несколько файлов могут расширять одни и те же блоки, например два файла с "name": "core/*"; каждый регистрирует собственные поля.
Схема
Blockstudio предоставляет пользовательскую схему JSON для конфигураций расширений:
Схема расширения Meta Box View
Имя
Свойство name объекта конфигурации определяет, какие блоки нужно расширить. В зависимости от ваших потребностей есть три варианта:
- blockName: имя одного блока, e.g.
core/paragraph - [blockNameA, blockNameB]: массив имен блоков, e.g.
["core/paragraph", "core/heading"] - core/*: подстановочный шаблон для расширения всех блоков определенного типа
Любое имя, оканчивающееся звездочкой, задает подстановку префикса, а не только core/*. Следующее расширение применяется ко всем блокам, имена которых начинаются с my-plugin/,
включая блоки, созданные с помощью Blockstudio:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
Исключение блоков
Чтобы пропускать блоки, которые иначе соответствовали бы name, используйте массив exclude верхнего уровня:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
Для исключений используется такое же сопоставление по точному имени и префиксу с завершающей *, как для name.
Они имеют приоритет над отдельными именами, списками имен и подстановочными знаками. Исключенный
блок не получает ни полей расширения в редакторе, ни атрибутов или ресурсов фронтенда.
Другие подходящие расширения не затрагиваются. Опустите exclude или укажите пустой массив,
чтобы сохранить текущее поведение.
Ключ Blockstudio
Как и при использовании block.json для пользовательских блоков, свойство blockstudio должно присутствовать в объекте конфигурации, а для extend должно быть задано значение true.
Положение
По умолчанию расширения отображаются на отдельной вкладке инспектора блоков. Чтобы переместить их в другое место, используйте свойство group:
- settings: положение по умолчанию
- styles: вкладка стилей
- advanced: вкладка дополнительных настроек
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
Приоритет
Свойство priority позволяет задать порядок отображения расширений. Расширения с более высоким приоритетом отображаются позже. Укажите его на верхнем уровне файла, как в примере настройки, или внутри extend:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
Если заданы оба значения, приоритет имеет blockstudio.extend.priority.
Атрибуты
Подробнее о работе атрибутов см. в разделе об атрибутах.
Единственное, что нужно знать об атрибутах расширений, — это свойство set. Оно используется, чтобы передать значение атрибута одному из типов расширений.
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
Получение значений
Чтобы получить значение атрибута, используйте точечную нотацию внутри фигурных скобок.
Также можно получать вложенные значения, если атрибуты возвращают не одно значение. Например, это происходит, когда для полей с вариантами задан формат возврата both.
{
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"returnFormat": "both",
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor.value}"
},
{
"attribute": "data-color",
"value": "{attributes.customColor.label}"
}
]
}
]
}
В приведенном выше примере атрибуту style будет присвоено значение color: #f00 или color: #00f, а атрибуту data-color — значение Red или Blue в зависимости от выбранного значения.
Пока что в определениях set можно использовать только значения текущего атрибута. Возможно, в будущем появится возможность использовать значения других атрибутов.
Массивы
При использовании массивов свойство set применяется к каждому элементу массива.
Каждый элемент добавляет собственный класс или объявление стиля. Любой другой атрибут содержит одно значение, поэтому каждый элемент перезаписывает его, и побеждает последний. Установите join в true, чтобы вместо этого записать результаты всех элементов через пробел, без пустых и повторяющихся значений; так селектор вроде [data-langs~="en"] будет соответствовать каждому выбранному элементу. join не влияет на class и style, а также на поля, возвращающие одно значение.
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
При выборе обоих параметров выводится data-langs="en de". Без join выводится data-langs="de".
Поле Attributes
При использовании поля attributes свойство set не требуется, поскольку поле автоматически сопоставляет значения с именем и значением атрибута.
Просмотр полей расширений
bs_block_extension_fields('core/paragraph') возвращает определения полей
всех расширений, соответствующих блоку. Подробнее о возвращаемом
значении и его связи с bs_block_fields() см. в разделе Просмотр блоков.