Preskoči na vsebino

Kontekst blokov in komunikacija

Večina blokov je samostojnih. Imajo svoja polja in svojo predlogo, zato jih ne zanima, kaj jih obdaja. Nekatere komponente pa so po naravi hierarhične: mreža kartic, v kateri nadrejeni blok določa število stolpcev in razmik, cenik, v katerem nadrejeni blok nastavi valuto, ali ovijalnik razdelka, ki podrejenim blokom pove, ali naj uporabijo svetlo ali temno temo.

WordPress za to zagotavlja kontekst bloka API. Nadrejeni blok izpostavi nekatere svoje podatke, podrejeni bloki pa se nanje naročijo. Ko se nadrejeni blok spremeni, se podrejeni bloki samodejno posodobijo. Blockstudio to precej poenostavi: providesContext vam sploh ni treba nastaviti. Vsak blok Blockstudio samodejno zagotovi vse svoje atribute kot kontekst. Podrejeni bloki potrebujejo le eno vrstico v svoji block.json, da se naročijo nanj.

Ta vodnik predstavi štiri praktične vzorce komponent, ki uporabljajo kontekst, pri čemer vsak prikazuje drugačno potrebo po komunikaciji.

Kako deluje kontekst v Blockstudio

V standardnem WordPress morate vsak atribut nadrejenega bloka izrecno preslikati v ključ konteksta v providesContext, nato pa te ključe navesti v usesContext podrejenega bloka. Blockstudio prvi korak v celoti odpravi.

Nadrejeni blok: Nastavitev ni potrebna. Vsak blok Blockstudio samodejno zagotovi vse svoje atribute pod imenom bloka.

Podrejeni blok: Dodajte usesContext z imenom nadrejenega bloka:

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

Predloga podrejenega bloka: Do atributov nadrejenega bloka dostopajte prek $context (ali skrajšane oblike $c):

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

To je vsa nastavitev. V nadrejenem bloku ni providesContext, preslikave atributov ali registracijske kode. Podrejeni blok prejme vse pretvorjene atribute nadrejenega bloka, kar pomeni, da se predstavnostna polja razrešijo v podatke o prilogah, izbirna polja upoštevajo returnFormat, ponavljalniki pa se v celoti razširijo.

Dve vrsti konteksta

Blockstudio v predlogah zagotavlja dve kontekstni spremenljivki, ki imata različna namena:

Spremenljivka Vsebina Primer uporabe
$context / $c Atributi nadrejenega bloka (prek usesContext) Komunikacija med komponentami
$block['context'] / $b['context'] Podatki zanke WordPress (postId, postType) Zanke blokov Query

Prva je namenjena komunikaciji blokov z njihovimi nadrejenimi. Druga je za bloke znotraj zanke Query, ki morajo vedeti, katero objavo upodabljajo. Ta vodnik obravnava prvo vrsto.

Podpora v urejevalniku

Posodobitve konteksta so v urejevalniku reaktivne. Ko uporabnik spremeni vrednost polja nadrejenega bloka, se vsi podrejeni bloki, naročeni na kontekst tega nadrejenega bloka, samodejno znova upodobijo z novo vrednostjo. Ročna osvežitev ni potrebna.

Ovijalnik razdelka

Najpogostejši vzorec s kontekstom je blok ovijalnika, ki podrejenim blokom zagotavlja nastavitve teme. Nadrejeni blok ima polja za barvo ozadja, barvo besedila in notranji odmik. Podrejeni bloki te vrednosti preberejo, da se dosledno oblikujejo.

Nadrejeni blok: razdelek

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>

Podrejeni blok: naslov razdelka

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>

Kaj prikazuje ta primer: Naslov nima svojega polja za barvo. Vrednost theme razdelka prebere iz konteksta in se ji prilagodi. Ko uporabnik v urejevalniku spremeni razdelek iz »Svetlo« v »Temno«, se barva besedila naslova takoj posodobi.

Lastnost parent v block.json podrejenega bloka omeji, kam je blok mogoče vstaviti. Vstavljalnik ga prikaže le, ko je uporabnik znotraj bloka my-theme/section. To ni obvezno, vendar je priporočljivo za bloke, ki so smiselni le znotraj določenega nadrejenega bloka.

Podrejeni blok: besedilo razdelka

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>

Zdaj se na temo razdelka odzivata tako naslov kot besedilo. Uporabnik izbere temo enkrat v nadrejenem bloku, vsak podrejeni blok pa se ji prilagodi.

Mreža kartic

Nadrejeni blok mreže upravlja nastavitve postavitve za svoje podrejene kartice. Določa število stolpcev in razmik. Podrejeni bloki te vrednosti uporabijo za razumevanje konteksta postavitve in ustrezno prilagodijo svoj slog.

Nadrejeni blok: mreža kartic

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>

Podrejeni blok: kartica

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>

Kaj prikazuje ta primer: Kartica nima svojega polja za slog. Vrednost cardStyle prebere iz nadrejenega bloka mreže. Ko uporabnik spremeni mrežo iz »Dvignjeno« v »Obrobljeno«, se vse kartice v mreži posodobijo hkrati. Tako kartice ostanejo vizualno usklajene, ne da bi moral uporabnik vsako posodobiti posebej.

Atribut template v <InnerBlocks> vnaprej napolni mrežo s tremi karticami, ki uporabniku služijo kot izhodišče.

Cenik

Naprednejši vzorec, pri katerem nadrejeni blok zagotavlja skupno poslovno logiko (valuto, obračunsko obdobje), ki jo podrejeni bloki uporabijo pri prikazu. Tako se izognete podvajanju istih polj v vseh cenovnih paketih.

Nadrejeni blok: cenik

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>

