Розширення
Розширення дають змогу доповнювати будь-який зареєстрований блок у вашій інсталяції WordPress за допомогою простого підходу на основі .json API, подібного до конфігурації block.json. Це стосується основних блоків, блоків сторонніх розробників і блоків, створених за допомогою Blockstudio.
Усі типи полів можна додати до будь-якого блоку, а дані зберігатимуться в атрибутах блоку. У розширеннях доступний повний набір можливостей для атрибутів: фільтрування, вимкнення, умовна логіка та заповнення параметрів.
Типи розширень
Розширені значення можна використовувати по-різному:
- 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 для конфігурацій розширень:
Назва
Властивість 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": []
}
}
Виключення блоків
Використовуйте масив exclude верхнього рівня, щоб пропускати блоки, які інакше відповідали б name:
{
"$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 не потрібна властивість set, адже поле автоматично зіставляє значення з назвою та значенням атрибута.
Перегляд полів розширень
bs_block_extension_fields('core/paragraph') повертає визначення полів усіх розширень, що відповідають блоку. Див. Перегляд блоків, щоб дізнатися про значення, що повертається, і його зв’язок із bs_block_fields().