Kochbuch für Feldmuster
Das Feldsystem von Blockstudio ist für sich genommen einfach: Füge ein Feld zu blockstudio.attributes hinzu und rufe es in deiner Vorlage über $a ab. Reale Blöcke haben jedoch selten nur ein Feld. Sie enthalten Gruppen zusammengehöriger Einstellungen, Felder, die abhängig von anderen Feldern ein- oder ausgeblendet werden, Repeater mit komplexen Zeilenstrukturen und Daten, die außerhalb des Block-Editors abfragbar sein müssen.
Diese Anleitung enthält praktische Rezepte für gängige Feldmuster. Jedes Rezept zeigt die block.json-Konfiguration und den dazugehörigen Vorlagencode. Kopiere sie direkt in deine Blöcke und passe sie nach Bedarf an.
Bedingte Felder
Das häufigste Muster: Felder abhängig vom Wert eines anderen Feldes ein- oder ausblenden. So bleibt der Editor übersichtlich und zeigt nur relevante Optionen an.
Optionen per Umschalter einblenden
Ein CTA-Block, in dem zusätzliche Einstellungen erscheinen, wenn der Nutzer eine Schaltfläche aktiviert:
{
"name": "my-theme/cta",
"title": "Call to Action",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "Ready to get started?" },
{ "id": "description", "type": "textarea", "label": "Description" },
{ "id": "showButton", "type": "toggle", "label": "Show Button", "default": true },
{
"id": "buttonText",
"type": "text",
"label": "Button Text",
"default": "Get Started",
"conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
},
{
"id": "buttonUrl",
"type": "link",
"label": "Button Link",
"conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
}
]
}
}
Die Felder für Schaltflächentext und Link erscheinen nur, wenn der Umschalter aktiviert ist. Prüfe in der Vorlage den Umschalter, bevor du sie ausgibst:
<div useBlockProps>
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<?php if ( $a['description'] ) : ?>
<p><?php echo esc_html( $a['description'] ); ?></p>
<?php endif; ?>
<?php if ( $a['showButton'] && $a['buttonUrl'] ) : ?>
<a href="<?php echo esc_url( $a['buttonUrl']['url'] ); ?>">
<?php echo esc_html( $a['buttonText'] ); ?>
</a>
<?php endif; ?>
</div>
Feldgruppen per Auswahl wechseln
Ein Hero-Block, bei dem der Hintergrundtyp bestimmt, welche Felder angezeigt werden:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading" },
{
"id": "bgType",
"type": "select",
"label": "Background Type",
"default": "color",
"options": [
{ "value": "color", "label": "Solid Color" },
{ "value": "gradient", "label": "Gradient" },
{ "value": "image", "label": "Image" },
{ "value": "video", "label": "Video" }
]
},
{
"id": "bgColor",
"type": "color",
"label": "Background Color",
"conditions": [[{ "id": "bgType", "operator": "==", "value": "color" }]]
},
{
"id": "bgGradient",
"type": "gradient",
"label": "Background Gradient",
"conditions": [[{ "id": "bgType", "operator": "==", "value": "gradient" }]]
},
{
"id": "bgImage",
"type": "files",
"label": "Background Image",
"multiple": false,
"conditions": [[{ "id": "bgType", "operator": "==", "value": "image" }]]
},
{
"id": "bgVideo",
"type": "files",
"label": "Background Video",
"multiple": false,
"allowedTypes": ["video"],
"conditions": [[{ "id": "bgType", "operator": "==", "value": "video" }]]
},
{
"id": "overlay",
"type": "range",
"label": "Overlay Opacity",
"default": 50,
"min": 0,
"max": 100,
"conditions": [[{ "id": "bgType", "operator": "!=", "value": "color" }]]
}
]
}
}
Das Feld für die Deckkraft des Overlays verwendet !=, damit es für alle Hintergrundtypen außer Volltonfarbe erscheint. Es wird immer nur ein Hintergrundfeld angezeigt. Ein color-Feld gibt ein Array mit value, name und slug der Farbe zurück, daher liest die Vorlage ['value'] aus:
<?php
$bg_style = match ( $a['bgType'] ) {
'color' => $a['bgColor'] ? "background-color: {$a['bgColor']['value']}" : '',
'gradient' => $a['bgGradient'] ? "background: {$a['bgGradient']}" : '',
'image' => $a['bgImage'] ? "background-image: url({$a['bgImage']['url']})" : '',
default => '',
};
?>
<div useBlockProps style="<?php echo esc_attr( $bg_style ); ?>">
<?php if ( $a['bgType'] === 'video' && $a['bgVideo'] ) : ?>
<video autoplay muted loop playsinline>
<source src="<?php echo esc_url( $a['bgVideo']['url'] ); ?>" />
</video>
<?php endif; ?>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
</div>
ODER-Bedingungen
Ein Feld anzeigen, wenn eine von mehreren Bedingungen zutrifft. Jedes innere Array ist eine UND-Gruppe; das äußere Array verbindet sie mit ODER:
{
"id": "caption",
"type": "text",
"label": "Caption",
"conditions": [
[{ "id": "bgType", "operator": "==", "value": "image" }],
[{ "id": "bgType", "operator": "==", "value": "video" }]
]
}
Damit wird das Beschriftungsfeld angezeigt, wenn bgType entweder „image“ ODER „video“ ist.
Verkettete Bedingungen
Mehrere Bedingungen im selben inneren Array verwenden eine UND-Verknüpfung:
{
"id": "altText",
"type": "text",
"label": "Alt Text",
"conditions": [[
{ "id": "bgType", "operator": "==", "value": "image" },
{ "id": "bgImage", "operator": "!empty" }
]]
}
Das Feld für den Alternativtext erscheint nur, wenn bgType „image“ ist UND ein Bild ausgewählt wurde.
Globale Bedingungen
Felder abhängig vom Beitragstyp, der Beitrags-ID oder der Nutzerrolle statt von anderen Feldwerten anzeigen:
{
"id": "seoTitle",
"type": "text",
"label": "SEO Title",
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
Verfügbare globale Bedingungstypen: postType, postId, userRole, userId.
Übersichtliche Einstellungen
Wenn Blöcke komplexer werden, halten logische Feldgruppen den Inspektor übersichtlich.
Gruppen zur visuellen Gliederung
Gruppen erstellen einklappbare Abschnitte im Inspektor. Eine anonyme Gruppe (ohne id) dient nur der visuellen Gliederung; auf ihre Felder greifst du über die unveränderten IDs zu:
{
"name": "my-theme/card",
"title": "Card",
"blockstudio": {
"attributes": [
{
"type": "group",
"title": "Content",
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "description", "type": "textarea", "label": "Description" },
{ "id": "image", "type": "files", "label": "Image", "multiple": false }
]
},
{
"type": "group",
"title": "Link",
"attributes": [
{ "id": "url", "type": "link", "label": "URL" },
{ "id": "openInNewTab", "type": "toggle", "label": "Open in New Tab" }
]
},
{
"type": "group",
"title": "Appearance",
"attributes": [
{
"id": "style",
"type": "select",
"label": "Style",
"default": "elevated",
"options": [
{ "value": "elevated", "label": "Elevated" },
{ "value": "outlined", "label": "Outlined" },
{ "value": "flat", "label": "Flat" }
]
},
{ "id": "accentColor", "type": "color", "label": "Accent Color" }
]
}
]
}
}
<div useBlockProps>
<h3><?php echo esc_html( $a['title'] ); ?></h3>
<p><?php echo esc_html( $a['description'] ); ?></p>
</div>
Auf die Felder greifst du direkt zu: $a['title'], $a['style'], $a['accentColor']. Die Gruppen beeinflussen nur das Layout des Inspektors.
Benannte Gruppen mit bs_get_group
Wenn eine Gruppe ein id hat, erhalten die IDs ihrer untergeordneten Felder ein Präfix. Verwende bs_get_group(), um das Präfix zu entfernen:
{
"id": "author",
"type": "group",
"title": "Author",
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "role", "type": "text", "label": "Role" },
{ "id": "avatar", "type": "files", "label": "Avatar", "multiple": false }
]
}
Ohne den Helfer greifst du auf die Felder über $a['author_name'], $a['author_role'], $a['author_avatar'] zu. Mit dem Helfer:
<?php $author = bs_get_group( $a, 'author' ); ?>
<div class="author">
<?php if ( $author['avatar'] ) : ?>
<img src="<?php echo esc_url( $author['avatar']['url'] ); ?>" alt="" />
<?php endif; ?>
<p><?php echo esc_html( $author['name'] ); ?></p>
<p><?php echo esc_html( $author['role'] ); ?></p>
</div>
Benannte Gruppen sind nützlich, wenn dieselben Feldnamen in mehreren Gruppen vorkommen (e.g, author_name und company_name) oder wenn du die Gruppe als Einheit an eine Teilvorlage übergeben möchtest.
Rasterlayout in Gruppen
Verwende die Eigenschaft style, um untergeordnete Gruppenelemente nebeneinander anzuordnen:
{
"type": "group",
"title": "Dimensions",
"style": {
"display": "grid",
"grid-template-columns": "1fr 1fr",
"grid-gap": "16px"
},
"attributes": [
{ "id": "width", "type": "unit", "label": "Width", "default": "100%", "switch": false },
{ "id": "height", "type": "unit", "label": "Height", "default": "auto", "switch": false }
]
}
Die beiden Einheitenfelder werden im Inspektor nebeneinander statt untereinander angezeigt. Das eignet sich für Maßpaare, Margin-/Padding-Werte und andere Felder, die inhaltlich zusammengehören.
Tabs für Hauptbereiche
Wenn ein Block viele Einstellungen hat, sorgen Tabs für eine übersichtlichere Gliederung als eine lange Liste von Gruppen:
{
"type": "tabs",
"tabs": [
{
"title": "Content",
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "body", "type": "wysiwyg", "label": "Body" }
]
},
{
"title": "Media",
"attributes": [
{ "id": "image", "type": "files", "label": "Image", "multiple": false },
{ "id": "video", "type": "files", "label": "Video", "multiple": false, "allowedTypes": ["video"] }
]
},
{
"title": "Settings",
"attributes": [
{ "id": "layout", "type": "select", "label": "Layout", "options": [
{ "value": "left", "label": "Media Left" },
{ "value": "right", "label": "Media Right" }
]},
{ "id": "fullWidth", "type": "toggle", "label": "Full Width" }
]
}
]
}
Auf die Felder jedes Tabs greifst du wie auf Felder der obersten Ebene zu: $a['title'], $a['image'], $a['layout']. Tabs sind lediglich ein UI-Container.
Repeater-Muster
Mit Repeatern können Nutzer mehrere Feldzeilen hinzufügen. Sie sind unverzichtbar für Listen, Raster, Zeitachsen und alle Komponenten mit einer variablen Anzahl von Elementen.
Einfacher Repeater mit Beschränkungen
Eine Merkmalsliste mit 1 bis 6 Einträgen:
{
"id": "features",
"type": "repeater",
"label": "Features",
"min": 1,
"max": 6,
"textButton": "Add Feature",
"attributes": [
{ "id": "icon", "type": "icon", "label": "Icon" },
{ "id": "title", "type": "text", "label": "Title", "default": "Feature" },
{ "id": "description", "type": "textarea", "label": "Description" }
]
}
<div useBlockProps class="grid grid-cols-3 gap-8">
<?php foreach ( $a['features'] as $feature ) : ?>
<div>
<?php if ( $feature['icon'] ) : ?>
<?php bs_render_icon( $feature['icon'] ); ?>
<?php endif; ?>
<h3><?php echo esc_html( $feature['title'] ); ?></h3>
<p><?php echo esc_html( $feature['description'] ); ?></p>
</div>
<?php endforeach; ?>
</div>
Benutzerdefinierte Zeilenbeschriftungen
Standardmäßig zeigen minimierte Repeater-Zeilen eine allgemeine Beschriftung. Verwende textMinimized, um stattdessen einen Feldwert anzuzeigen:
{
"id": "team",
"type": "repeater",
"label": "Team Members",
"textMinimized": { "id": "name", "fallback": "Team Member" },
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "role", "type": "text", "label": "Role" },
{ "id": "photo", "type": "files", "label": "Photo", "multiple": false }
]
}
Wenn eine Zeile eingeklappt ist, wird statt „Zeile 1“ der Name der Person angezeigt. fallback wird verwendet, wenn das Namensfeld leer ist. Du kannst auch die Zeichenfolgen prefix und suffix hinzufügen.
Bedingungen in Repeatern
Felder in einem Repeater können über ihre unveränderten id (ohne Präfix) auf andere Felder derselben Zeile verweisen:
{
"id": "links",
"type": "repeater",
"label": "Links",
"attributes": [
{ "id": "label", "type": "text", "label": "Label" },
{ "id": "url", "type": "link", "label": "URL" },
{
"id": "isExternal",
"type": "toggle",
"label": "External Link"
},
{
"id": "externalNote",
"type": "message",
"label": "Note",
"description": "External links open in a new tab with rel=\"noopener\".",
"conditions": [[{ "id": "isExternal", "operator": "==", "value": true }]]
}
]
}
Von einem Repeater aus auf äußere Felder verweisen
Wenn eine Bedingung in einem Repeater ein Feld außerhalb des Repeaters prüfen muss, füge "context": "main" hinzu:
{
"id": "showDescriptions",
"type": "toggle",
"label": "Show Descriptions",
"default": true
},
{
"id": "items",
"type": "repeater",
"label": "Items",
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{
"id": "description",
"type": "textarea",
"label": "Description",
"conditions": [[{
"id": "showDescriptions",
"operator": "==",
"value": true,
"context": "main"
}]]
}
]
}
Ohne "context": "main" würde die Bedingung im Repeater eine showDescriptions-Feldzeile suchen. Damit prüft sie den Umschalter auf der obersten Ebene.
Tabs in Repeatern
Tabs sind in Repeatern nicht verfügbar: Ein tabs-Feld innerhalb einer Repeater-Zeile zeigt im Editor einen Hinweis statt seiner Felder an, und die Erweiterung PHPStan meldet dies. Halte die Felder einer Zeile stattdessen flach. Bei langen Zeilen sorgt eine benutzerdefinierte Zeilenbeschriftung (textMinimized) dafür, dass eingeklappte Zeilen lesbar bleiben. Bedingungen innerhalb der Zeile können Felder ausblenden, die nur manche Zeilen benötigen, wie in den obigen Mustern gezeigt.
Setze "minimized": true bei einem Repeater, damit vorhandene Zeilen zunächst eingeklappt sind. Neu hinzugefügte Zeilen werden sofort geöffnet. Ausgeklappte Ausnahmen werden in diesem Browser über das erneute Laden des Editors hinweg gespeichert. Das ist eine Bearbeitungseinstellung und kein gespeicherter Beitragsinhalt.
Repeater ohne minimized behalten ihr bisheriges Verhalten bei, standardmäßig ausgeklappt zu sein.
Medienmuster
Einzelbild mit Fallback
{
"id": "image",
"type": "files",
"label": "Image",
"multiple": false
}
<?php if ( $a['image'] ) : ?>
<img
src="<?php echo esc_url( $a['image']['url'] ); ?>"
alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
<?php if ( isset( $a['image']['sizes']['full-width'], $a['image']['sizes']['full-height'] ) ) : ?>
width="<?php echo esc_attr( $a['image']['sizes']['full-width'] ); ?>"
height="<?php echo esc_attr( $a['image']['sizes']['full-height'] ); ?>"
<?php endif; ?>
/>
<?php endif; ?>
Der Standardwert für returnFormat ist "object". Damit erhältst du ID, title, alt, caption, description, href, url und sizes. sizes enthält die URL aller registrierten Bildgrößen (sizes['large']) samt Abmessungen (sizes['large-width'], sizes['large-height']). Die vollständige Liste findest du unter Rendering-Attribute.
Galerie mit Begrenzung
{
"id": "gallery",
"type": "files",
"label": "Gallery",
"multiple": true,
"max": 6,
"allowedTypes": ["image"]
}
<?php if ( $a['gallery'] ) : ?>
<div class="grid grid-cols-3 gap-4">
<?php foreach ( $a['gallery'] as $image ) : ?>
<img
src="<?php echo esc_url( $image['url'] ); ?>"
alt="<?php echo esc_attr( $image['alt'] ); ?>" />
<?php endforeach; ?>
</div>
<?php endif; ?>
Deaktivierbares Bild mit Schalter
Die Eigenschaft switch fügt ein Augensymbol hinzu, mit dem Nutzer das Feld deaktivieren können, ohne den Wert zu löschen:
{
"id": "logo",
"type": "files",
"label": "Logo",
"multiple": false,
"switch": true
}
<?php
$is_disabled = ! empty( $a['_disabled'] ) && in_array( 'logo', $a['_disabled'], true );
if ( $a['logo'] && ! $is_disabled ) : ?>
<img src="<?php echo esc_url( $a['logo']['url'] ); ?>" alt="" />
<?php endif; ?>
Nutzer können das Logo ausschalten, ohne die hochgeladene Datei zu entfernen. Beim erneuten Einschalten wird dieselbe Datei wieder angezeigt.
Varianten des Rückgabeformats
Lege fest, was das Dateifeld zurückgibt:
// Full object (default)
{ "id": "photo", "type": "files", "returnFormat": "object", "multiple": false }
// $a['photo']['url'], $a['photo']['alt'], $a['photo']['sizes']['full-width'], etc.
// Just the ID
{ "id": "photo", "type": "files", "returnFormat": "id", "multiple": false }
// $a['photo'] = 42
// Just the URL
{ "id": "photo", "type": "files", "returnFormat": "url", "multiple": false }
// $a['photo'] = "https://example.com/photo.jpg"
Verwende "id", wenn du wp_get_attachment_image() selbst aufrufen musst. Verwende "url" für einfache Hintergrundbilder. Für alles andere eignet sich "object" (der Standardwert).
Mit "returnFormat": "id" wird ein importierter Zeichenfolgenverweis wie "buckshair-home" unverändert übergeben. Der Editor zeigt eine Ersatzkarte ohne Miniaturbild an, auch in Repeater-Zeilen. Wenn du die Seite öffnest oder speicherst, wird ein skalarer Verweis nicht in ein Array umgewandelt. Auch gemischte Listen mit Anhang-IDs und Zeichenfolgenverweisen funktionieren. Nur positive Anhang-IDs werden in der Medienbibliothek gesucht.
Blockstudio löst benutzerdefinierte Zeichenfolgenverweise nicht zu Anhängen auf. Wenn du portable Namen über verschiedene Websites hinweg verwendest, löse sie in deinem eigenen Render-Filter oder Template auf. Wenn du in der Medienbibliothek einen Ersatz auswählst, wird wie üblich dessen Anhang-ID gespeichert.
Dynamische Optionen
Mit Beiträgen befüllen
Ein Auswahlfeld, das alle veröffentlichten Seiten auflistet:
{
"id": "linkedPage",
"type": "select",
"label": "Linked Page",
"stylisedUi": true,
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "page",
"post_status": "publish",
"posts_per_page": -1
}
}
}
Das Feld wird automatisch mit Seitentiteln als Beschriftungen und Beitrags-IDs als Werten befüllt. Verwende returnFormat in der Befüllungskonfiguration, um die Zuordnung anzupassen:
"populate": {
"type": "query",
"query": "posts",
"arguments": { "post_type": "page" },
"returnFormat": { "value": "ID", "label": "post_title" }
}
Mit Taxonomiebegriffen befüllen
{
"id": "category",
"type": "select",
"label": "Category",
"stylisedUi": true,
"populate": {
"type": "query",
"query": "terms",
"arguments": {
"taxonomy": "category",
"hide_empty": true
}
}
}
Mit einer PHP-Funktion befüllen
{
"id": "postType",
"type": "select",
"label": "Post Type",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": { "public": true }
}
}
Statische Optionen mit ergänzten dynamischen Optionen
Kombiniere festgelegte Optionen mit dynamischen. Verwende position, um zu steuern, wo die befüllten Optionen erscheinen:
{
"id": "source",
"type": "select",
"label": "Source",
"options": [
{ "value": "manual", "label": "Manual Entry" },
{ "value": "latest", "label": "Latest Posts" }
],
"populate": {
"type": "query",
"query": "posts",
"arguments": { "post_type": "page" },
"position": "after"
}
}
Zuerst erscheinen die statischen Optionen, gefolgt von den dynamisch befüllten Seiten.
Daten für Abfragen speichern
Standardmäßig liegen Feldwerte in Blockattributen innerhalb von post_content. Sie lassen sich nicht mit WP_Query abfragen. Wenn du Beiträge anhand eines Feldwerts filtern oder sortieren möchtest, verwende die Speicherung.
Beitrags-Metadaten für abfragbare Felder
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
},
{
"id": "priority",
"type": "number",
"label": "Priority",
"default": 0,
"min": 0,
"max": 100,
"storage": {
"type": "postMeta",
"postMetaKey": "priority_score"
}
}
Jetzt kannst du nach hervorgehobenen Beiträgen suchen:
$featured = new WP_Query( array(
'meta_query' => array(
array(
'key' => 'is_featured',
'value' => '1',
),
),
'orderby' => 'meta_value_num',
'meta_key' => 'priority_score',
'order' => 'DESC',
) );
Die Metadaten-Schlüssel werden automatisch mit show_in_rest registriert und sind daher auch in REST API verfügbar.
Doppelte Speicherung
Speichere die Daten sowohl in Blockattributen als auch in Beitrags-Metadaten. Das Blockattribut hält den Wert über $a in Vorlagen verfügbar, während er durch die Beitrags-Metadaten abfragbar wird:
{
"id": "eventDate",
"type": "date",
"label": "Event Date",
"storage": {
"type": ["block", "postMeta"],
"postMetaKey": "event_date"
}
}
Option-Speicherung für globale Werte
Verwende die Option-Speicherung für Website-weite Einstellungen, die überall gleich sein sollen:
{
"id": "companyName",
"type": "text",
"label": "Company Name",
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
Der Wert wird in wp_options gespeichert und ist überall über get_option('site_company_name') verfügbar. Wenn der Nutzer dieses Feld in einer beliebigen Blockinstanz bearbeitet, wird der Wert global aktualisiert.
Wiederverwendbare Felddefinitionen
Wenn mehrere Blöcke dieselbe Feldstruktur verwenden, definiere sie einmal als benutzerdefiniertes Feld und verweise überall darauf.
Benutzerdefiniertes Feld erstellen
Erstelle ein field.json im blockstudio/fields/-Verzeichnis deines Themes:
theme/
└── blockstudio/
└── fields/
└── cta/
└── field.json
{
"name": "cta",
"title": "Call to Action",
"attributes": [
{ "id": "label", "type": "text", "label": "Button Label", "default": "Learn More" },
{ "id": "url", "type": "link", "label": "Button URL" },
{ "id": "style", "type": "select", "label": "Button Style", "default": "primary", "options": [
{ "value": "primary", "label": "Primary" },
{ "value": "secondary", "label": "Secondary" },
{ "value": "outline", "label": "Outline" }
]}
]
}
Benutzerdefiniertes Feld verwenden
Verweise in einem beliebigen Block mit "type": "custom/cta" darauf:
{
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading" },
{ "type": "custom/cta" }
]
}
}
Die CTA-Felder werden in den Block eingefügt. Greife direkt darauf zu: $a['label'], $a['url'], $a['style'].
Benutzerdefinierte Felder mit idStructure präfixieren
Wenn du dasselbe benutzerdefinierte Feld mehrmals verwendest, füge idStructure hinzu, um den IDs ein Präfix voranzustellen:
{
"blockstudio": {
"attributes": [
{ "type": "custom/cta", "idStructure": "primary_{id}" },
{ "type": "custom/cta", "idStructure": "secondary_{id}" }
]
}
}
Die Felder des ersten CTA erhalten primary_label, primary_url, primary_style. Die des zweiten erhalten secondary_label usw.
Standardwerte überschreiben
Passe bestimmte Felder an, wenn du auf ein benutzerdefiniertes Feld verweist:
{
"type": "custom/cta",
"idStructure": "hero_{id}",
"overrides": {
"label": { "default": "Get Started", "label": "CTA Label" },
"style": { "default": "primary" }
}
}
Überschreibungen werden mit der ursprünglichen Definition zusammengeführt. Du kannst Standardwerte, Beschriftungen, Bedingungen und andere Eigenschaften ändern.
Muster zum Rendern
Auf leere Werte prüfen
Die meisten Feldtypen geben im leeren Zustand false zurück. Prüfe den Wert immer, bevor du ihn ausgibst:
<?php if ( $a['title'] ) : ?>
<h2><?php echo esc_html( $a['title'] ); ?></h2>
<?php endif; ?>
Bei Zahlen ist 0 ein gültiger Wert. Verwende einen strikten Vergleich, wenn du zwischen „leer“ und „null“ unterscheiden musst:
<?php if ( $a['count'] !== 0 || $a['count'] !== false ) : ?>
<span><?php echo esc_html( $a['count'] ); ?></span>
<?php endif; ?>
Auswahlfeld mit returnFormat: both
Wenn du sowohl den Wert (für die Logik) als auch die Beschriftung (für die Anzeige) benötigst:
{
"id": "status",
"type": "select",
"label": "Status",
"returnFormat": "both",
"options": [
{ "value": "active", "label": "Active" },
{ "value": "paused", "label": "On Hold" },
{ "value": "closed", "label": "Closed" }
]
}
<?php if ( $a['status'] ) : ?>
<span class="badge badge--<?php echo esc_attr( $a['status']['value'] ); ?>">
<?php echo esc_html( $a['status']['label'] ); ?>
</span>
<?php endif; ?>
Datenattribute aus dem attributes-Feld
Nutzer können mit dem Feldtyp attributes eigene Datenattribute hinzufügen:
{
"id": "dataAttrs",
"type": "attributes",
"label": "Data Attributes",
"link": true,
"media": true
}
<div useBlockProps <?php bs_render_data_attributes( $a['dataAttrs'] ); ?>>
Content here.
</div>
CSS-Variablen aus Feldwerten
Erzeuge eigene CSS-Eigenschaften aus ausgewählten Feldern:
{
"id": "textColor", "type": "color", "label": "Text Color"
},
{
"id": "fontSize", "type": "unit", "label": "Font Size", "default": "1rem"
}
<div useBlockProps style="<?php bs_render_variables( $a, array( 'textColor', 'fontSize' ) ); ?>">
<p>Styled content.</p>
</div>
Das gibt style="--text-color: #333; --font-size: 1rem;" aus (Feld-IDs werden in kebab-case umgewandelt). Verwende die Variablen in deinem CSS:
p {
color: var(--text-color);
font-size: var(--font-size);
}
Nächste Schritte
- Attribute registrieren: die Eigenschaften
id,type,label,default,help,positionundconditions. - Referenz zu Feldtypen: automatisch generierte Referenz mit jeder Eigenschaft aller Feldtypen.
- Bedingte Logik: Operatoren, globale Bedingungen, eigene Bedingungsfilter und Repeater-Kontext.
- Optionen befüllen: Abfrage-, Funktions-, eigene und Fetch-Modi für dynamische Auswahlfelder.
- Benutzerdefinierte Felder:
field.json, Suchpfade, derblockstudio/fields-Filter und erweiterteidStructure-Muster. - Rendern:
$a,$b,$c, leere Werte und Hilfsfunktionen.