Pielāgotie lauki
Pielāgotie lauki ļauj definēt atkārtoti izmantojamas lauku grupas, uz kurām var atsaukties vairākos blokos. Uztveriet tās kā lauku veidnes: definējiet vienreiz un izmantojiet visur.
Pielāgotie lauki nav tas pats, kas
pielāgotie lauku tipi. Izmantojiet
custom/{name} atkārtoti izmantojamām esošo lauku grupām. Izmantojiet nosaukumtelpā iekļautu pielāgotu
lauka tipu, piemēram, acme/dimensions, ja tēma vai spraudnis reģistrē jaunu
redaktora vadīklu un vērtības struktūru.
Reģistrācija failu sistēmā
Izveidojiet failu field.json direktorijā fields/, kas atrodas jūsu blockstudio direktorijā:
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 filtra reģistrācija
Reģistrējiet pielāgotos laukus programmiski, izmantojot filtru 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;
});
Lietošana block.json
Atsaucieties uz pielāgotu lauku, izmantojot tipu custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Tas izvērš definētā pielāgotā lauka laukus tieši šeit. Izvērstie lauki saglabā savus sākotnējos ID (heading, description, enabled).
Pielāgotajos laukos var atkārtoti izmantot arī pilnas grupu definīcijas:
{
"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" }]
}
}
Grupas apakšelementi tiek saglabāti kā section-header_kicker,
section-header_title un tā tālāk. Veidnēs izmantojiet bs_get_group(), lai
izvilktu tos sakārtotā grupas objektā.
ID struktūra
Izmantojiet idStructure lauku ID prefiksa pievienošanai vai pārveidošanai. Vietturis {id} tiek aizstāts ar sākotnējo lauka ID:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Tādējādi tiek izveidoti lauki ar ID: hero_heading, hero_description, hero_enabled.
Pārrakstīšana
Pielāgojiet atsevišķus laukus katrā instancē, izmantojot overrides. Atslēgas ir sākotnējie lauku ID no definīcijas:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Pārrakstīto rekvizītu vērtības tiek apvienotas ar sākotnējo lauka definīciju. Pārrakstot id, tiek apiets raksts idStructure. Iepriekš minētajā piemērā enabled kļūst par active, nevis hero_enabled.
Apvienošana notiek tikai vienā līmenī: pārrakstīts rekvizīts aizstāj visu sākotnējo rekvizītu. options pārrakstīšana norāda pilnu opciju sarakstu, nevis tā papildinājumu; tas pats attiecas uz conditions un grupas attributes. Atsauces nosacījumi joprojām tiek pievienoti pēc tam.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Šis bloks piedāvā tikai balto un pelēko krāsu neatkarīgi no tā, cik opciju ir norādīts definīcijā.
Nosacījumi
Nosacījumi pielāgoto lauku definīcijās tiek automātiski pārveidoti, kad tiek lietots idStructure. Lauks, kura nosacījums ir atkarīgs no blakus lauka, turpina darboties arī pēc izvēršanas.
{
"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 izvērš to par title_font_enable, title_font_min,
title_font_max un pārraksta nosacījumus, lai tie atsauktos uz
title_font_enable, nevis enable. Pārslēgi darbojas
tieši tāpat kā tad, ja lauki būtu definēti iekļauti.
Atsauces līmeņa nosacījumi
Pievienojiet conditions atsaucei, lai tos piemērotu katram izvērstajam laukam. Tas
noder, lai paslēptu veselu grupu aiz ārēja pārslēga:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Šie nosacījumi tiek apvienoti ar visiem nosacījumiem, kas jau definēti lauka
definīcijā. Nosacījumu ID arī tiek pārrakstīti, izmantojot idStructure.
Vairāki pielāgotie lauki
Vienā blokā varat izmantot vairākus pielāgotos laukus kopā ar parastajiem laukiem:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Ligzdošana
Pielāgotie lauki darbojas grupās, cilnēs un atkārtotājos:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Papildu noteikšanas ceļi
Izmantojiet filtru blockstudio/fields/paths, lai pievienotu papildu direktorijus lauku noteikšanai:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Statiskā analīze
Pakotne blockstudio/phpstan izvērš failos definētas
custom/* atsauces, validējot PHP, Twig, Blade, bloku tagus un
secinot atribūtu struktūras. Izvēršana ievēro tās pašas ligzdošanas,
idStructure un overrides kārtulas, kas aprakstītas iepriekš.
Ārpus analizētā projekta esošām definīcijām pievienojiet bibliotēkas direktoriju
blockstudioScanRoots failā phpstan.neon. Lauki, kas reģistrēti tikai ar filtru
blockstudio/fields PHP, darbojas izpildlaikā, un to tipu nevar noteikt
statiski.