Přejít k obsahu

Skládání šablon pomocí značek bloků

Jakmile projekt obsahuje několik bloků, šablony začnou potřebovat jedna druhou. Blok s funkcemi chce zobrazit tři karty. Úvodní stránka potřebuje sekci s tlačítkem uvnitř. Každý blok můžete zavolat pomocí bs_render_block(), ale šablona plná volání PHP s vnořenými poli se špatně čte a ještě hůř vnořuje.

Značky bloků umožňují zapsat blok přímo na místo, kde se má zobrazit jeho výstup, jako značku HTML:

HTML
<bs:acme-card title="Fast" text="Rendered on the server." />

Stejná značka znamená různé věci podle toho, kde je zapsaná. V šabloně bloku nebo v obsahu příspěvku se nahradí vykresleným HTML bloku. Ve zdroji stránky, vzoru nebo šablony webu se z ní stane skutečný blok WordPress, který se zobrazí v editoru. V tomto průvodci vytvoříme několik bloků, ukážeme jejich skládání oběma způsoby, přidáme předponu projektu pro kratší názvy a nakonec předvedeme převod těchto zkrácených názvů zpět na přenositelný zápis.

Bloky

Stačí tři malé bloky. Karta se dvěma poli:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title", "default": "" },
      { "id": "text", "type": "textarea", "label": "Text", "default": "" }
    ]
  }
}
PHP
<article useBlockProps class="acme-card">
  <h3><?php echo esc_html( $a['title'] ); ?></h3>
  <p><?php echo esc_html( $a['text'] ); ?></p>
</article>

Sekce, která obalí libovolný vložený obsah, s polem heading deklarovaným stejným způsobem jako u karty:

PHP
<section useBlockProps class="acme-section">
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <InnerBlocks />
</section>

A tlačítko v druhém jmenném prostoru acme-ui/button s poli label a href:

PHP
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>

Značky v šabloně bloku

Šablony bloků značky vykreslují automaticky. Není potřeba nic nastavovat. Blok s funkcemi může přímo vypsat dvě karty a oddělovač jádra:

PHP
<div useBlockProps class="acme-features">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <block name="acme/card" title="Typed" text="Fields come from block.json." />
  <block name="core/separator" />
</div>

Vykreslením acme/features vznikne:

HTML
<!--blockstudio/acme/features--><div class="acme-features wp-block-acme-features">
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Typed</h3>
  <p>Fields come from block.json.</p>
</article>

  <hr class="wp-block-separator has-alpha-channel-opacity">
</div>

Každému bloku Blockstudio ve výstupu předchází komentář <!--blockstudio/namespace/slug-->. Vyrovnávací paměť stránky jej odstraní z odpovědi; pro výstup, který vyrovnávací paměť obchází, použijte bs_strip_render_markers(). Obě syntaxe jsou rovnocenné. <bs:acme-card> kóduje název bloku ve značce a <block name="acme/card"> jej předává jako atribut. Každý další atribut se stává hodnotou pole, takže title se do šablony karty předává jako $a['title']. Fungují i základní bloky, které se vykreslují pomocí WordPress s vestavěnými vykreslovači bloků.

Párové značky a vnitřní obsah

Párová značka předává bloku své potomky. U bloku Blockstudio vyplní <InnerBlocks /> a vnořené značky se vykreslí jako první:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <bs:acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
HTML
<!--blockstudio/acme/section--><section class="acme-section wp-block-acme-section">
  <h2>Why Acme</h2>
  <div>
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme-ui/button--><a class="acme-button wp-block-acme-ui-button" href="/start">Get started</a>

</div>
</section>

Jak se název značky změní na název bloku

Název značky <bs:> neobsahuje lomítko, a tak Blockstudio nějaké najde. Postupně zleva doprava nahrazuje každou pomlčku lomítkem a použije první nalezený zaregistrovaný kandidát. <bs:acme-card> se hned napoprvé vyhodnotí jako acme/card. <bs:acme-ui-button> nejprve zkusí acme/ui-button, nic nenajde a pak se vyhodnotí jako acme-ui/button. Jmenné prostory obsahující pomlčky tak fungují bez jakékoli konfigurace, pokud neexistují oba kandidáti.

Kratší názvy pomocí předpon

<bs:acme-ui-button> je přesné, ale dlouhé. Předpona projektu mapuje krátkou předponu značky na jeden nebo více jmenných prostorů. Nakonfigurujte ji v blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "blockTags": {
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    }
  }
}

Stejnou mapu můžete zaregistrovat také z PHP:

PHP
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
	$prefixes['acme'] = array( 'acme' );
	$prefixes['ui']   = array( 'acme-ui' );

	return $prefixes;
} );

