Zum Inhalt springen

Block-Kontext und Kommunikation

Die meisten Blöcke sind eigenständig. Sie haben ihre eigenen Felder und Templates und kümmern sich nicht um ihre Umgebung. Manche Komponenten sind jedoch von Natur aus hierarchisch: ein Kartenraster, in dem der übergeordnete Block die Spaltenanzahl und den Abstand festlegt; eine Preistabelle, in der er die Währung bestimmt; oder ein Abschnitts-Wrapper, der seinen untergeordneten Blöcken ein helles oder dunkles Theme vorgibt.

WordPress stellt dafür einen Block-Kontext API bereit. Ein übergeordneter Block gibt einen Teil seiner Daten frei, und untergeordnete Blöcke abonnieren sie. Ändert sich der übergeordnete Block, werden die untergeordneten automatisch aktualisiert. Blockstudio vereinfacht das erheblich: Du musst providesContext gar nicht konfigurieren. Jeder Blockstudio-Block stellt automatisch all seine Attribute als Kontext bereit. Untergeordnete Blöcke brauchen in ihrem block.json nur eine Zeile, um den Kontext zu abonnieren.

Diese Anleitung erstellt vier praxisnahe Komponenten, die Kontext verwenden. Jede zeigt einen anderen Kommunikationsbedarf.

So funktioniert Kontext in Blockstudio

Bei standardmäßigem WordPress musst du jedes Attribut des übergeordneten Blocks in providesContext ausdrücklich einem Kontexteintrag zuordnen und diese Einträge anschließend in usesContext des untergeordneten Blocks aufführen. Blockstudio macht den ersten Schritt überflüssig.

Übergeordneter Block: Keine Konfiguration nötig. Jeder Blockstudio-Block stellt automatisch alle seine Attribute unter seinem Blocknamen bereit.

Untergeordneter Block: Füge usesContext mit dem Namen des übergeordneten Blocks hinzu:

JSON
{
  "usesContext": ["my-theme/parent-block"]
}

Template des untergeordneten Blocks: Greife über $context (oder die Kurzform $c) auf die Attribute des übergeordneten Blocks zu:

PHP
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>

Damit ist alles eingerichtet. Kein providesContext im übergeordneten Block, keine Attributzuordnung und kein Registrierungscode. Der untergeordnete Block erhält alle transformierten Attribute des übergeordneten Blocks. Medienfelder werden dabei zu Anhangsdaten aufgelöst, Auswahlfelder berücksichtigen returnFormat, und Repeater werden vollständig erweitert.

Zwei Arten von Kontext

Blockstudio stellt in Templates zwei Kontextvariablen bereit, die unterschiedlichen Zwecken dienen:

Variable Enthält Anwendungsfall
$context / $c Attribute des übergeordneten Blocks (über usesContext) Kommunikation zwischen Komponenten
$block['context'] / $b['context'] WordPress-Schleifendaten (postId, postType) Schleifen von Query-Blöcken

Die erste dient der Kommunikation zwischen Blöcken und ihren übergeordneten Blöcken. Die zweite ist für Blöcke innerhalb einer Query-Schleife gedacht, die wissen müssen, welchen Beitrag sie gerade rendern. Diese Anleitung konzentriert sich auf die erste Art.

Unterstützung im Editor

Kontextänderungen werden im Editor reaktiv übernommen. Ändert jemand den Feldwert eines übergeordneten Blocks, werden alle untergeordneten Blöcke, die den Kontext dieses übergeordneten Blocks abonnieren, automatisch mit dem neuen Wert neu gerendert. Eine manuelle Aktualisierung ist nicht nötig.

Abschnitts-Wrapper

Das häufigste Kontextmuster: ein Wrapper-Block, der seinen untergeordneten Blöcken Designeinstellungen bereitstellt. Der übergeordnete Block enthält Felder für Hintergrundfarbe, Textfarbe und Innenabstand. Untergeordnete Blöcke lesen diese Werte aus, um sich einheitlich zu gestalten.

Übergeordneter Block: Abschnitt

