Vlastní pole
Vlastní pole umožňují definovat opakovaně použitelné skupiny polí, na které lze odkazovat z více bloků. Představte si je jako šablony polí: definujte jednou, používejte všude.
Vlastní pole nejsou totéž co
vlastní typy polí. Pro opakovaně použitelné skupiny existujících polí použijte
custom/{name}. Pokud šablona nebo plugin registruje nový ovládací prvek editoru a tvar hodnoty, použijte vlastní typ pole se jmenným prostorem, například acme/dimensions.
Registrace v systému souborů
Vytvořte soubor field.json v adresáři fields/ uvnitř adresáře 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" }
]
}
Registrace pomocí filtru PHP
Zaregistrujte vlastní pole programově pomocí 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;
});
Použití v block.json
Odkazujte na vlastní pole pomocí typu custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Tím se vloží pole definovaná ve vlastní definici pole. Rozbalená pole používají svá původní ID (heading, description, enabled).
Vlastní pole mohou znovu použít také úplné definice skupin:
{
"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" }]
}
}
Podřízené položky skupiny se ukládají jako section-header_kicker,
section-header_title atd. V šablonách je pomocí bs_get_group() převeďte
na přehledný objekt skupiny.
Struktura ID
Pomocí idStructure můžete předřadit prefix ID polí nebo je transformovat. Zástupný symbol {id} se nahradí původním ID pole:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Výsledkem budou pole s ID: hero_heading, hero_description, hero_enabled.
Přepisování hodnot
Upravte jednotlivá pole pro každou instanci pomocí overrides. Klíče jsou původní ID polí z definice:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Přepsané vlastnosti se sloučí s původní definicí pole. Přepsání id obchází vzor idStructure. Ve výše uvedeném příkladu se enabled změní na active místo hero_enabled.
Sloučení probíhá pouze o jednu úroveň: přepsaná vlastnost nahradí původní vlastnost jako celek. Přepsání options představuje úplný seznam možností, nikoli jeho rozšíření; totéž platí pro conditions a pro attributes skupiny. Podmínky uvedené v referenci se přidají až poté.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Tento blok nabízí pouze bílou a šedou barvu, bez ohledu na počet možností uvedených v definici.
Podmínky
Podmínky ve vlastních definicích polí se automaticky přepíší při použití idStructure. Pole, jehož podmínka závisí na sourozeneckém poli, bude po rozbalení dál fungovat.
{
"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 to rozbalí na title_font_enable, title_font_min,
title_font_max a přepíše podmínky tak, aby odkazovaly na
title_font_enable místo enable. Přepínače fungují
přesně tak, jako kdyby byla pole definována přímo.
Podmínky na úrovni odkazu
Přidejte conditions do odkazu a použijte je na každé rozbalené pole. Hodí se to, když chcete skrýt celou skupinu pomocí externího přepínače:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Tyto podmínky se sloučí se všemi podmínkami, které už jsou definované uvnitř definice pole. ID podmínek se také přepíší pomocí idStructure.
Více vlastních polí
V jednom bloku můžete použít více vlastních polí společně s běžnými poli:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Vnořování
Vlastní pole fungují uvnitř skupin, karet a opakovačů:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Další cesty pro vyhledávání
Pomocí filtru blockstudio/fields/paths přidejte další adresáře pro vyhledávání polí:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Statická analýza
Balíček blockstudio/phpstan rozbaluje odkazy custom/* na soubory při ověřování PHP, Twig, Blade, značek bloků a odvozených tvarů atributů. Při rozbalování se řídí stejnými pravidly pro vnořování, idStructure a overrides, která jsou popsána výše.
U definic mimo analyzovaný projekt přidejte adresář knihovny do blockstudioScanRoots v phpstan.neon. Pole registrovaná pouze přes filtr blockstudio/fields PHP existují za běhu a nelze je staticky odvodit.