Nyní se <acme-card> vyhodnotí jako acme/card a <ui-button> jako acme-ui/button. Pokud předpona uvádí několik jmenných prostorů, zkoušejí se v daném pořadí a použije se první zaregistrovaný blok. Projektový blok tak může překrýt knihovní blok se stejným zkráceným názvem.

Lze skládat i předpony. <acme-ui-button> nejprve zkusí acme/ui-button. Tento blok neexistuje a zbytek značky ui-button je sám zaregistrovanou značkou s předponou, takže se vyhodnocení přesune na acme-ui/button. Přímá shoda má vždy přednost před vnořenou.

HTML
<bs:acme-section heading="Why Acme">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

Tím se vykreslí přesně stejné HTML jako výše uvedenou kanonickou verzí.

Pro předpony platí několik pravidel:

  • Předpona obsahuje malá písmena a číslice, začíná písmenem a neobsahuje pomlčky.
  • Značka s předponou, kterou nelze přiřadit k žádnému zaregistrovanému bloku, zůstane ve výstupu beze změny, takže <acme-missing title="x" /> zůstane zapsaná tak, jak je.
  • Přesné aliasy z filtru blockstudio/block_tags/tag_aliases mají před předponami přednost. Alias mapuje jednu značku s pomlčkou na jeden blok. Například $aliases['acme-cta'] = 'acme-ui/button'; způsobí, že se tlačítko vykreslí jako <acme-cta>.

Značky s předponami a aliasy se v šablonách bloků vykreslují vedle značek <bs:> a <block> z Blockstudio 7.5.

Atributy

Atributy, které odpovídají ID pole, se stanou hodnotami polí. Dvě předpony mají jiný účel:

  • Atributy data-* se zkopírují na kořenový element vykresleného bloku.
  • Atributy html-* se zkopírují na kořenový element po odebrání předpony, takže z html-id="intro" vznikne id="intro".
HTML
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
HTML
<article data-track="card" id="intro" class="featured">
  <h3>Hi</h3>
  <p>There</p>
</article>

html-class nastaví atribut, nepřipojí hodnotu k jeho stávající hodnotě: vlastní třídy acme-card wp-block-acme-card bloku se odstraní. Pokud má volající přidat bloku třídy, deklarujte pro ně pole a spojte je v šabloně.

Každý jiný atribut, který není deklarovaným polem, se zahodí. Prostý class="wide" u <bs:acme-card> vykreslí kartu bez tohoto atributu. Blockstudio 7.7 takové atributy při zapnutém WP_DEBUG hlásí upozorněním _doing_it_wrong().

Stejné značky ve zdrojových souborech stránek

Ve stránkách založených na souborech, vzorech a šablonách webu se značky nevykreslují. Při parsování zdroje se převedou na bloky, takže se zobrazí v editoru. Tento zdroj stránky:

HTML
<bs:acme-section heading="Why Acme">
  <p>Everything below is a real block.</p>
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

se naparsuje do tohoto zápisu bloků (pro přehlednost jsou doplněny konce řádků):

HTML
<!-- wp:acme/section {"blockstudio":{"attributes":{"heading":"Why Acme"}}} -->
<!-- wp:paragraph --><p>Everything below is a real block.</p><!-- /wp:paragraph -->
<!-- wp:acme/card {"blockstudio":{"attributes":{"title":"Fast","text":"Rendered on the server."}}} /-->
<!-- wp:acme-ui/button {"blockstudio":{"attributes":{"label":"Get started","href":"/start"}}} /-->
<!-- /wp:acme/section -->

Hodnoty polí se ukládají pod blockstudio.attributes, kde je uchovávají bloky Blockstudio. Odstavec i oba vnitřní bloky se stanou vnitřními bloky sekce. Předpony a aliasy se zde vyhodnocují stejně jako v šablonách.

Značky v obsahu příspěvku

Obsah vytvořený v editoru nebo uložený ve widgetech se ve výchozím nastavení nekontroluje. Zapněte vykreslování na úrovni stránky v blockstudio.json:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

Značky v the_content a widget_text se pak vykreslují s prioritou 5. Stejným přepínačem se zaregistruje filtr pro vykreslování značek v libovolném řetězci:

PHP
$html = apply_filters( 'blockstudio/block_tags/render', $content );

Pomocí vzorů allow a deny omezte značky, které lze vykreslit. Vzory přijímají zástupné znaky fnmatch() a vztahují se na všechny zápisy i oba režimy vykreslování:

JSON
{
  "blockTags": {
    "enabled": true,
    "deny": ["acme-ui/*"]
  }
}

