Anpassade fält
Med anpassade fält kan du definiera återanvändbara fältgrupper som kan refereras från flera block. Se dem som fältmallar: definiera en gång, använd överallt.
Anpassade fält är inte samma sak som
anpassade fälttyper. Använd
custom/{name} för återanvändbara grupper med befintliga fält. Använd en anpassad fälttyp med ett namnområde, till exempel acme/dimensions, när ett tema eller tillägg registrerar en ny redigeringskontroll och värdestruktur.
Registrering av filsystem
Skapa en fil field.json i en katalog fields/ i din blockstudio-katalog:
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" }
]
}
Filterregistrering med PHP
Registrera anpassade fält programmatiskt med filtret 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;
});
Användning i block.json
Referera till ett anpassat fält med typen custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Detta infogas direkt och visar fälten som definierats i den anpassade fältdefinitionen. De infogade fälten använder sina ursprungliga ID:n (heading, description, enabled).
Anpassade fält kan också återanvända fullständiga gruppdefinitioner:
{
"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" }]
}
}
Gruppens underordnade fält lagras som section-header_kicker,
section-header_title och så vidare. Använd bs_get_group() i mallar för att
extrahera dem till ett tydligt gruppobjekt.
ID-struktur
Använd idStructure för att lägga till ett prefix till eller omforma fält-ID:n. Platshållaren {id} ersätts med det ursprungliga fält-ID:t:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Detta skapar fält med ID:n: hero_heading, hero_description, hero_enabled.
Åsidosättningar
Anpassa enskilda fält per instans med overrides. Nycklarna är de ursprungliga fält-ID:na från definitionen:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Åsidosatta egenskaper slås samman med den ursprungliga fältdefinitionen. Ett åsidosättande av id kringgår mönstret idStructure. I exemplet ovan blir enabled active i stället för hero_enabled.
Sammanslagningen går bara en nivå djupt: en egenskap som du åsidosätter ersätter den ursprungliga egenskapen i sin helhet. En options-åsidosättning är den fullständiga listan med alternativ, inte ett tillägg till den, och detsamma gäller för conditions och för en grupps attributes. Villkor på referensen läggs fortfarande till efteråt.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Det här blocket erbjuder bara White och Grey, oavsett hur många alternativ definitionen listar.
Villkor
Villkor i anpassade fältdefinitioner skrivs automatiskt om när idStructure används. Ett fält med ett villkor som beror på ett syskonfält fortsätter att fungera efter expansionen.
{
"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 expanderar detta till title_font_enable, title_font_min,
title_font_max och skriver om villkoren så att de refererar till
title_font_enable i stället för enable. Växlingsknapparna fungerar
precis som om fälten hade definierats direkt.
Villkor på referensnivå
Lägg till conditions i referensen för att tillämpa dem på alla expanderade fält. Det är användbart när du vill dölja en hel grupp bakom en extern växlingsknapp:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Dessa villkor slås samman med eventuella villkor som redan definierats i fältdefinitionen. Villkors-ID:n skrivs också om via idStructure.
Flera anpassade fält
Du kan använda flera anpassade fält i ett enda block tillsammans med vanliga fält:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Kapsling
Anpassade fält fungerar i grupper, flikar och repeaters:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Ytterligare identifieringssökvägar
Använd filtret blockstudio/fields/paths för att lägga till ytterligare kataloger där fält kan identifieras:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Statisk analys
Paketet blockstudio/phpstan expanderar filbaserade referenser till
custom/* vid validering av PHP, Twig, Blade, blocktaggar och
härledda attributstrukturer. Expansionen följer samma regler för kapsling,
idStructure och overrides som beskrivs ovan.
Om definitioner finns utanför det analyserade projektet lägger du till bibliotekskatalogen i blockstudioScanRoots i phpstan.neon. Fält som endast registrerats via filtret blockstudio/fields PHP finns vid körning och kan inte härledas statiskt.