Kontext bloků a komunikace
Většina bloků je samostatná. Mají vlastní pole, vlastní šablonu a nezajímá je, co je obklopuje. Některé komponenty jsou ale přirozeně hierarchické: mřížka karet, jejíž nadřazený blok řídí počet sloupců a mezery, ceníková tabulka, v níž nadřazený blok nastavuje měnu, nebo obal sekce, který dětem určuje, zda mají použít světlý, nebo tmavý motiv.
WordPress k tomu nabízí kontext bloků API. Nadřazený blok zpřístupní část svých dat a podřazené bloky se k nim přihlásí. Když se nadřazený blok změní, podřazené bloky se automaticky aktualizují. Blockstudio to výrazně zjednodušuje: providesContext nemusíte konfigurovat vůbec. Každý blok Blockstudio automaticky zpřístupňuje všechny své atributy jako kontext. Podřazeným blokům stačí jediný řádek v jejich block.json, aby se přihlásily.
Tento průvodce představuje čtyři praktické vzory komponent využívající kontext, z nichž každý ukazuje jinou potřebu komunikace.
Jak funguje kontext v Blockstudio
Ve standardním WordPress musíte v providesContext výslovně namapovat každý atribut nadřazeného bloku na klíč kontextu a pak tyto klíče uvést v usesContext podřazeného bloku. Blockstudio první krok zcela odstraňuje.
Nadřazený blok: Není potřeba žádná konfigurace. Každý blok Blockstudio automaticky zpřístupňuje všechny své atributy pod názvem svého bloku.
Podřazený blok: Přidejte usesContext s názvem nadřazeného bloku:
{
"usesContext": ["my-theme/parent-block"]
}
Šablona podřazeného bloku: K atributům nadřazeného bloku přistupujte přes $context (nebo zkrácený zápis $c):
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>
To je celé nastavení. V nadřazeném bloku není potřeba providesContext, mapování atributů ani registrační kód. Podřazený blok dostane všechny transformované atributy nadřazeného bloku, takže mediální pole se převedou na data přílohy, výběrová pole respektují returnFormat a opakovače jsou plně rozbaleny.
Dva druhy kontextu
Blockstudio zpřístupňuje v šablonách dvě kontextové proměnné, které slouží k různým účelům:
| Proměnná | Obsah | Použití |
|---|---|---|
$context / $c |
Atributy nadřazeného bloku (prostřednictvím usesContext) |
Komunikace mezi komponentami |
$block['context'] / $b['context'] |
Data smyčky WordPress (postId, postType) |
Smyčky dotazovacích bloků |
První slouží blokům ke komunikaci s jejich nadřazenými bloky. Druhý je určen blokům uvnitř smyčky Query, které potřebují vědět, který příspěvek vykreslují. Tento průvodce se zaměřuje na první druh.
Podpora v editoru
Změny kontextu se v editoru promítají okamžitě. Když uživatel změní hodnotu pole nadřazeného bloku, všechny podřazené bloky přihlášené k jeho kontextu se automaticky znovu vykreslí s novou hodnotou. Není potřeba ruční obnovení.
Obal sekce
Nejběžnější vzor kontextu: obalový blok, který dětem poskytuje nastavení motivu. Nadřazený blok má pole pro barvu pozadí, barvu textu a vnitřní odsazení. Podřazené bloky tyto hodnoty čtou, aby se jednotně stylovaly.
Nadřazený blok: Sekce
{
"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>
Podřazený blok: Nadpis sekce
{
"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>
Co tento příklad ukazuje: Nadpis nemá vlastní pole pro barvu. Z kontextu čte hodnotu theme sekce a přizpůsobí se jí. Když uživatel v editoru přepne sekci ze „Světlé“ na „Tmavé“, barva textu nadpisu se okamžitě změní.
Vlastnost parent v block.json podřazeného bloku omezuje místa, kam lze blok vložit. V nabídce pro vkládání se zobrazí pouze tehdy, když je uživatel uvnitř bloku my-theme/section. Tato možnost je nepovinná, doporučuje se však u bloků, které dávají smysl pouze uvnitř konkrétního nadřazeného bloku.
Podřazený blok: Text sekce
{
"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>
Nadpis i text nyní reagují na motiv sekce. Uživatel vybere motiv jednou v nadřazeném bloku a všechny podřazené bloky se mu přizpůsobí.
Mřížka karet
Nadřazený blok mřížky řídí nastavení rozvržení podřazených karet. Určuje počet sloupců a mezery. Podřazené bloky tyto hodnoty používají k pochopení kontextu svého rozvržení a odpovídajícím úpravám stylů.
Nadřazený blok: Mřížka karet
{
"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>
Podřazený blok: Karta
{
"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>
Co tento příklad ukazuje: Karta nemá vlastní pole stylu. Hodnotu cardStyle čte z nadřazené mřížky. Když uživatel přepne mřížku z „Vystouplé“ na „Ohraničené“, všechny karty v mřížce se aktualizují najednou. Karty tak zůstávají vizuálně jednotné, aniž by uživatel musel každou upravovat zvlášť.
Atribut template na <InnerBlocks> předvyplní mřížku třemi kartami, což uživateli poskytne výchozí bod.
Ceníková tabulka
Pokročilejší vzor, v němž nadřazený blok poskytuje sdílenou obchodní logiku (měnu a fakturační období), kterou podřazené bloky používají při zobrazování. Díky tomu není třeba opakovat stejná pole v každé cenové úrovni.
Nadřazený blok: Ceníková tabulka
{
"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>
Podřazený blok: Cenová úroveň
{
"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>
Co tento příklad ukazuje: Symbol měny a fakturační období se nastavují jednou v ceníkové tabulce a přebírají je všechny cenové úrovně. Když uživatel přepne z USD na EUR, symbol měny se ve všech třech úrovních změní současně. Bez kontextu byste museli pole měny opakovat v každé úrovni a ručně udržovat jejich shodu.
Kontext smyčky dotazu
Existuje také samostatný druh kontextu, který WordPress poskytuje uvnitř smyček bloků Query. Když se blok vykresluje uvnitř smyčky, proměnná $block['context'] (nebo $b['context']) obsahuje data příspěvku pro aktuální průchod:
<?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>
To se liší od kontextu nadřazeného bloku ($context / $c). Kontext smyčky poskytuje jádro WordPress a obsahuje pouze postId a postType. Kvůli tomu není potřeba usesContext v block.json. Blockstudio automaticky přihlásí každý blok k postId a postType.
Kde se kontext smyčky hodí: Vlastní karty příspěvků uvnitř bloků Query, bloky zobrazující metadata příspěvku nebo jakýkoli blok, který se má v rámci smyčky vykreslovat pro každý příspěvek jinak.
Můžete také přistupovat k datům příspěvku z vnější stránky bez ohledu na kontext smyčky:
$outer_post_id = $block['postId']; // always the current page
$loop_post_id = $block['context']['postId']; // current loop iteration
Vnořený kontext
Kontext prochází celým stromem bloků, nejen o jednu úroveň. Pokud blok A obsahuje blok B a ten obsahuje blok C, může se blok C přihlásit ke kontextu bloku A. Funguje to proto, že WordPress předává kontext všemi úrovněmi InnerBlocks.
my-theme/section (theme: "dark")
└── core/columns
└── core/column
└── my-theme/section-heading (reads section context)
Nadpis nemusí být přímým podřazeným blokem sekce. Může být vnořený uvnitř základních bloků (sloupců, skupin atd.) a stále dostávat kontext sekce. Přihlášení k usesContext funguje v libovolné hloubce.
Více nadřazených bloků
Podřazený blok se může přihlásit k více nadřazeným blokům:
{
"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';
?>
Pokud se nadřazený blok ve stromu předků nenajde, jeho klíč v $context nebude. Při čtení hodnot kontextu vždy použijte operátor null coalescing (??) nebo ověřte isset() pro případ, že se blok použije mimo očekávaný nadřazený blok.
Ošetření chybových stavů
Bloky využívající kontext by měly vždy počítat s tím, že nadřazený blok nemusí být přítomen. Uživatel může vložit blok mimo zamýšlený nadřazený blok nebo nadřazený blok nemusí mít pro určité pole nastavenou hodnotu.
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>
Pokud chcete zajistit, aby se podřazený blok zobrazoval pouze uvnitř svého nadřazeného bloku, přidejte vlastnost parent:
{
"parent": ["my-theme/section"]
}
Tím blok zmizí z nabídky pro vkládání, když uživatel není uvnitř bloku my-theme/section. Bez parent se blok zobrazuje všude a vaše šablona musí chybějící kontext správně ošetřit.
Použijte parent u bloků, které mimo svůj obal nemají smysl (cenové úrovně, položky mřížky karet). Vynechte ji u bloků, které fungují samostatně, ale získávají další styl od nadřazeného bloku (například nadpisy sekcí, které lze použít i samostatně).
Tipy
Kontext je pouze pro čtení. Podřazené bloky nemohou prostřednictvím kontextu měnit atributy nadřazeného bloku. Data proudí dolů, nikdy nahoru. Pokud podřazený blok potřebuje komunikovat s nadřazeným, je potřeba jiný přístup (například sdílený stav na serveru prostřednictvím API Interactivity nebo metadata příspěvku).
Zpřístupňují se všechny atributy. Blockstudio poskytuje všechny atributy nadřazeného bloku, nejen ty, které vyberete. Podřazený blok tak může přistupovat ke kterémukoli poli definovanému nadřazeným blokem. Pokud nadřazený blok později přidá nové pole, podřazené bloky k němu získají přístup automaticky bez změny konfigurace.
Transformované hodnoty. Hodnoty kontextu procházejí transformačním řetězcem atributů Blockstudio. Pole souborů obsahují úplná data přílohy (url, alt, width, height), výběrová pole respektují returnFormat a opakovače se rekurzivně rozbalují. Získáte stejnou datovou strukturu jako $a v šabloně nadřazeného bloku.
Reaktivita editoru. Když uživatel v editoru změní pole nadřazeného bloku, podřazené bloky se automaticky znovu vykreslí. Využívá se přitom vestavěné předávání kontextu v WordPress a React useEffect, který zjišťuje změny kontextu a spouští opětovné vykreslení podřazeného bloku na straně serveru.
Udržujte kontext úsporný. Ačkoli Blockstudio automaticky zpřístupňuje všechny atributy nadřazeného bloku, podřazené bloky by měly číst jen hodnoty, které skutečně potřebují. Nejde o výkon (data už jsou k dispozici), ale o přehlednost kódu. Zdokumentujte, na kterých polích nadřazeného bloku podřazený blok závisí, aby budoucí vývojáři znali jejich vztah.
Další kroky
- Referenční příručka ke kontextu: proměnné šablon, kontext smyčky a datová struktura
$block. - InnerBlocks: komponenta
<InnerBlocks />,allowedBlocks, šablony a filtr obalu frontendu. - Průvodce Interactivity: reaktivita na straně klienta mezi bloky (API Interactivity řeší to, co kontext neumí: komunikaci od podřazeného bloku k nadřazenému, stav napříč bloky a aktualizace vyvolané uživatelem).