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:
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" }
]
}
PHP-Filterregistrierung
Registriere benutzerdefinierte Felder programmatisch mit dem 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;
});
Verwendung in block.json
Verweise mit dem Typ custom/{name} auf ein benutzerdefiniertes Feld:
{
"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:
{
"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" }]
}
}
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:
{
"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:
{
"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.
{
"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.
{
"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 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:
{
"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:
{
"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:
{
"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:
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.