Liigu sisu juurde

Plokkide kontekst ja suhtlus

Enamik plokke on iseseisvad. Neil on oma väljad ja mall ning neid ei huvita, mis nende ümber on. Mõned komponendid on aga loomult hierarhilised: kaardiruudustik, kus ema määrab veergude arvu ja vahed; hinnatabel, kus ema määrab valuuta; sektsiooniümbris, mis ütleb oma alamelementidele, kas kasutada heledat või tumedat kujundust.

WordPress pakub selleks ploki konteksti API. Emaplokk avalikustab osa oma andmetest ja alamplokid tellivad need. Kui ema muutub, uuenevad alamad automaatselt. Blockstudio lihtsustab seda märkimisväärselt: te ei pea providesContext üldse seadistama. Iga Blockstudio plokk annab automaatselt kontekstina edasi kõik oma atribuudid. Alamplokkidel tuleb tellimiseks lisada vaid üks rida oma block.json-i.

Selles juhendis luuakse neli päriselulist konteksti kasutavat komponendimustrit, millest igaüks näitab erinevat suhtlusvajadust.

Kuidas kontekst Blockstudio-is toimib

Tavalises WordPress-is tuleb iga ema atribuudi ja kontekstivõtme vastavus selgesõnaliselt määrata failis providesContext ning seejärel loetleda need võtmed alama usesContext-is. Blockstudio jätab esimese sammu täielikult ära.

Emaplokk: seadistamist pole vaja. Iga Blockstudio plokk annab kõik oma atribuudid automaatselt edasi ploki nime all.

Alamplokk: lisage usesContext koos emaploki nimega:

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

Alamploki mall: pääsete ema atribuutidele ligi $context (või lühivormi $c) kaudu:

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

See ongi kogu seadistus. Emas pole vaja providesContext-i, atribuutide vastendamist ega registreerimiskoodi. Alam saab kõik ema teisendatud atribuudid: meediaväljad lahendatakse manuse andmeteks, valikuväljad järgivad returnFormat ja kordajad laiendatakse täielikult.

Kaks konteksti tüüpi

Blockstudio pakub mallides kahte kontekstimuutujat, millel on eri otstarve:

Muutuja Sisaldab Kasutusjuht
$context / $c Emaploki atribuudid (usesContext kaudu) Komponentidevaheline suhtlus
$block['context'] / $b['context'] WordPress tsükli andmed (postId, postType) Päringubloki tsüklid

Esimene võimaldab plokkidel suhelda oma emaga. Teine on mõeldud päringutsüklis olevatele plokkidele, mis peavad teadma, millist postitust nad renderdavad. See juhend keskendub esimesele tüübile.

Toe olemasolu redaktoris

Redaktoris uuendatakse konteksti reaktiivselt. Kui kasutaja muudab emaploki välja väärtust, renderdatakse kõik selle konteksti tellinud alamplokid automaatselt uue väärtusega uuesti. Käsitsi värskendada pole vaja.

Sektsiooniümbris

Levinuim kontekstimuster on ümbrisplokk, mis annab oma alamplokkidele kujunduse seaded. Emal on taustavärvi, teksti värvi ja täidise väljad. Alamplokid loevad neid väärtusi, et end ühtselt kujundada.

Ema: sektsioon

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>

Alam: sektsiooni pealkiri

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>

Mida see näitab: pealkirjal pole oma värvivälja. See loeb kontekstist sektsiooni theme väärtuse ja kohandub selle järgi. Kui kasutaja vahetab redaktoris sektsiooni kujunduse „Heledast” „Tumedaks”, uuendatakse pealkirja teksti värv kohe.

Alama block.json-i parent atribuut piirab ploki sisestamise kohti. Plokk ilmub lisajas ainult siis, kui kasutaja on my-theme/section ploki sees. See on valikuline, kuid soovitatav plokkide puhul, millel on mõtet ainult kindla ema sees.

Alam: sektsiooni tekst

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>

Nüüd reageerivad nii pealkiri kui ka tekst sektsiooni kujundusele. Kasutaja valib kujunduse korra emal ja iga alam kohandub sellega.

Kaardiruudustik

Ruudustiku emaplokk juhib oma kaardialamplokkide paigutuse seadeid. Ema määrab veerud ja vahed. Alamplokid kasutavad neid väärtusi oma paigutuse mõistmiseks ja kujunduse kohandamiseks.

Ema: kaardiruudustik

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>

Alam: kaart

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>

Mida see näitab: kaardil pole oma kujundusvälja. See loeb ruudustiku emalt väärtuse cardStyle. Kui kasutaja vahetab ruudustiku kujunduse „Reljeefsest” „Kontuuriga” variandiks, uuenevad kõik ruudustiku kaardid korraga. Nii jäävad kaardid visuaalselt ühtseks, ilma et kasutaja peaks igaüht eraldi muutma.

Atribuut template elemendil <InnerBlocks> lisab ruudustikku eeltäidetult kolm kaarti, mis annavad kasutajale lähtepunkti.

Hinnatabel

Keerukamas mustris annab ema edasi jagatud äriloogika (valuuta, arveldusperiood), mida alamad oma kuvas kasutavad. Nii ei pea samu välju igas hinnatasemes kordama.

Ema: hinnatabel

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>

Alam: hinnatase

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>

