Ga naar de inhoud

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:

Code
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
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:

PHP
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}:

JSON
{
  "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:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "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.

JSON
{
  "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.

JSON
{
  "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 }]]
    }
  ]
}
JSON
{ "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:

JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "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:

PHP
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.