Preskočiť na obsah

Kontext blokov a komunikácia

Väčšina blokov je samostatná. Majú vlastné polia, vlastnú šablónu a nezaujíma ich, čo sa nachádza okolo nich. Niektoré komponenty však prirodzene tvoria hierarchiu: mriežka kariet, v ktorej nadradený blok riadi počet stĺpcov a medzery, cenová tabuľka, v ktorej nadradený blok nastavuje menu, alebo obal sekcie, ktorý svojim podradeným blokom určuje, či majú použiť svetlú alebo tmavú tému.

WordPress poskytuje kontext bloku API. Nadradený blok sprístupňuje časť svojich údajov a podradené bloky sa na ne prihlasujú. Keď sa nadradený blok zmení, podradené bloky sa automaticky aktualizujú. Blockstudio to výrazne zjednodušuje: providesContext nemusíte konfigurovať vôbec. Každý blok Blockstudio automaticky poskytuje všetky svoje atribúty ako kontext. Podradeným blokom stačí pridať jeden riadok do block.json, aby sa prihlásili na odber.

Táto príručka predstavuje štyri vzory komponentov z praxe, ktoré využívajú kontext, pričom každý ukazuje inú potrebu komunikácie.

Ako funguje kontext v Blockstudio

V štandardnom WordPress musíte každý atribút nadradeného bloku explicitne priradiť ku kľúču kontextu v providesContext a potom tieto kľúče uviesť v usesContext podradeného bloku. Blockstudio prvý krok úplne odstraňuje.

Nadradený blok: Nie je potrebná žiadna konfigurácia. Každý blok Blockstudio automaticky poskytuje všetky svoje atribúty pod názvom svojho bloku.

Podradený blok: Pridajte usesContext s názvom nadradeného bloku:

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

Šablóna podradeného bloku: Prístup k atribútom nadradeného bloku cez $context (alebo skrátený zápis $c):

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

To je celé nastavenie. V nadradenom bloku netreba providesContext, mapovanie atribútov ani registračný kód. Podradený blok dostane všetky transformované atribúty nadradeného bloku, čo znamená, že mediálne polia sa prevedú na údaje prílohy, výberové polia rešpektujú returnFormat a opakovače sa úplne rozbalia.

Dva druhy kontextu

Blockstudio poskytuje v šablónach dve kontextové premenné, ktoré slúžia na rôzne účely:

Premenná Obsah Použitie
$context / $c Atribúty nadradeného bloku (cez usesContext) Komunikácia komponentov
$block['context'] / $b['context'] Údaje cyklu WordPress (postId, postType) Cykly bloku Query

Prvý slúži blokom na komunikáciu s ich nadradenými blokmi. Druhý slúži blokom v cykle Query, ktoré potrebujú vedieť, ktorý príspevok práve vykresľujú. Táto príručka sa zameriava na prvý druh.

Podpora v editore

Aktualizácie kontextu sú v editore reaktívne. Keď používateľ zmení hodnotu poľa nadradeného bloku, všetky podradené bloky prihlásené na odber kontextu tohto bloku sa automaticky znova vykreslia s novou hodnotou. Nie je potrebné manuálne obnovovanie.

Obal sekcie

Najbežnejší vzor kontextu: obalový blok, ktorý poskytuje podradeným blokom nastavenia témy. Nadradený blok má polia pre farbu pozadia, farbu textu a odsadenie. Podradené bloky čítajú tieto hodnoty, aby sa ich vzhľad zladil.

Nadradený blok: Sekcia

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>

Podradený blok: Nadpis sekcie

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>

Čo to ukazuje: Nadpis nemá vlastné pole farby. Z kontextu číta hodnotu theme sekcie a prispôsobuje sa jej. Keď používateľ v editore prepne sekciu z „Svetlá“ na „Tmavá“, farba textu nadpisu sa okamžite aktualizuje.

Vlastnosť parent v block.json podradeného bloku obmedzuje miesta, kam možno blok vložiť. V ponuke na vkladanie sa zobrazí iba vtedy, keď sa používateľ nachádza v bloku my-theme/section. Je to voliteľné, ale odporúča sa to pri blokoch, ktoré dávajú zmysel iba v rámci konkrétneho nadradeného bloku.

Podradený blok: Text sekcie

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>

Teraz nadpis aj text reagujú na tému sekcie. Používateľ vyberie tému raz v nadradenom bloku a každý podradený blok sa jej prispôsobí.

Mriežka kariet

Nadradený blok mriežky riadi nastavenia rozloženia podradených kariet. Definuje počet stĺpcov a medzery. Podradené bloky využívajú tieto hodnoty, aby rozpoznali kontext svojho rozloženia a podľa toho upravili svoj vzhľad.

Nadradený blok: Mriežka kariet

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>

Podradený blok: Karta

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>

Čo to ukazuje: Karta nemá vlastné pole štýlu. Hodnotu cardStyle číta z nadradenej mriežky. Keď používateľ zmení štýl mriežky z „Zvýraznený“ na „S obrysom“, všetky karty v mriežke sa naraz aktualizujú. Karty tak zostanú vizuálne jednotné bez toho, aby ich používateľ musel aktualizovať jednotlivo.

Atribút template na <InnerBlocks> predvyplní mriežku tromi kartami, ktoré používateľovi poslúžia ako východiskový bod.

Cenová tabuľka

Pokročilejší vzor, v ktorom nadradený blok poskytuje zdieľanú obchodnú logiku (menu a fakturačné obdobie), ktorú podradené bloky používajú pri zobrazovaní. Predchádza sa tak zbytočnému opakovaniu rovnakých polí v každej cenovej úrovni.

Nadradený blok: Cenová tabuľka

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>

Podradený blok: Cenová úroveň

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>

