Blokcontext en communicatie
De meeste blokken staan op zichzelf. Ze hebben hun eigen velden en sjabloon en trekken zich niets aan van hun omgeving. Sommige componenten zijn echter van nature hiërarchisch: een kaartraster waarbij het bovenliggende blok het aantal kolommen en de tussenruimte bepaalt, een prijstabel waarbij het bovenliggende blok de valuta instelt, of een sectieomsluiting die de onderliggende blokken vertelt of ze een licht of donker thema moeten gebruiken.
WordPress biedt hiervoor een blokcontext API. Een bovenliggend blok stelt een deel van zijn gegevens beschikbaar en onderliggende blokken abonneren zich daarop. Wanneer het bovenliggende blok verandert, worden de onderliggende blokken automatisch bijgewerkt. Blockstudio maakt dit aanzienlijk eenvoudiger: je hoeft providesContext helemaal niet te configureren. Elk Blockstudio blok biedt automatisch al zijn attributen als context aan. Onderliggende blokken hoeven slechts één regel toe te voegen aan hun block.json om zich erop te abonneren.
In deze gids bouw je vier componentpatronen uit de praktijk die context gebruiken. Elk patroon laat een andere communicatiebehoefte zien.
Hoe context werkt in Blockstudio
In standaard-WordPress moet je elk attribuut van het bovenliggende blok expliciet aan een contextsleutel koppelen in providesContext en die sleutels vervolgens vermelden in de usesContext van het onderliggende blok. Blockstudio slaat de eerste stap helemaal over.
Bovenliggend blok: Geen configuratie nodig. Elk Blockstudio blok biedt automatisch al zijn attributen aan onder de naam van het blok.
Onderliggend blok: Voeg usesContext toe met de naam van het bovenliggende blok:
{
"usesContext": ["my-theme/parent-block"]
}
Sjabloon van het onderliggende blok: Gebruik $context om attributen van het bovenliggende blok op te halen (of de verkorte notatie $c):
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>
Dat is de volledige configuratie. Geen providesContext in het bovenliggende blok, geen attribuutkoppeling en geen registratiet code. Het onderliggende blok ontvangt alle getransformeerde attributen van het bovenliggende blok. Mediavelden worden dus omgezet naar bijlagegegevens, selectievelden respecteren returnFormat en herhalers worden volledig uitgewerkt.
Twee soorten context
Blockstudio biedt twee contextvariabelen in sjablonen, elk voor een ander doel:
| Variabele | Bevat | Gebruik |
|---|---|---|
$context / $c |
Attributen van het bovenliggende blok (via usesContext) |
Communicatie tussen componenten |
$block['context'] / $b['context'] |
WordPress lusgegevens (postId, postType) |
Lussen in queryblokken |
De eerste is bedoeld voor blokken die met hun bovenliggende blok communiceren. De tweede voor blokken in een Query-lus die moeten weten welk bericht ze weergeven. Deze gids richt zich op de eerste soort.
Ondersteuning in de editor
Contextupdates zijn reactief in de editor. Wanneer een gebruiker de veldwaarde van een bovenliggend blok wijzigt, worden alle onderliggende blokken die zich op de context van dat blok abonneren automatisch opnieuw weergegeven met de nieuwe waarde. Handmatig vernieuwen is niet nodig.
Sectieomsluiting
Het meest voorkomende contextpatroon: een omsluitingsblok dat thema-instellingen aan de onderliggende blokken doorgeeft. Het bovenliggende blok heeft velden voor achtergrondkleur, tekstkleur en opvulling. De onderliggende blokken lezen deze waarden om hun stijl consistent te houden.
Bovenliggend blok: Sectie
{
"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
$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>
Onderliggend blok: Sectiekop
{
"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
$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>
Wat dit laat zien: De kop heeft geen eigen kleurveld. De kop leest de waarde theme van de sectie uit de context en past zich eraan aan. Wanneer de gebruiker de sectie in de editor van “Licht” naar “Donker” schakelt, verandert de tekstkleur van de kop direct.
De eigenschap parent in de block.json van het onderliggende blok beperkt waar het blok kan worden ingevoegd. Het verschijnt alleen in het invoegmenu wanneer de gebruiker zich in een my-theme/section blok bevindt. Dit is optioneel, maar aanbevolen voor blokken die alleen zinvol zijn binnen een specifiek bovenliggend blok.
Onderliggend blok: Sectietekst
{
"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
$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>
Nu reageren zowel de kop als de tekst op het thema van de sectie. De gebruiker kiest één keer een thema voor het bovenliggende blok en elk onderliggend blok past zich eraan aan.
Kaartraster
Een rasterblok dat de lay-outinstellingen voor de kaarten erin beheert. Het bovenliggende blok bepaalt het aantal kolommen en de tussenruimte. De onderliggende blokken gebruiken deze waarden om hun lay-outcontext te bepalen en hun stijl daarop aan te passen.
Bovenliggend blok: Kaartraster
{
"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
$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>
Onderliggend blok: Kaart
{
"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
$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>
Wat dit laat zien: De kaart heeft geen eigen stijleigenschap. De kaart leest cardStyle uit het bovenliggende rasterblok. Wanneer de gebruiker het raster van “Verhoogd” naar “Omlijnd” schakelt, worden alle kaarten in het raster tegelijk bijgewerkt. Zo blijven de kaarten visueel consistent zonder dat de gebruiker ze stuk voor stuk hoeft aan te passen.
Het attribuut template op <InnerBlocks> vult het raster vooraf met drie kaarten, zodat de gebruiker een startpunt heeft.
Prijstabel
Een geavanceerder patroon waarin het bovenliggende blok gedeelde bedrijfslogica aanbiedt, zoals de valuta en factureringsperiode, die de onderliggende blokken voor hun weergave gebruiken. Zo hoef je dezelfde velden niet op elke prijstrede te dupliceren.
Bovenliggend blok: Prijstabel
{
"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" }
]
}
]
}
}
<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>
Onderliggend blok: Prijstrede
{
"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
$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">✓</span>
<?php echo esc_html( $feature['text'] ); ?>
</li>
<?php endforeach; ?>
</ul>
<?php endif; ?>
</div>
Wat dit laat zien: Het valutasymbool en de factureringsperiode worden één keer in de prijstabel ingesteld en door elke trede overgenomen. Wanneer de gebruiker van USD naar EUR schakelt, veranderen de valutasymbolen van alle drie de treden tegelijk. Zonder context zou je het valutaveld op elke trede moeten dupliceren en ze handmatig gelijk moeten houden.
Context van querylussen
WordPress biedt een afzonderlijke contextsoort binnen lussen van Query-blokken. Wanneer een blok binnen een lus wordt weergegeven, bevat $block['context'] (of $b['context']) de berichtgegevens van de huidige iteratie:
<?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>
Dit verschilt van de context van een bovenliggend blok ($context / $c). De luscontext wordt door de kern van WordPress aangeboden en bevat alleen postId en postType. Hiervoor hoef je usesContext niet in je block.json te gebruiken. Blockstudio abonneert elk blok automatisch op postId en postType.
Waar luscontext handig is: Aangepaste berichtkaarten in Query-blokken, blokken die berichtmeta weergeven of elk blok dat in een lus per bericht anders moet worden weergegeven.
Je kunt ook de berichtgegevens van de buitenste pagina ophalen, ongeacht de luscontext:
$outer_post_id = $block['postId']; // always the current page
$loop_post_id = $block['context']['postId']; // current loop iteration
Geneste context
Context loopt door de hele blokstructuur, niet slechts één niveau diep. Als blok A blok B bevat en blok B blok C, kan C zich abonneren op de context van A. Dit werkt omdat WordPress context op elk niveau van InnerBlocks doorgeeft.
my-theme/section (theme: "dark")
└── core/columns
└── core/column
└── my-theme/section-heading (reads section context)
De kop hoeft geen direct onderliggend blok van de sectie te zijn. De kop kan genest zijn in kernblokken (kolommen, groepen enzovoort) en ontvangt nog steeds de context van de sectie. De usesContext-abonnement werkt op elke diepte.
Meerdere bovenliggende blokken
Een onderliggend blok kan zich abonneren op meerdere bovenliggende blokken:
{
"usesContext": ["my-theme/section", "my-theme/card-grid"]
}
<?php
$section = $context['my-theme/section'] ?? array();
$grid = $context['my-theme/card-grid'] ?? array();
$theme = $section['theme'] ?? 'light';
$cardStyle = $grid['cardStyle'] ?? 'elevated';
?>
Als een bovenliggend blok niet in de voorouderstructuur voorkomt, ontbreekt de sleutel ervan in $context. Gebruik altijd de null-coalescentieoperator (??) of controleer isset() wanneer je contextwaarden uitleest, voor het geval het blok buiten het verwachte bovenliggende blok wordt gebruikt.
Defensief programmeren
Blokken die context gebruiken, moeten altijd rekening houden met het ontbreken van het bovenliggende blok. Een gebruiker kan het blok buiten het bedoelde bovenliggende blok invoegen, of het bovenliggende blok heeft mogelijk geen waarde ingesteld voor een bepaald veld.
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>
Als je wilt afdwingen dat een onderliggend blok alleen binnen het bovenliggende blok verschijnt, voeg je de eigenschap parent toe:
{
"parent": ["my-theme/section"]
}
Hierdoor verdwijnt het blok uit het invoegmenu wanneer de gebruiker zich niet in een my-theme/section blok bevindt. Zonder parent verschijnt het blok overal en is het aan je sjabloon om ontbrekende context op een nette manier af te handelen.
Gebruik parent voor blokken die buiten hun container geen betekenis hebben (prijstreden, kaartitems in een raster). Laat dit weg voor blokken die zelfstandig werken, maar met extra stijl van een bovenliggend blok (sectiekoppen die ook los gebruikt kunnen worden).
Tips
Context is alleen-lezen. Onderliggende blokken kunnen de attributen van het bovenliggende blok niet via context wijzigen. Gegevens gaan omlaag, nooit omhoog. Als een onderliggend blok iets aan het bovenliggende blok moet doorgeven, heb je een andere aanpak nodig, zoals gedeelde serverstatus via de Interactivity API of berichtmeta.
Alle attributen worden aangeboden. Blockstudio biedt elk attribuut van het bovenliggende blok aan, niet alleen de attributen die je selecteert. Het onderliggende blok kan dus elk veld gebruiken dat het bovenliggende blok definieert. Als het bovenliggende blok later een veld toevoegt, hebben onderliggende blokken er automatisch toegang toe; configuratiewijzigingen zijn niet nodig.
Getransformeerde waarden. Contextwaarden doorlopen de attribuuttransformatiepijplijn van Blockstudio. Bestandsvelden bevatten alle bijlagegegevens (url, alt, width, height), selectievelden respecteren returnFormat en herhalers worden recursief uitgewerkt. Je krijgt dezelfde gegevensstructuur als $a in het sjabloon van het bovenliggende blok.
Reactiviteit in de editor. Wanneer een gebruiker een veld van het bovenliggende blok in de editor wijzigt, worden onderliggende blokken automatisch opnieuw weergegeven. Dit gebruikt de ingebouwde contextdoorgifte van WordPress met een React useEffect die contextwijzigingen detecteert en een serverweergave van het onderliggende blok start.
Houd de context beperkt. Hoewel Blockstudio automatisch alle attributen van het bovenliggende blok aanbiedt, moeten onderliggende blokken alleen de waarden uitlezen die ze echt nodig hebben. Dit is geen prestatiekwestie (de gegevens zijn er al), maar een kwestie van duidelijke code. Documenteer van welke velden van het bovenliggende blok een onderliggend blok afhankelijk is, zodat toekomstige ontwikkelaars de relatie begrijpen.
Volgende stappen
- Contextreferentie: sjabloonvariabelen, luscontext en de gegevensstructuur
$block. - InnerBlocks: de component
<InnerBlocks />,allowedBlocks, sjablonen en het frontend-wrapperfilter. - Handleiding over interactiviteit: voor reactiviteit aan de clientzijde tussen blokken (de Interactivity API handelt af wat context niet kan: communicatie van onderliggend naar bovenliggend blok, status tussen blokken en updates door gebruikers).