S tímto pravidlem zůstanou <acme-ui-button> a <bs:acme-ui-button> ve výstupu nevykreslené. deny má přednost před allow. Filtry blockstudio/block_tags/allow a blockstudio/block_tags/deny mění stejné seznamy z PHP.

Analýza ověřuje kanonický zápis

Rozšíření PHPStan ověřuje značky bloků v šablonách PHP, Twig a Blade. Překlep v poli nebo názvu bloku ohlásí spolu s blokem, na který se název vyhodnotil:

Text
  3      Block tag "acme/card" has unknown attribute "txt" in index.php
         🪪  blockstudio.blockTag.attribute
  4      Block tag references unknown block "acme/cards" in index.php
         🪪  blockstudio.blockTag.unknown

Ve verzi 7.6 se kontrolují značky <bs:> a <block>. Značka s předponou, jako je <acme-card txt="...">, kontrolou neprojde. Blockstudio 7.7 rozšiřuje pravidlo na značky s předponou, zdrojové soubory stránek a mapované elementy HTML. Jeho nápověda také uvádí globální atributy, které značka může předávat dál.

Převod zkrácených názvů na kanonický zápis

Značky s předponou a aliasy usnadňují práci v konkrétním projektu. Vyhodnocují se jen tam, kde jsou načtené filtry a nastavení projektu. Šablona zkopírovaná do jiného projektu, knihovny bloků nebo kontextu programovacího agenta proto ztrácí svůj význam. Zápis <bs:namespace-slug> uvádí skutečný název bloku a funguje všude. Proto jej používají i vlastní příklady, diagnostická hlášení a generovaný výstup nástroje Blockstudio.

Samostatný příkaz převádí zkrácené názvy na tento zápis. Představme si projekt, jehož zdroje stále používají krátké varianty. Je mezi nimi alias, značka neexistujícího bloku i příklad uvnitř ukázky kódu:

PHP
<div useBlockProps class="acme-features">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</div>
PHP
<acme-section heading="Why Acme">
  <acme-cta label="Talk to us" href="/contact" />
  <acme-quote text="Missing block" />
</acme-section>
<pre><code>&lt;acme-card /&gt; <acme-card title="Example" /></code></pre>

Příkaz nenačítá WordPress, proto použije konfiguraci projektu jako soubory JSON uložené mimo prohledávaný strom:

JSON
{ "acme": ["acme"], "ui": ["acme-ui"] }
JSON
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
JSON
{ "acme-cta": "acme-ui/button" }

Nejprve spusťte zkušební režim, který je zároveň výchozí:

Shell
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/acme-tags/prefixes.json \
  --known-blocks=/tmp/acme-tags/blocks.json \
  --aliases=/tmp/acme-tags/aliases.json \
  --report=/tmp/acme-tags/report.json \
  --dry-run
Text
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.

Zpráva uvádí všechna mapování, která by příkaz provedl, i všechny případy, u nichž odmítne cokoli odhadovat:

JSON
{
  "mappings": [
    { "legacy": "acme-card", "canonical": "bs:acme-card", "block": "acme/card", "occurrences": 1 },
    { "legacy": "acme-cta", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 },
    { "legacy": "acme-section", "canonical": "bs:acme-section", "block": "acme/section", "occurrences": 2 },
    { "legacy": "acme-ui-button", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 }
  ],
  "unknown": [
    { "path": "pages/home/index.php", "line": 3, "column": 4, "tag": "acme-quote", "reason": "no-known-block" }
  ],
  "manual": [
    { "path": "pages/home/index.php", "line": 5, "column": 33, "tag": "acme-card", "reason": "code-sample" }
  ]
}

Zpráva je zde zkrácená. Zaznamenává také konfiguraci a kontrolní součty každého souboru před změnou a po ní. Počáteční a koncová značka sekce se počítají jako dva výskyty. acme-quote odpovídá předponě acme, ale neoznačuje žádný známý blok, a proto je neznámá. acme-card uvnitř <pre><code> je příklad, nikoli značka, proto se uvede k ruční kontrole a nikdy se nepřepíše; totéž platí pro komentáře HTML a vložený kód.

Použití změn se odmítne, dokud zůstanou neznámé, nejednoznačné nebo dynamické značky:

Text
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.

Příkaz skončí s kódem 2. Opravte neznámou značku, v tomto případě jejím odstraněním, a spusťte příkaz s --apply místo --dry-run:

Text
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.

Změní se pouze názvy značek. Atributy zůstanou zachovány bajt po bajtu:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>

Opakované spuštění zkušebního režimu nad výsledkem oznámí 0 changed, 0 replacements. Předpony mohou zůstat zaregistrované i poté, takže nic nepřestane fungovat ve větvích, které stále používají krátkou podobu.

Další kroky