Čo to ukazuje: Symbol meny a fakturačné obdobie sa nastavia raz v cenovej tabuľke a zdedia ich všetky úrovne. Keď používateľ zmení menu z USD na EUR, symbol meny sa vo všetkých troch úrovniach aktualizuje súčasne. Bez kontextu by ste museli pole meny duplikovať v každej úrovni a manuálne ich udržiavať zosúladené.

Kontext cyklu Query

WordPress poskytuje v cykloch bloku Query samostatný druh kontextu. Keď sa blok vykresľuje v cykle, $block['context'] (alebo $b['context']) obsahuje údaje o príspevku v aktuálnej iterácii:

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>

Líši sa to od kontextu nadradeného bloku ($context / $c). Kontext cyklu poskytuje jadro WordPress a obsahuje iba postId a postType. Na tento účel nepotrebujete usesContext vo svojom block.json. Blockstudio automaticky prihlasuje každý blok na odber postId a postType.

Kedy sa hodí kontext cyklu: vlastné karty príspevkov v blokoch Query, bloky zobrazujúce metadáta príspevkov alebo akýkoľvek blok, ktorý potrebuje vykresľovať odlišný obsah pre každý príspevok v cykle.

Môžete pristupovať aj k údajom o príspevku na vonkajšej stránke bez ohľadu na kontext cyklu:

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

Vnorený kontext

Kontext prechádza celým stromom blokov, nielen jednou úrovňou. Ak blok A obsahuje blok B, ktorý obsahuje blok C, blok C sa môže prihlásiť na odber kontextu bloku A. Funguje to preto, že WordPress šíri kontext cez všetky úrovne InnerBlocks.

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

Nadpis nemusí byť priamym podradeným blokom sekcie. Môže byť vnorený v blokoch jadra (stĺpcoch, skupinách a podobne) a stále dostávať kontext sekcie. Prihlásenie na odber cez usesContext funguje v akejkoľvek hĺbke.

Viacero nadradených blokov

Podradený blok sa môže prihlásiť na odber kontextu viacerých nadradených blokov:

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';
?>

Ak sa nadradený blok nenájde v strome predkov, jeho kľúč bude v $context chýbať. Pri čítaní hodnôt kontextu vždy použite operátor null coalescing (??) alebo skontrolujte isset(), ak by sa blok mohol použiť mimo očakávaného nadradeného bloku.

Ošetrenie chýb

Bloky využívajúce kontext by mali vždy ošetriť prípad, keď nadradený blok chýba. Používateľ môže vložiť blok mimo nadradeného bloku, pre ktorý je určený, alebo nadradený blok nemusí mať nastavenú hodnotu konkrétneho poľa.

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

Ak chcete vynútiť, aby sa podradený blok zobrazoval iba v nadradenom bloku, pridajte vlastnosť parent:

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

Blok sa tak odstráni z ponuky na vkladanie, keď používateľ nie je v bloku my-theme/section. Bez vlastnosti parent sa blok zobrazuje všade a za správne ošetrenie chýbajúceho kontextu zodpovedá šablóna.

Použite parent pri blokoch, ktoré mimo svojho kontajnera nemajú zmysel (cenové úrovne, položky mriežky kariet). Vynechajte ho pri blokoch, ktoré fungujú samostatne, ale získavajú od nadradeného bloku ďalšie štýlovanie (nadpisy sekcií, ktoré sa dajú použiť aj samostatne).

Tipy

Kontext je iba na čítanie. Podradené bloky nemôžu cez kontext meniť atribúty nadradeného bloku. Údaje prúdia nadol, nikdy nie nahor. Ak podradený blok potrebuje komunikovať s nadradeným, použite iný prístup (napríklad zdieľaný stav na serveri cez API Interactivity alebo metadáta príspevku).

Poskytujú sa všetky atribúty. Blockstudio poskytuje všetky atribúty nadradeného bloku, nielen tie, ktoré vyberiete. Podradený blok tak môže pristupovať ku každému poľu definovanému nadradeným blokom. Ak nadradený blok neskôr dostane nové pole, podradené bloky k nemu získajú prístup automaticky bez zmeny konfigurácie.

Transformované hodnoty. Hodnoty kontextu prechádzajú transformačným procesom atribútov Blockstudio. Polia súborov obsahujú úplné údaje o prílohe (url, alt, width, height), výberové polia rešpektujú returnFormat a opakovače sa rekurzívne rozbalia. Získate rovnakú dátovú štruktúru ako $a v šablóne nadradeného bloku.

Reaktivita editora. Keď používateľ v editore zmení pole nadradeného bloku, podradené bloky sa automaticky znova vykreslia. Využíva sa pritom vstavané šírenie kontextu v WordPress s React useEffect, ktorý zisťuje zmeny kontextu a spúšťa opätovné vykreslenie podradeného bloku na strane servera.

Udržujte kontext stručný. Hoci Blockstudio automaticky poskytuje všetky atribúty nadradeného bloku, podradené bloky by mali čítať iba hodnoty, ktoré skutočne potrebujú. Nejde o výkon, pretože údaje už sú k dispozícii, ale o zrozumiteľnosť kódu. Zdokumentujte, od ktorých polí nadradeného bloku závisí podradený blok, aby budúci vývojári poznali tieto súvislosti.

Ďalšie kroky

  • Referencia ku kontextu: premenné šablón, kontext cyklu a dátová štruktúra $block.
  • InnerBlocks: komponent <InnerBlocks />, allowedBlocks, šablóny a filter obalu na frontende.
  • Príručka Interactivity: reaktivita na strane klienta medzi blokmi (Interactivity API rieši to, čo kontext nedokáže: komunikáciu od podradeného bloku k nadradenému, stav zdieľaný medzi blokmi a aktualizácie vyvolané používateľom).