JSON
{
  "name": "my-theme/section",
  "title": "Section",
  "category": "design",
  "icon": "align-wide",
  "description": "Section wrapper with theme settings.",
  "blockstudio": {
    "attributes": [
      {
        "id": "theme",
        "type": "select",
        "label": "Theme",
        "default": "light",
        "options": [
          { "value": "light", "label": "Light" },
          { "value": "dark", "label": "Dark" },
          { "value": "accent", "label": "Accent" }
        ]
      },
      {
        "id": "spacing",
        "type": "select",
        "label": "Spacing",
        "default": "md",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "md", "label": "Medium" },
          { "value": "lg", "label": "Large" }
        ]
      }
    ]
  }
}
PHP
<?php
$theme_classes = array(
	'light'  => 'bg-white text-gray-900',
	'dark'   => 'bg-gray-900 text-white',
	'accent' => 'bg-indigo-600 text-white',
);
$spacing_classes = array(
	'sm' => 'py-8',
	'md' => 'py-16',
	'lg' => 'py-24',
);
$classes = ( $theme_classes[ $a['theme'] ] ?? '' ) . ' ' . ( $spacing_classes[ $a['spacing'] ] ?? '' );
?>
<div useBlockProps class="<?php echo esc_attr( $classes ); ?>">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/section-heading', 'my-theme/section-text', 'core/columns', 'core/group' ) ) ); ?>'
  />
</div>

Untergeordneter Block: Abschnittsüberschrift

JSON
{
  "name": "my-theme/section-heading",
  "title": "Section Heading",
  "category": "design",
  "icon": "heading",
  "description": "Heading that adapts to section theme.",
  "usesContext": ["my-theme/section"],
  "parent": ["my-theme/section"],
  "blockstudio": {
    "attributes": [
      { "id": "text", "type": "text", "label": "Heading", "default": "Section Title" },
      {
        "id": "size",
        "type": "select",
        "label": "Size",
        "default": "lg",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "lg", "label": "Large" },
          { "value": "xl", "label": "Extra Large" }
        ]
      }
    ]
  }
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';

$color_class = match ( $theme ) {
	'light'  => 'text-gray-900',
	'dark'   => 'text-white',
	'accent' => 'text-white',
	default  => 'text-gray-900',
};

$size_class = match ( $a['size'] ) {
	'sm' => 'text-2xl',
	'lg' => 'text-4xl',
	'xl' => 'text-6xl',
	default => 'text-4xl',
};
?>
<h2 useBlockProps class="<?php echo esc_attr( "$color_class $size_class font-bold" ); ?>">
  <?php echo esc_html( $a['text'] ); ?>
</h2>

Das wird hier gezeigt: Die Überschrift hat kein eigenes Farbfeld. Sie liest den Wert theme des Abschnitts aus dem Kontext und passt sich daran an. Wenn du den Abschnitt im Editor von „Light“ auf „Dark“ umstellst, ändert sich die Textfarbe der Überschrift sofort.

Die Eigenschaft parent im block.json des untergeordneten Blocks schränkt ein, wo du den Block einfügen kannst. Er erscheint nur dann im Inserter, wenn du dich innerhalb eines my-theme/section-Blocks befindest. Das ist optional, empfiehlt sich aber für Blöcke, die nur innerhalb eines bestimmten übergeordneten Blocks sinnvoll sind.

Untergeordneter Block: Abschnittstext

