Користувацькі поля
Користувацькі поля дають змогу визначати групи полів для повторного використання в кількох блоках. Це шаблони полів: визначте один раз і використовуйте всюди.
Користувацькі поля — це не те саме, що типи користувацьких полів. Використовуйте custom/{name} для повторно використовуваних груп наявних полів. Використовуйте тип користувацького поля з простором імен, наприклад acme/dimensions, коли тема або плагін реєструє новий елемент керування редактора та структуру значення.
Реєстрація у файловій системі
Створіть файл field.json у каталозі fields/ вашого каталогу blockstudio:
theme/
└── blockstudio/
└── fields/
└── hero/
└── field.json
{
"$schema": "https://blockstudio.dev/schema/field",
"name": "hero",
"title": "Hero Section",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Hello World"
},
{ "id": "description", "type": "textarea", "label": "Description" },
{ "id": "enabled", "type": "toggle", "label": "Enabled" }
]
}
Реєстрація через фільтр PHP
Зареєструйте користувацькі поля програмно за допомогою фільтра blockstudio/fields:
add_filter('blockstudio/fields', function ($fields) {
$fields['cta'] = [
'title' => 'Call to Action',
'attributes' => [
['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
['id' => 'url', 'type' => 'text', 'label' => 'URL'],
],
];
return $fields;
});
Використання в block.json
Посилайтеся на користувацьке поле за допомогою типу custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Це розгортається вбудовано в поля, визначені у визначенні користувацького поля. Розгорнуті поля використовують вихідні ID (heading, description, enabled).
Користувацькі поля також можуть повторно використовувати повні визначення груп:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"title": "Header",
"attributes": [
{ "id": "kicker", "type": "text", "label": "Kicker" },
{ "id": "title", "type": "text", "label": "Title" }
]
}
]
}
{
"blockstudio": {
"attributes": [{ "type": "custom/section-header" }]
}
}
Дочірні елементи групи зберігаються як section-header_kicker,
section-header_title тощо. У шаблонах використовуйте bs_get_group(),
щоб перетворити їх на зручний об’єкт групи.
Структура ID
Використовуйте idStructure, щоб додати префікс до ID поля або перетворити його. Заповнювач {id} замінюється вихідним ID поля:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
У результаті утворюються поля з ID: hero_heading, hero_description, hero_enabled.
Перевизначення
Налаштовуйте окремі поля для кожного екземпляра за допомогою overrides. Ключі відповідають вихідним ID полів із визначення:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Перевизначення властивостей об’єднуються з вихідним визначенням поля. Перевизначення id обходить шаблон idStructure. У наведеному вище прикладі enabled стає active замість hero_enabled.
Злиття відбувається лише на один рівень углиб: властивість, яку ви перевизначаєте, замінює початкову властивість повністю. Перевизначення options — це повний список параметрів, а не доповнення до нього. Те саме стосується conditions і attributes групи. Умови з посилання додаються після цього.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Цей блок пропонує лише білий і сірий кольори, незалежно від кількості варіантів у визначенні.
Умови
Умови у визначеннях користувацьких полів автоматично переписуються під час застосування idStructure. Поле, умовно залежне від сусіднього поля, продовжує працювати після розгортання.
{
"name": "font-size",
"attributes": [
{ "id": "enable", "type": "toggle", "label": "Modify font size" },
{
"id": "min",
"type": "number",
"label": "Min Size",
"conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
},
{
"id": "max",
"type": "number",
"label": "Max Size",
"conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
}
]
}
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }
Blockstudio розгортає це в title_font_enable, title_font_min,
title_font_max і переписує умови так, щоб вони посилалися на
title_font_enable замість enable. Перемикачі працюють
точно так, ніби поля визначено вбудовано.
Умови на рівні посилання
Додайте conditions до посилання, щоб застосувати їх до кожного розгорнутого поля. Це зручно, щоб приховати цілу групу за зовнішнім перемикачем:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Ці умови об’єднуються з умовами, вже визначеними всередині визначення поля. ID умов також переписуються через idStructure.
Кілька користувацьких полів
В одному блоці можна використовувати кілька користувацьких полів разом зі звичайними полями:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Вкладеність
Користувацькі поля працюють усередині груп, вкладок і повторювачів:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Додаткові шляхи виявлення
Використовуйте фільтр blockstudio/fields/paths, щоб додати каталоги для виявлення полів:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Статичний аналіз
Пакет blockstudio/phpstan розгортає посилання custom/* на основі файлів під час перевірки PHP, Twig, Blade, тегів блоків і виведених структур атрибутів. Його розгортання дотримується описаних вище правил вкладеності, idStructure та overrides.
Для визначень поза аналізованим проєктом додайте каталог бібліотеки до blockstudioScanRoots у phpstan.neon. Поля, зареєстровані лише через фільтр blockstudio/fields PHP, доступні під час виконання, але їх неможливо вивести статично.