Câmpuri personalizate
Câmpurile personalizate vă permit să definiți grupuri reutilizabile de câmpuri, la care se poate face referire din mai multe blocuri. Gândiți-vă la ele ca la șabloane de câmpuri: definiți o dată, folosiți oriunde.
Câmpurile personalizate nu sunt același lucru cu
tipurile de câmpuri personalizate. Folosiți
custom/{name} pentru grupuri reutilizabile de câmpuri existente. Folosiți un tip de câmp personalizat cu spațiu de nume, precum acme/dimensions, când o temă sau un plugin înregistrează un nou control de editor și o nouă structură a valorii.
Înregistrare prin sistemul de fișiere
Creați un fișier field.json într-un director fields/ din directorul 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" }
]
}
Înregistrare prin filtrul PHP
Înregistrați câmpuri personalizate programatic folosind filtrul 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;
});
Utilizare în block.json
Faceți referire la un câmp personalizat folosind tipul custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Acesta extinde în linie câmpurile definite în definiția câmpului personalizat. Câmpurile extinse folosesc ID-urile lor originale (heading, description, enabled).
Câmpurile personalizate pot reutiliza și definiții complete de grupuri:
{
"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" }]
}
}
Elementele imbricate ale grupului sunt stocate ca section-header_kicker,
section-header_title și așa mai departe. În șabloane, folosiți bs_get_group() pentru
a le extrage într-un obiect de grup ordonat.
Structura ID-urilor
Folosiți idStructure pentru a adăuga un prefix la ID-urile câmpurilor sau pentru a le transforma. Substituentul {id} este înlocuit cu ID-ul original al câmpului:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Acest lucru generează câmpuri cu ID-urile: hero_heading, hero_description, hero_enabled.
Suprascrieri
Personalizați câmpuri individuale pentru fiecare instanță folosind overrides. Cheile sunt ID-urile originale ale câmpurilor din definiție:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Proprietățile suprascrise se combină cu definiția originală a câmpului. O suprascriere id ocolește modelul idStructure. În exemplul de mai sus, enabled devine active în loc de hero_enabled.
Îmbinarea are un singur nivel: o proprietate pe care o suprascrieți înlocuiește proprietatea originală în întregime. O suprascriere options reprezintă lista completă de opțiuni, nu o completare a acesteia; același lucru este valabil pentru conditions și pentru attributes unui grup. Condițiile de pe referință sunt adăugate ulterior.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Acest bloc oferă doar Alb și Gri, indiferent de câte opțiuni sunt enumerate în definiție.
Condiții
Condițiile din definițiile câmpurilor personalizate sunt rescrise automat când se aplică idStructure. Un câmp condiționat de un câmp alăturat continuă să funcționeze după extindere.
{
"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 extinde acest lucru în title_font_enable, title_font_min,
title_font_max și rescrie condițiile să facă referire la
title_font_enable în loc de enable. Comutatoarele de control funcționează
exact ca și cum câmpurile ar fi definite în linie.
Condiții la nivel de referință
Adăugați conditions la referință pentru a le aplica fiecărui câmp extins. Acest lucru este util pentru a ascunde un grup întreg în spatele unui comutator extern:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Aceste condiții se combină cu toate condițiile deja definite în interiorul definiției câmpului. ID-urile condițiilor sunt rescrise și prin idStructure.
Mai multe câmpuri personalizate
Puteți folosi mai multe câmpuri personalizate într-un singur bloc, alături de câmpuri obișnuite:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Imbricare
Câmpurile personalizate funcționează în interiorul grupurilor, filelor și repetitoarelor:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Căi suplimentare de descoperire
Folosiți filtrul blockstudio/fields/paths pentru a adăuga directoare suplimentare pentru descoperirea câmpurilor:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Analiză statică
Pachetul blockstudio/phpstan extinde referințele custom/* bazate pe fișiere la validarea PHP, Twig, Blade, a etichetelor de bloc și a structurilor deduse ale atributelor. Extinderea urmează aceleași reguli de imbricare, idStructure și overrides descrise mai sus.
Pentru definițiile din afara proiectului analizat, adăugați directorul bibliotecii la blockstudioScanRoots în phpstan.neon. Câmpurile înregistrate doar prin filtrul blockstudio/fields PHP există în timpul rulării și nu pot fi deduse static.