JSON
{
  "name": "my-theme/section-text",
  "title": "Section Text",
  "category": "design",
  "icon": "text",
  "description": "Body text that adapts to section theme.",
  "usesContext": ["my-theme/section"],
  "parent": ["my-theme/section"],
  "blockstudio": {
    "attributes": [
      { "id": "text", "type": "textarea", "label": "Text", "default": "Section body text." }
    ]
  }
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';

$color_class = match ( $theme ) {
	'dark', 'accent' => 'text-white/80',
	default          => 'text-gray-600',
};
?>
<p useBlockProps class="<?php echo esc_attr( "$color_class text-lg leading-relaxed" ); ?>">
  <?php echo esc_html( $a['text'] ); ?>
</p>

Jetzt reagieren sowohl die Überschrift als auch der Text auf das Design des Abschnitts. Du wählst das Design einmal im übergeordneten Block aus, und alle untergeordneten Blöcke passen sich an.

Kartenraster

Ein übergeordneter Rasterblock, der die Layouteinstellungen seiner untergeordneten Karten steuert. Der übergeordnete Block legt Spalten und Abstände fest. Untergeordnete Blöcke verwenden diese Werte, um ihren Layoutkontext zu erkennen und ihr Styling entsprechend anzupassen.

Übergeordneter Block: Kartenraster

JSON
{
  "name": "my-theme/card-grid",
  "title": "Card Grid",
  "category": "design",
  "icon": "grid-view",
  "description": "Responsive card grid with configurable columns.",
  "blockstudio": {
    "attributes": [
      {
        "id": "columns",
        "type": "range",
        "label": "Columns",
        "default": 3,
        "min": 1,
        "max": 4,
        "step": 1
      },
      {
        "id": "gap",
        "type": "select",
        "label": "Gap",
        "default": "md",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "md", "label": "Medium" },
          { "value": "lg", "label": "Large" }
        ]
      },
      {
        "id": "cardStyle",
        "type": "select",
        "label": "Card Style",
        "default": "elevated",
        "options": [
          { "value": "elevated", "label": "Elevated (shadow)" },
          { "value": "outlined", "label": "Outlined (border)" },
          { "value": "flat", "label": "Flat (no decoration)" }
        ]
      }
    ]
  }
}
PHP
<?php
$gap_class = match ( $a['gap'] ) {
	'sm' => 'gap-4',
	'md' => 'gap-6',
	'lg' => 'gap-8',
	default => 'gap-6',
};
?>
<div useBlockProps class="grid grid-cols-<?php echo esc_attr( $a['columns'] ); ?> <?php echo esc_attr( $gap_class ); ?>">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/card' ) ) ); ?>'
    template='<?php echo esc_attr( wp_json_encode( array(
      array( 'my-theme/card', array() ),
      array( 'my-theme/card', array() ),
      array( 'my-theme/card', array() ),
    ) ) ); ?>'
  />
</div>

Untergeordneter Block: Karte

JSON
{
  "name": "my-theme/card",
  "title": "Card",
  "category": "design",
  "icon": "cover-image",
  "description": "Card that inherits style from its grid parent.",
  "usesContext": ["my-theme/card-grid"],
  "parent": ["my-theme/card-grid"],
  "blockstudio": {
    "attributes": [
      { "id": "image", "type": "files", "label": "Image", "multiple": false },
      { "id": "title", "type": "text", "label": "Title", "default": "Card Title" },
      { "id": "description", "type": "textarea", "label": "Description", "default": "Card description goes here." },
      { "id": "url", "type": "link", "label": "Link" }
    ]
  }
}
PHP
<?php
$grid      = $context['my-theme/card-grid'] ?? array();
$card_style = $grid['cardStyle'] ?? 'elevated';

$style_class = match ( $card_style ) {
	'elevated' => 'bg-white rounded-xl shadow-md',
	'outlined' => 'bg-white rounded-xl border border-gray-200',
	'flat'     => 'bg-gray-50 rounded-xl',
	default    => 'bg-white rounded-xl shadow-md',
};
?>
<div useBlockProps class="<?php echo esc_attr( "$style_class overflow-hidden" ); ?>">
  <?php if ( $a['image'] ) : ?>
    <img
      src="<?php echo esc_url( $a['image']['url'] ); ?>"
      alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
      class="w-full aspect-video object-cover" />
  <?php endif; ?>
  <div class="p-6">
    <h3 class="text-lg font-semibold"><?php echo esc_html( $a['title'] ); ?></h3>
    <p class="mt-2 text-gray-600"><?php echo esc_html( $a['description'] ); ?></p>
    <?php if ( $a['url'] ) : ?>
      <a href="<?php echo esc_url( $a['url']['url'] ); ?>" class="mt-4 inline-block text-indigo-600 font-medium">
        <?php echo esc_html( $a['url']['title'] ?: 'Learn more' ); ?>
      </a>
    <?php endif; ?>
  </div>