Podrejeni blok: cenovni paket

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>

Kaj prikazuje ta primer: Simbol valute in obračunsko obdobje sta določena enkrat v ceniku in ju podedujejo vsi paketi. Ko uporabnik spremeni USD v EUR, se simbol valute v vseh treh paketih posodobi hkrati. Brez konteksta bi morali polje za valuto podvojiti v vsakem paketu in ga ročno usklajevati.

Kontekst zanke Query

WordPress zagotavlja ločeno vrsto konteksta znotraj zank blokov Query. Ko se blok upodobi znotraj zanke, $block['context'] (ali $b['context']) vsebuje podatke o objavi trenutne iteracije:

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>

To se razlikuje od konteksta nadrejenega bloka ($context / $c). Kontekst zanke zagotavlja jedro WordPress in vsebuje samo postId ter postType. Za to v svoji block.json ne potrebujete usesContext. Blockstudio samodejno naroči vsak blok na postId in postType.

Kje je kontekst zanke uporaben: Za lastne kartice objav znotraj blokov Query, bloke, ki prikazujejo metapodatke objave, ali poljubne bloke, ki morajo za vsako objavo v zanki ustvariti drugačen prikaz.

Dostopate lahko tudi do podatkov o objavi na zunanji strani, ne glede na kontekst zanke:

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

Gnezdeni kontekst

Kontekst se prenaša po celotnem drevesu blokov, ne le za eno raven. Če blok A vsebuje blok B, ta pa blok C, se lahko C naroči na kontekst bloka A. To deluje, ker WordPress širi kontekst na vse ravni elementa InnerBlocks.

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

Naslov ni nujno neposreden podrejeni blok razdelka. Lahko je ugnezden v jedrnih blokih (stolpcih, skupinah itd.) in še vedno prejema kontekst razdelka. Naročnina usesContext deluje na poljubni globini.

Več nadrejenih blokov

Podrejeni blok se lahko naroči na več nadrejenih 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';
?>

Če nadrejenega bloka ni v drevesu prednikov, njegov ključ ne bo na voljo v $context. Pri branju vrednosti konteksta vedno uporabite operator združevanja z ničelno vrednostjo (??) ali preverite isset(), če bi bil blok uporabljen zunaj pričakovanega nadrejenega bloka.

Obrambno programiranje

Bloki, ki uporabljajo kontekst, morajo vedno obravnavati primer, ko nadrejeni blok manjka. Uporabnik lahko blok vstavi zunaj predvidenega nadrejenega bloka ali pa nadrejeni blok nima nastavljene vrednosti za določeno polje.

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

Če želite zagotoviti, da se podrejeni blok pojavi samo znotraj nadrejenega, dodajte lastnost parent:

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

S tem blok odstranite iz vstavljalnika, kadar uporabnik ni znotraj bloka my-theme/section. Brez parent se blok prikaže povsod, za pravilno obravnavo manjkajočega konteksta pa je odgovorna predloga.

Uporabite parent za bloke, ki so zunaj vsebnika nesmiselni (cenovni paketi, elementi mreže kartic). Izpustite ga pri blokih, ki delujejo samostojno, vendar jim nadrejeni blok doda slog (naslovi razdelkov, ki jih je mogoče uporabiti tudi samostojno).

Nasveti

Kontekst je samo za branje. Podrejeni bloki ne morejo spreminjati atributov nadrejenega bloka prek konteksta. Podatki se prenašajo navzdol, nikoli navzgor. Če mora podrejeni blok komunicirati z nadrejenim, potrebujete drugačen pristop (na primer skupno stanje strežnika prek API Interactivity ali metapodatke objave).

Na voljo so vsi atributi. Blockstudio zagotavlja vse atribute nadrejenega bloka, ne le izbranih. To pomeni, da lahko podrejeni blok dostopa do poljubnega polja, ki ga določa nadrejeni blok. Če nadrejeni blok pozneje dobi novo polje, je to podrejenim blokom samodejno na voljo brez spremembe nastavitev.

Pretvorjene vrednosti. Vrednosti konteksta gredo skozi cevovod za pretvorbo atributov v Blockstudio. Polja datotek vsebujejo celotne podatke o prilogi (url, alt, width, height), izbirna polja upoštevajo returnFormat, ponavljalniki pa se rekurzivno razširijo. Dobite enako podatkovno strukturo kot $a v predlogi nadrejenega bloka.

Reaktivnost urejevalnika. Ko uporabnik v urejevalniku spremeni polje nadrejenega bloka, se podrejeni bloki samodejno znova upodobijo. To uporablja vgrajeno širjenje konteksta v WordPress in React useEffect, ki zazna spremembe konteksta in sproži ponovno upodabljanje podrejenega bloka na strežniku.

Naj bo kontekst jedrnat. Čeprav Blockstudio samodejno zagotavlja vse atribute nadrejenega bloka, naj podrejeni bloki berejo samo vrednosti, ki jih dejansko potrebujejo. To ni vprašanje zmogljivosti (podatki so že na voljo), temveč jasnosti kode. Zabeležite, od katerih polj nadrejenega bloka je podrejeni odvisen, da bodoči razvijalci razumejo povezavo.

Naslednji koraki

  • Referenca konteksta: spremenljivke predlog, kontekst zanke in podatkovna struktura $block.
  • InnerBlocks: komponenta <InnerBlocks />, allowedBlocks, predloge in filter ovijalnika vmesnika.
  • Vodnik po interaktivnosti: za reaktivnost na strani odjemalca med bloki (API Interactivity obravnava, česar kontekst ne zmore: komunikacijo od podrejenega do nadrejenega bloka, stanje med bloki in posodobitve na zahtevo uporabnika).