Brugerdefinerede felter
Brugerdefinerede felter lader dig definere genanvendelige feltgrupper, der kan bruges på tværs af flere blokke. Tænk på dem som feltskabeloner: Definer én gang, og brug dem overalt.
Brugerdefinerede felter er ikke det samme som
brugerdefinerede felttyper. Brug
custom/{name} til genanvendelige grupper af eksisterende felter. Brug en brugerdefineret felttype med navnerum som acme/dimensions, når et tema eller plugin registrerer en ny
redigeringskontrol og værdistruktur.
Registrering af filsystem
Opret en field.json-fil i en fields/-mappe i din blockstudio-mappe:
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 af PHP
Registrer brugerdefinerede felter programmatisk med filteret 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;
});
Brug i block.json
Henvis til et brugerdefineret felt ved at bruge typen custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Dette indsætter felterne fra definitionen af det brugerdefinerede felt direkte. De indsatte felter beholder deres oprindelige ID’er (heading, description, enabled).
Brugerdefinerede felter kan også genbruge komplette gruppedefinitioner:
{
"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" }]
}
}
Underfelterne i gruppen gemmes som section-header_kicker,
section-header_title osv. Brug bs_get_group() i skabeloner for at
udtrække dem til et overskueligt gruppeobjekt.
ID-struktur
Brug idStructure til at sætte præfiks på eller omdanne felt-ID’er. Pladsholderen {id} erstattes med det oprindelige felt-ID:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Dette giver felter med ID’erne: hero_heading, hero_description, hero_enabled.
Tilsidesættelser
Tilpas individuelle felter for hver forekomst med overrides. Nøglerne er de oprindelige felt-ID’er fra definitionen:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Tilsidesættelsesegenskaber flettes oven i den oprindelige feltdefinition. En tilsidesættelse af id omgår mønsteret idStructure. I eksemplet ovenfor bliver enabled til active i stedet for hero_enabled.
Sammenfletningen går kun ét niveau ned: En egenskab, du tilsidesætter, erstatter den oprindelige egenskab som helhed. En options-tilsidesættelse er den komplette liste over valgmuligheder, ikke en tilføjelse til den, og det samme gælder for conditions og for en gruppes attributes. Betingelser på referencen tilføjes stadig bagefter.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Denne blok tilbyder kun White og Grey, uanset hvor mange valgmuligheder definitionen angiver.
Betingelser
Betingelser i brugerdefinerede feltdefinitioner omskrives automatisk, når
idStructure anvendes. Et felt, der betinget afhænger af et søsterfelt,
fortsætter med at fungere efter udvidelsen.
{
"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 udvider dette til title_font_enable, title_font_min,
title_font_max og omskriver betingelserne, så de henviser til
title_font_enable i stedet for enable. Til/fra-knapperne fungerer
præcis, som hvis felterne var defineret direkte.
Betingelser på referenceniveau
Tilføj conditions til referencen for at anvende dem på alle udvidede felter. Det er
nyttigt, hvis en hel gruppe skal skjules bag en ekstern til/fra-knap:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Disse betingelser flettes sammen med eventuelle betingelser, der allerede er defineret i feltdefinitionen. Betingelses-ID’er omskrives også via idStructure.
Flere brugerdefinerede felter
Du kan bruge flere brugerdefinerede felter i én blok sammen med almindelige felter:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Indlejring
Brugerdefinerede felter fungerer i grupper, faner og repeatere:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Yderligere registreringsstier
Brug filteret blockstudio/fields/paths til at føje flere mapper til registreringen af felter:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Statisk analyse
Pakken blockstudio/phpstan udvider filbaserede
referencer til custom/*, når den validerer PHP, Twig, Blade, bloktags og
udledte attributstrukturer. Udvidelsen følger de samme regler for indlejring,
idStructure og overrides, som er beskrevet ovenfor.
For definitioner uden for det analyserede projekt skal du føje biblioteksmappen til
blockstudioScanRoots i phpstan.neon. Felter, der kun registreres via filteret
blockstudio/fields PHP, findes ved kørsel og kan ikke udledes
statisk.