</div>

Das wird hier gezeigt: Die Karte hat kein eigenes Stilfeld. Sie liest cardStyle aus dem übergeordneten Rasterblock aus. Wenn du das Raster von „Elevated“ auf „Outlined“ umstellst, werden alle Karten im Raster gleichzeitig aktualisiert. So bleiben sie optisch einheitlich, ohne dass du jede Karte einzeln ändern musst.

Das Attribut template auf <InnerBlocks> füllt das Raster mit drei Karten vor und bietet dir so einen Ausgangspunkt.

Preistabelle

Ein fortgeschritteneres Muster, bei dem der übergeordnete Block gemeinsame Geschäftslogik wie Währung und Abrechnungszeitraum bereitstellt, die untergeordnete Blöcke in ihrer Anzeige verwenden. So musst du dieselben Felder nicht in jeder Preisstufe wiederholen.

Übergeordneter Block: Preistabelle

JSON
{
  "name": "my-theme/pricing-table",
  "title": "Pricing Table",
  "category": "text",
  "icon": "money-alt",
  "description": "Pricing comparison with shared currency and billing settings.",
  "blockstudio": {
    "attributes": [
      {
        "id": "currency",
        "type": "select",
        "label": "Currency",
        "default": "usd",
        "options": [
          { "value": "usd", "label": "USD ($)" },
          { "value": "eur", "label": "EUR (\u20ac)" },
          { "value": "gbp", "label": "GBP (\u00a3)" }
        ]
      },
      {
        "id": "period",
        "type": "select",
        "label": "Billing Period",
        "default": "month",
        "options": [
          { "value": "month", "label": "Monthly" },
          { "value": "year", "label": "Yearly" }
        ]
      }
    ]
  }
}
PHP
<div useBlockProps class="grid grid-cols-3 gap-6 items-start">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/pricing-tier' ) ) ); ?>'
    template='<?php echo esc_attr( wp_json_encode( array(
      array( 'my-theme/pricing-tier', array( 'name' => 'Starter', 'price' => 9 ) ),
      array( 'my-theme/pricing-tier', array( 'name' => 'Pro', 'price' => 29, 'highlighted' => true ) ),
      array( 'my-theme/pricing-tier', array( 'name' => 'Enterprise', 'price' => 99 ) ),
    ) ) ); ?>'
  />
</div>

Untergeordneter Block: Preisstufe

JSON
{
  "name": "my-theme/pricing-tier",
  "title": "Pricing Tier",
  "category": "text",
  "icon": "tag",
  "description": "Single pricing tier that reads currency from parent.",
  "usesContext": ["my-theme/pricing-table"],
  "parent": ["my-theme/pricing-table"],
  "blockstudio": {
    "attributes": [
      { "id": "name", "type": "text", "label": "Tier Name", "default": "Plan" },
      { "id": "price", "type": "number", "label": "Price", "default": 0 },
      { "id": "highlighted", "type": "toggle", "label": "Highlighted", "default": false },
      {
        "id": "features",
        "type": "repeater",
        "label": "Features",
        "attributes": [
          { "id": "text", "type": "text", "label": "Feature" }
        ]
      }
    ]
  }
}
PHP
<?php
$table    = $context['my-theme/pricing-table'] ?? array();
$currency = $table['currency'] ?? 'usd';
$period   = $table['period'] ?? 'month';

$symbols = array(
	'usd' => '$',
	'eur' => "\u{20AC}",
	'gbp' => "\u{00A3}",
);
$symbol = $symbols[ $currency ] ?? '$';

$period_label = $period === 'year' ? '/year' : '/month';

