Tinkinti laukai
Tinkinti laukai leidžia apibrėžti pakartotinai naudojamas laukų grupes, kurias galima nurodyti keliuose blokuose. Laikykite juos laukų šablonais: apibrėžkite vieną kartą ir naudokite visur.
Tinkinti laukai nėra tas pats, kas
tinkinti laukų tipai. Naudokite
custom/{name} pakartotinai naudojamoms esamų laukų grupėms. Naudokite vardų sritį turintį tinkintą laukų tipą, pvz., acme/dimensions, kai tema arba papildinys registruoja naują
redaktoriaus valdiklį ir reikšmės struktūrą.
Registravimas failų sistemoje
Savo blockstudio katalogo fields/ kataloge sukurkite failą field.json:
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" }
]
}
Registravimas naudojant PHP filtrą
Tinkintus laukus registruokite programiškai naudodami filtrą 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;
});
Naudojimas su block.json
Nurodykite tinkintą lauką naudodami tipą custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Taip įterpiami laukai, apibrėžti tinkinto lauko apraše. Įterptieji laukai naudoja pradinius ID (heading, description, enabled).
Tinkintuose laukuose taip pat galima pakartotinai naudoti visas grupių apibrėžtis:
{
"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" }]
}
}
Grupės antriniai elementai saugomi kaip section-header_kicker,
section-header_title ir t. t. Šablonuose naudokite bs_get_group(), kad
išskleistumėte juos į tvarkingą grupės objektą.
ID struktūra
Naudokite idStructure laukų ID prefiksui pridėti arba jiems pakeisti. Vietos rezervavimo ženklas {id} pakeičiamas pradiniu lauko ID:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Taip sukuriami laukai su šiais ID: hero_heading, hero_description, hero_enabled.
Pakeitimai
Tinkinkite atskirus laukus pagal egzempliorių naudodami overrides. Raktai yra pradiniai lauko ID iš aprašo:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Perrašytos savybės sujungiamos su pradiniu lauko aprašu. id perrašymas apeina šabloną idStructure. Aukščiau pateiktame pavyzdyje enabled tampa active, o ne hero_enabled.
Sujungimas vyksta tik vienu lygiu: perrašyta savybė pakeičia visą pradinę savybę. options perrašymas reiškia visą parinkčių sąrašą, o ne jo papildymą; tas pats galioja conditions ir grupės attributes. Nuorodos sąlygos vis tiek pridedamos vėliau.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Šiame bloke siūlomos tik balta ir pilka spalvos, kad ir kiek parinkčių būtų nurodyta apraše.
Sąlygos
Sąlygos tinkintų laukų apibrėžtyse automatiškai perrašomos, kai taikomas idStructure. Laukas, kurio rodymas priklauso nuo gretimo lauko sąlygos, veiks ir po išskleidimo.
{
"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 išskleidžia tai į title_font_enable, title_font_min,
title_font_max ir perrašo sąlygas, kad jos nurodytų title_font_enable, o ne enable. Perjungikliai veikia
lygiai taip, tarsi laukai būtų apibrėžti tiesiogiai.
Nuorodos lygmens sąlygos
Prie nuorodos pridėkite conditions, kad jos būtų taikomos kiekvienam išskleistam laukui. Tai naudinga, kai norite paslėpti visą grupę pagal išorinį perjungiklį:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Šios sąlygos sujungiamos su sąlygomis, jau apibrėžtomis lauko apraše. Sąlygų ID taip pat perrašomi naudojant idStructure.
Keli tinkinti laukai
Viename bloke galite naudoti kelis tinkintus laukus kartu su įprastais laukais:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Įdėjimas
Tinkinti laukai veikia grupėse, kortelėse ir kartotuvuose:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Papildomi aptikimo keliai
Naudokite filtrą blockstudio/fields/paths, kad pridėtumėte papildomų katalogų laukams aptikti:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Statinė analizė
blockstudio/phpstan paketas išplečia failuose apibrėžtas custom/* nuorodas, tikrindamas PHP, Twig, Blade, blokų žymas ir išvedamas atributų struktūras. Išplėtimas taiko tas pačias įdėjimo, idStructure ir overrides taisykles, kurios aprašytos aukščiau.
Jei apibrėžtys yra už analizuojamo projekto ribų, pridėkite bibliotekos katalogą prie blockstudioScanRoots faile phpstan.neon. Laukai, registruoti tik naudojant filtrą blockstudio/fields PHP, egzistuoja vykdymo metu ir negali būti nustatyti atliekant statinę analizę.