Персонализирани полета
Персонализираните полета ви позволяват да дефинирате групи от полета за повторна употреба, към които могат да препращат различни блокове. Представете си ги като шаблони за полета: дефинирате веднъж, използвате навсякъде.
Персонализираните полета не са същото като
типовете персонализирани полета. Използвайте
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" }
]
}
}
}
Този блок предлага само White и 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, съществуват по време на изпълнение и не могат да бъдат изведени статично.