$border_class = $a['highlighted'] ? 'border-2 border-indigo-600' : 'border border-gray-200';
?>
<div useBlockProps class="<?php echo esc_attr( "rounded-xl p-8 $border_class" ); ?>">
  <h3 class="text-lg font-semibold"><?php echo esc_html( $a['name'] ); ?></h3>
  <div class="mt-4">
    <span class="text-4xl font-bold"><?php echo esc_html( $symbol . $a['price'] ); ?></span>
    <span class="text-gray-500"><?php echo esc_html( $period_label ); ?></span>
  </div>
  <?php if ( ! empty( $a['features'] ) ) : ?>
    <ul class="mt-6 space-y-3">
      <?php foreach ( $a['features'] as $feature ) : ?>
        <li class="flex items-center gap-2">
          <span class="text-indigo-600">&#10003;</span>
          <?php echo esc_html( $feature['text'] ); ?>
        </li>
      <?php endforeach; ?>
    </ul>
  <?php endif; ?>
</div>

Das wird hier gezeigt: Währungssymbol und Abrechnungszeitraum werden einmal in der Preistabelle festgelegt und von jeder Preisstufe übernommen. Wenn du von USD auf EUR umstellst, aktualisieren sich die Währungssymbole aller drei Preisstufen gleichzeitig. Ohne Kontext müsstest du das Währungsfeld in jeder Preisstufe wiederholen und die Werte manuell synchron halten.

Kontext in Query-Schleifen

Es gibt eine weitere Art von Kontext, die WordPress innerhalb von Query-Block-Schleifen bereitstellt. Wird ein Block innerhalb einer Schleife gerendert, enthält $block['context'] (oder $b['context']) die Beitragsdaten des aktuellen Durchlaufs:

PHP
<?php
$loop_post_id   = $block['context']['postId'];
$loop_post_type = $block['context']['postType'];
?>
<article useBlockProps>
  <h2><?php echo esc_html( get_the_title( $loop_post_id ) ); ?></h2>
  <p><?php echo esc_html( get_the_excerpt( $loop_post_id ) ); ?></p>
  <a href="<?php echo esc_url( get_permalink( $loop_post_id ) ); ?>">Read more</a>
</article>

Das unterscheidet sich vom Kontext übergeordneter Blöcke ($context / $c). Der Schleifenkontext wird vom WordPress-Kern über WordPress bereitgestellt und enthält nur postId und postType. Dafür brauchst du usesContext nicht in deinem block.json. Blockstudio abonniert automatisch für jeden Block postId und postType.

Wann der Schleifenkontext nützlich ist: bei eigenen Beitragskarten innerhalb von Query-Blöcken, bei Blöcken, die Beitragsmetadaten anzeigen, oder allgemein bei Blöcken, die innerhalb einer Schleife je nach Beitrag anders gerendert werden müssen.

Du kannst unabhängig vom Schleifenkontext auch auf die Beitragsdaten der äußeren Seite zugreifen:

PHP
$outer_post_id   = $block['postId'];   // always the current page
$loop_post_id    = $block['context']['postId'];  // current loop iteration

Verschachtelter Kontext

Der Kontext wird durch den gesamten Blockbaum weitergegeben, nicht nur über eine Ebene. Wenn Block A Block B enthält und dieser wiederum Block C, kann C den Kontext von A abonnieren. Das funktioniert, weil WordPress den Kontext durch alle Ebenen von InnerBlocks weitergibt.

Code
my-theme/section (theme: "dark")
└── core/columns
    └── core/column
        └── my-theme/section-heading (reads section context)

Die Überschrift muss kein direkt untergeordneter Block des Abschnitts sein. Sie kann in Kernblöcken wie Spalten oder Gruppen verschachtelt sein und erhält den Kontext des Abschnitts trotzdem. Das Abonnement über usesContext funktioniert auf jeder Verschachtelungstiefe.

Mehrere übergeordnete Blöcke

Ein untergeordneter Block kann den Kontext mehrerer übergeordneter Blöcke abonnieren:

