Aangepaste velden
Met aangepaste velden kun je herbruikbare veldgroepen definiëren waarnaar vanuit meerdere blokken kan worden verwezen. Zie ze als veldtemplates: één keer definiëren, overal gebruiken.
Aangepaste velden zijn niet hetzelfde als
aangepaste veldtypen. Gebruik
custom/{name} voor herbruikbare groepen bestaande velden. Gebruik een aangepaste
veldtype met namespace, zoals acme/dimensions, wanneer een thema of plugin een nieuw
editorbedieningselement en een nieuwe waardestructuur registreert.
Registratie via het bestandssysteem
Maak een bestand field.json aan in een map fields/ binnen je Blockstudio-map:
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" }
]
}
Filterregistratie van PHP
Registreer aangepaste velden programmatisch met het filter 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;
});
Gebruik in block.json
Verwijs naar een aangepast veld met het type custom/{name}:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
Hiermee worden inline de velden uit de aangepaste velddefinitie uitgebreid. De uitgebreide velden gebruiken hun oorspronkelijke ID’s (heading, description, enabled).
Aangepaste velden kunnen ook volledige groepsdefinities hergebruiken:
{
"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" }]
}
}
De onderliggende velden van de groep worden opgeslagen als section-header_kicker,
section-header_title enzovoort. Gebruik in templates bs_get_group() om
ze uit te pakken naar een overzichtelijk groepsobject.
ID-structuur
Gebruik idStructure om veld-ID’s vooraf te laten gaan of te transformeren. De tijdelijke aanduiding {id} wordt vervangen door de oorspronkelijke veld-ID:
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
Dit levert velden op met de ID’s: hero_heading, hero_description, hero_enabled.
Overschrijvingen
Pas afzonderlijke velden per instantie aan met overrides. De keys zijn de oorspronkelijke veld-ID’s uit de definitie:
{
"blockstudio": {
"attributes": [
{
"type": "custom/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "default": "Welcome", "label": "Title" },
"enabled": { "id": "active" }
}
}
]
}
}
Overschrijf-eigenschappen worden samengevoegd met de oorspronkelijke velddefinitie. Een overschrijving van id omzeilt het patroon idStructure. In het bovenstaande voorbeeld wordt enabled active in plaats van hero_enabled.
De samenvoeging gaat maar één niveau diep: een eigenschap die je overschrijft, vervangt de oorspronkelijke eigenschap volledig. Een overschrijving van options is de volledige optielijst, geen aanvulling daarop. Hetzelfde geldt voor conditions en voor de attributes van een groep. Voorwaarden op de verwijzing worden daarna nog toegevoegd.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
Dit blok biedt alleen Wit en Grijs, ongeacht hoeveel opties de definitie opsomt.
Voorwaarden
Voorwaarden in aangepaste velddefinities worden automatisch herschreven wanneer
idStructure wordt toegepast. Een veld dat voorwaardelijk afhankelijk is van een veld ernaast,
blijft na uitbreiding werken.
{
"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 breidt dit uit naar title_font_enable, title_font_min,
title_font_max en herschrijft de voorwaarden zodat ze verwijzen naar
title_font_enable in plaats van enable. De schakelaars werken
precies alsof de velden inline waren gedefinieerd.
Voorwaarden op referentieniveau
Voeg conditions toe aan de verwijzing om ze op elk uitgebreid veld toe te passen. Dit
is handig om een hele groep achter een externe schakelaar te verbergen:
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
Deze voorwaarden worden samengevoegd met eventuele voorwaarden die al in de velddefinitie zijn vastgelegd. Voorwaarde-ID’s worden ook herschreven via idStructure.
Meerdere aangepaste velden
Je kunt meerdere aangepaste velden in één blok gebruiken, samen met gewone velden:
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
Nesting
Aangepaste velden werken binnen groepen, tabbladen en repeaters:
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
Extra detectiepaden
Gebruik het filter blockstudio/fields/paths om extra mappen toe te voegen voor veldontdekking:
add_filter('blockstudio/fields/paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/blockstudio/fields';
return $paths;
});
Statische analyse
Het pakket blockstudio/phpstan breidt bestandsgebaseerde verwijzingen naar
custom/* uit bij het valideren van PHP, Twig, Blade, bloktags en
afgeleide kenmerkstructuren. De uitbreiding volgt dezelfde regels voor nesting,
idStructure en overrides die hierboven zijn beschreven.
Voeg voor definities buiten het geanalyseerde project de bibliotheekmap toe aan
blockstudioScanRoots in phpstan.neon. Velden die alleen via het filter blockstudio/fields PHP zijn geregistreerd, bestaan tijdens runtime en kunnen niet statisch worden afgeleid.