Mida see näitab: valuutasümbol ja arveldusperiood määratakse hinnatabelis üks kord ning päranduvad igale hinnatasemele. Kui kasutaja vahetab USD eurode vastu, uuenevad kõigi kolme taseme valuutasümbolid korraga. Ilma kontekstita tuleks valuutaväli igale tasemele lisada ja nende väärtusi käsitsi sünkroonis hoida.

Päringutsükli kontekst

On veel üks konteksti tüüp, mida WordPress päringubloki tsüklites pakub. Kui plokk renderdatakse tsükli sees, sisaldab $block['context'] (või $b['context']) parajasti töödeldava iteratsiooni postituse andmeid:

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>

See erineb emaploki kontekstist ($context / $c). Tsükli konteksti annab WordPress tuum ning see sisaldab ainult postId ja postType. Selleks pole vaja usesContext-i oma block.json-is. Blockstudio tellib automaatselt iga ploki postId-i ja postType-i.

Kus tsükli kontekstist kasu on: kohandatud postituskaardid päringublokkides, postituse metaandmeid kuvavad plokid või mis tahes plokk, mis peab tsüklis iga postituse puhul erinevalt renderduma.

Välise lehe postituse andmetele pääsete ligi ka tsükli kontekstist sõltumata:

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

Pesastatud kontekst

Kontekst liigub läbi kogu plokipuu, mitte ainult ühe taseme võrra. Kui plokk A sisaldab plokki B ja see omakorda plokki C, saab C tellida A konteksti. See toimib, sest WordPress levitab konteksti igal InnerBlocks-i tasemel.

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

Pealkiri ei pea olema sektsiooni otsene alamplokk. See võib olla pesastatud tuumplokkide (veerud, rühmad jne) sisse ja saab ikkagi sektsiooni konteksti. usesContext tellimus toimib igal sügavusel.

Mitu ema

Alamplokk saab tellida mitme ema konteksti:

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

Kui ema esivanemate puust ei leita, puudub selle võti $context-ist. Konteksti väärtuste lugemisel kasutage alati nulliga koalestseerimise operaatorit (??) või kontrollige isset() väärtust, juhuks kui plokki kasutatakse väljaspool eeldatud emaploki konteksti.

Tõrkeid ennetav kood

Konteksti kasutavad plokid peaksid alati arvestama olukorraga, kus ema puudub. Kasutaja võib ploki sisestada väljapoole selle ettenähtud emaploki konteksti või emaploki kindlal väljal võib väärtus määramata olla.

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

Kui soovite tagada, et alam ilmub ainult oma ema sees, lisage atribuut parent:

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

See eemaldab ploki lisajast, kui kasutaja pole my-theme/section ploki sees. Ilma atribuudita parent kuvatakse plokki kõikjal ja mall peab puuduva konteksti ise korrektselt lahendama.

Kasutage parent-i plokkide puhul, millel pole väljaspool ümbrist mõtet (hinnatasemed, kaardiruudustiku elemendid). Jätke see vahele plokkide puhul, mis toimivad ka iseseisvalt, kuid saavad emalt lisakujunduse (sektsioonide pealkirjad, mida saab kasutada ka eraldi).

Nõuanded

Kontekst on kirjutuskaitstud. Alamplokid ei saa konteksti kaudu ema atribuute muuta. Andmed liiguvad allapoole, mitte kunagi ülespoole. Kui alam peab emale midagi edastama, vajate muud lähenemist (näiteks jagatud serveripoolset olekut Interactivity API kaudu või postituse metaandmeid).

Edastatakse kõik atribuudid. Blockstudio annab edasi kõik emaploki atribuudid, mitte ainult valitud atribuudid. See tähendab, et alam pääseb ligi igale ema määratud väljale. Kui ema saab hiljem uue välja, saavad alamplokid sellele automaatselt ligi, ilma et midagi tuleks seadistada.

Teisendatud väärtused. Konteksti väärtused läbivad Blockstudio atribuudi teisendamise voo. Failiväljad sisaldavad manuse kõiki andmeid (url, alt, width, height), valikuväljad järgivad returnFormat-i ja kordajad laiendatakse rekursiivselt. Saate sama andmestruktuuri mis ema mallis $a.

Reaktiivsus redaktoris. Kui kasutaja muudab redaktoris ema välja, renderdatakse alamplokid automaatselt uuesti. Selleks kasutatakse WordPress sisseehitatud konteksti levitamist ja React useEffect-i, mis tuvastab konteksti muutused ning käivitab alama serveripoolse uuesti renderdamise.

Hoidke kontekst napp. Kuigi Blockstudio annab kõik ema atribuudid automaatselt edasi, peaksid alamad lugema ainult neid väärtusi, mida neil tegelikult vaja on. See pole jõudluse küsimus (andmed on juba olemas), vaid koodi selguse küsimus. Dokumenteerige, millistest ema väljadest alam sõltub, et tulevased arendajad seda seost mõistaksid.

Järgmised sammud

  • Konteksti viide: mallimuutujad, tsükli kontekst ja andmestruktuur $block.
  • InnerBlocks: komponent <InnerBlocks />, allowedBlocks, mallid ja kasutajaliidese ümbrise filter.
  • Interactivity guide: plokkide kliendipoolseks reaktiivsuseks (Interactivity API katab selle, millega kontekst toime ei tule: alamalt emale suhtlemise, plokkideülese oleku ja kasutaja algatatud uuendused).