JSON
{
  "usesContext": ["my-theme/section", "my-theme/card-grid"]
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$grid    = $context['my-theme/card-grid'] ?? array();

$theme     = $section['theme'] ?? 'light';
$cardStyle = $grid['cardStyle'] ?? 'elevated';
?>

Wird ein übergeordneter Block im übergeordneten Baum nicht gefunden, fehlt sein Schlüssel in $context. Verwende beim Lesen von Kontextwerten immer den Null-Koaleszenzoperator (??) oder prüfe isset(), falls der Block außerhalb des vorgesehenen übergeordneten Blocks verwendet wird.

Defensive Programmierung

Blöcke, die Kontext verwenden, sollten immer den Fall abfangen, dass der übergeordnete Block fehlt. Jemand könnte den Block außerhalb des vorgesehenen übergeordneten Blocks einfügen, oder für ein bestimmtes Feld des übergeordneten Blocks könnte kein Wert festgelegt sein.

PHP
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>

Wenn du erzwingen möchtest, dass ein untergeordneter Block nur innerhalb seines übergeordneten Blocks erscheint, füge die Eigenschaft parent hinzu:

JSON
{
  "parent": ["my-theme/section"]
}

Damit wird der Block aus dem Inserter entfernt, wenn du dich nicht innerhalb eines my-theme/section-Blocks befindest. Ohne parent erscheint der Block überall; dein Template muss dann fehlenden Kontext zuverlässig abfangen.

Verwende parent für Blöcke, die außerhalb ihres Containers keinen Sinn ergeben, etwa Preisstufen oder Kartenraster-Elemente. Lass es bei Blöcken weg, die eigenständig funktionieren, aber durch das Styling eines übergeordneten Blocks ergänzt werden, etwa Abschnittsüberschriften, die auch einzeln verwendet werden können.

Tipps

Kontext ist schreibgeschützt. Untergeordnete Blöcke können die Attribute des übergeordneten Blocks nicht über den Kontext ändern. Daten fließen nach unten, niemals nach oben. Wenn ein untergeordneter Block etwas an seinen übergeordneten Block übermitteln muss, brauchst du einen anderen Ansatz, etwa einen gemeinsamen Serverzustand über die Interactivity API oder Beitragsmetadaten.

Alle Attribute werden bereitgestellt. Blockstudio stellt alle Attribute des übergeordneten Blocks bereit, nicht nur die ausgewählten. Der untergeordnete Block kann also auf jedes Feld zugreifen, das der übergeordnete Block definiert. Wenn später ein neues Feld hinzukommt, können untergeordnete Blöcke automatisch darauf zugreifen, ohne dass du etwas konfigurieren musst.

Umgewandelte Werte. Kontextwerte durchlaufen die Attributumwandlungspipeline von Blockstudio. Dateifelder enthalten die vollständigen Anhangdaten (url, alt, width, height), Auswahlfelder berücksichtigen returnFormat und Repeater werden rekursiv erweitert. Du erhältst dieselbe Datenstruktur wie über $a im Template des übergeordneten Blocks.

Reaktivität im Editor. Ändert jemand im Editor ein Feld des übergeordneten Blocks, werden untergeordnete Blöcke automatisch neu gerendert. Dafür nutzt WordPress die integrierte Kontextweitergabe mit einem React useEffect, der Kontextänderungen erkennt und ein serverseitiges Neurendern des untergeordneten Blocks auslöst.

Halte den Kontext schlank. Obwohl Blockstudio automatisch alle Attribute des übergeordneten Blocks bereitstellt, sollten untergeordnete Blöcke nur die tatsächlich benötigten Werte auslesen. Das ist keine Frage der Leistung, denn die Daten sind bereits vorhanden, sondern der Übersichtlichkeit des Codes. Dokumentiere, von welchen Feldern des übergeordneten Blocks ein untergeordneter Block abhängt, damit zukünftige Entwickler die Beziehung nachvollziehen können.

Nächste Schritte

  • Kontextreferenz: Template-Variablen, Schleifenkontext und die Datenstruktur $block.
  • InnerBlocks: die Komponente <InnerBlocks />, allowedBlocks, Templates und der Frontend-Wrapper-Filter.
  • Interactivity-Anleitung: für clientseitige Reaktivität zwischen Blöcken (die Interactivity API übernimmt, was der Kontext nicht kann: Kommunikation vom untergeordneten zum übergeordneten Block, blockübergreifender Zustand und durch dich ausgelöste Aktualisierungen).