Zum Inhalt springen

Benutzerdefinierte Felder

Mit benutzerdefinierten Feldern kannst du wiederverwendbare Feldgruppen definieren, auf die mehrere Blöcke verweisen können. Betrachte sie als Feldvorlagen: einmal definieren, überall verwenden.

Benutzerdefinierte Felder sind nicht dasselbe wie benutzerdefinierte Feldtypen. Verwende custom/{name} für wiederverwendbare Gruppen vorhandener Felder. Verwende einen benutzerdefinierten Feldtyp mit Namespace, z. B. acme/dimensions, wenn ein Theme oder Plugin ein neues Editor-Steuerelement und eine neue Wertstruktur registriert.

Registrierung über das Dateisystem

Erstelle eine field.json-Datei in einem fields/-Verzeichnis innerhalb deines Blockstudio-Verzeichnisses:

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" }
  ]
}

PHP-Filterregistrierung

Registriere benutzerdefinierte Felder programmatisch mit dem 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;
});

Verwendung in block.json

Verweise mit dem Typ custom/{name} auf ein benutzerdefiniertes Feld:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

Dadurch werden die in der benutzerdefinierten Felddefinition festgelegten Felder direkt eingefügt. Die eingefügten Felder behalten ihre ursprünglichen IDs (heading, description, enabled).

Du kannst auch vollständige Gruppendefinitionen wiederverwenden:

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" }]
  }
}

Die Unterfelder der Gruppe werden als section-header_kicker, section-header_title usw. gespeichert. Verwende in Templates bs_get_group(), um sie in ein übersichtliches Gruppenobjekt umzuwandeln.

ID-Struktur

Verwende idStructure, um Feld-IDs voranzustellen oder umzuwandeln. Der Platzhalter {id} wird durch die ursprüngliche Feld-ID ersetzt:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

Dadurch entstehen Felder mit den IDs: hero_heading, hero_description, hero_enabled.

Überschreibungen

Passe einzelne Felder pro Instanz mit overrides an. Als Schlüssel dienen die ursprünglichen Feld-IDs aus der Definition:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

Überschreibungseigenschaften werden mit der ursprünglichen Felddefinition zusammengeführt. Eine Überschreibung von id umgeht das Muster idStructure. Im obigen Beispiel wird enabled zu active statt zu hero_enabled.

Die Zusammenführung geht nur eine Ebene tief: Eine überschriebene Eigenschaft ersetzt die ursprüngliche Eigenschaft vollständig. Eine Überschreibung von options ist die vollständige Optionsliste, keine Ergänzung dazu; dasselbe gilt für conditions und für attributes einer Gruppe. Bedingungen aus der Referenz werden anschließend weiterhin hinzugefügt.

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

Dieser Block bietet nur Weiß und Grau, unabhängig davon, wie viele Optionen die Definition aufführt.

Bedingungen

Bedingungen in benutzerdefinierten Felddefinitionen werden automatisch angepasst, wenn idStructure angewendet wird. Ein Feld, dessen Anzeige bedingt von einem Geschwisterfeld abhängt, funktioniert nach dem Einfügen weiterhin.

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 erweitert dies zu title_font_enable, title_font_min, title_font_max und passt die Bedingungen so an, dass sie auf title_font_enable statt auf enable verweisen. Die Schalter funktionieren genau so, als wären die Felder direkt eingefügt.

Bedingungen auf Referenzebene

Füge conditions zur Referenz hinzu, um die Bedingungen auf jedes eingefügte Feld anzuwenden. Das ist nützlich, um eine ganze Gruppe hinter einem externen Schalter zu verbergen:

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

Diese Bedingungen werden mit den bereits in der Felddefinition festgelegten Bedingungen zusammengeführt. Bedingungs-IDs werden ebenfalls über idStructure angepasst.

Mehrere benutzerdefinierte Felder

Du kannst in einem einzelnen Block mehrere benutzerdefinierte Felder neben regulären Feldern verwenden:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

Verschachtelung

Benutzerdefinierte Felder funktionieren in Gruppen, Tabs und Repeatern:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

Zusätzliche Suchpfade

Verwende den Filter blockstudio/fields/paths, um weitere Verzeichnisse für die Felderkennung hinzuzufügen:

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

Statische Analyse

Das Paket blockstudio/phpstan erweitert dateibasierte custom/*-Referenzen bei der Validierung von PHP, Twig, Blade, Block-Tags und abgeleiteten Attributstrukturen. Die Erweiterung folgt denselben Regeln für Verschachtelung, idStructure und overrides wie oben beschrieben.

Füge für Definitionen außerhalb des analysierten Projekts das Bibliotheksverzeichnis in blockstudioScanRoots in phpstan.neon hinzu. Felder, die nur über den Filter blockstudio/fields PHP registriert werden, existieren zur Laufzeit und können nicht statisch abgeleitet werden.