Zostavovanie šablón pomocou značiek blokov
Keď projekt obsahuje niekoľko blokov, šablóny začnú závisieť jedna od druhej. Blok
funkcií chce zobraziť tri karty. Úvodná stránka potrebuje sekciu s tlačidlom.
Každý blok môžete zavolať pomocou bs_render_block(), ale šablóna plná volaní PHP s vnorenými
poľami sa ťažko číta a ešte ťažšie sa do nej vkladajú ďalšie prvky.
Značky blokov umožňujú zapísať blok priamo tam, kde sa má zobraziť jeho výstup, ako značku HTML:
<bs:acme-card title="Fast" text="Rendered on the server." />
Tá istá značka znamená dve rôzne veci podľa toho, kde je zapísaná. V šablóne bloku alebo v obsahu príspevku sa nahradí vykresleným HTML bloku. V zdrojovom súbore stránky, vzoru alebo šablóny stránky sa z nej stane skutočný blok WordPress, ktorý sa zobrazí v editore. V tomto sprievodcovi vytvoríme niekoľko blokov, poskladáme ich oboma spôsobmi, pridáme predponu projektu pre kratšie názvy a ukážeme, ako tieto skrátené názvy previesť späť na prenosný zápis.
Bloky
Stačia tri jednoduché bloky. Karta s dvoma poľami:
{
"$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": "" }
]
}
}
<article useBlockProps class="acme-card">
<h3><?php echo esc_html( $a['title'] ); ?></h3>
<p><?php echo esc_html( $a['text'] ); ?></p>
</article>
Sekcia, ktorá obklopí ľubovoľný vložený obsah, s poľom heading
deklarovaným rovnako ako pole karty:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
A tlačidlo v druhom mennom priestore, acme-ui/button, s poľami label a href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Značky v šablóne bloku
Šablóny blokov vykresľujú značky automaticky. Netreba nič nastavovať. Blok funkcií môže priamo zobraziť dve karty a oddeľovač jadra:
<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:
<!--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 vo výstupe predchádza komentár <!--blockstudio/namespace/slug-->. Vyrovnávacia pamäť stránky ho odstráni z odpovede; pri výstupe, ktorý obchádza vyrovnávaciu pamäť, použite bs_strip_render_markers().
Obe syntaxe sú rovnocenné. <bs:acme-card> zakóduje názov bloku do značky a <block name="acme/card"> ho odovzdá ako atribút. Každý ďalší atribút sa stane hodnotou poľa, takže title sa dostane do šablóny karty ako $a['title']. Fungujú aj základné bloky, ktoré sa vykresľujú pomocou WordPress a vstavaných vykresľovačov blokov.
Párové značky a vnútorný obsah
Párová značka odovzdá bloku svoje vnorené prvky. V bloku Blockstudio
vyplnia <InnerBlocks /> a vnorené značky sa vykreslia ako prvé:
<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>
<!--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>
Ako sa názov značky zmení na názov bloku
Názov značky <bs:> neobsahuje lomku, preto Blockstudio nejakú nájde. Postupne
nahrádza spojovníky lomkami zľava doprava a použije prvého kandidáta, ktorý je zaregistrovaný.
<bs:acme-card> sa vyrieši hneď pri prvom pokuse na acme/card.
<bs:acme-ui-button> skúsi acme/ui-button, nič nenájde a potom sa vyrieši na acme-ui/button. Menné priestory so
spojovníkmi teda fungujú bez akejkoľvek konfigurácie, pokiaľ neexistujú obaja kandidáti.
Kratšie názvy pomocou predpôn
<bs:acme-ui-button> je presný, ale dlhý názov. Predpona projektu mapuje krátku predponu značky
na jeden alebo viac menných priestorov. Nakonfigurujte ju v blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Alebo zaregistrujte rovnakú mapu z PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Teraz sa <acme-card> vyrieši na acme/card a <ui-button> na acme-ui/button. Ak predpona uvádza
viac menných priestorov, skúšajú sa v poradí a vyhrá prvý zaregistrovaný blok. Projektový
blok tak môže prekryť blok knižnice s rovnakým názvom.
Predpony možno aj kombinovať. Najprv sa pri <acme-ui-button> skúsi acme/ui-button. Tento blok
neexistuje a zvyšok značky ui-button je sám zaregistrovanou značkou predpony, takže
riešenie pokračuje na acme-ui/button. Priame zhody majú vždy prednosť pred vnorenými.
<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>
Toto vykreslí presne rovnaké HTML ako vyššie uvedená kanonická verzia.
Pre predpony platí niekoľko pravidiel:
- Predpona obsahuje malé písmená a číslice, začína sa písmenom a neobsahuje spojovníky.
- Predpona značky, ktorá sa nevyrieši na žiadny zaregistrovaný blok, zostane vo výstupe
nezmenená. Napríklad
<acme-missing title="x" />zostane tak, ako je zapísaná. - Presné aliasy z filtra
blockstudio/block_tags/tag_aliasesmajú prednosť pred predponami. Alias mapuje jednu značku so spojovníkom na jeden blok; napríklad$aliases['acme-cta'] = 'acme-ui/button';spôsobí, že<acme-cta>vykreslí tlačidlo.
V šablónach blokov sa značky s predponami a aliasmi vykresľujú rovnako ako značky <bs:> a <block>
z Blockstudio 7.5.
Atribúty
Atribúty zodpovedajúce ID poľa sa stanú hodnotami poľa. Dve predpony majú inú funkciu:
- Atribúty
data-*sa skopírujú na koreňový prvok vykresleného bloku. - Atribúty
html-*sa skopírujú na koreňový prvok bez predpony, takžehtml-id="intro"sa zmení naid="intro".
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
<article data-track="card" id="intro" class="featured">
<h3>Hi</h3>
<p>There</p>
</article>
html-class nastaví atribút, nepridá hodnotu k jeho existujúcej hodnote: vlastné triedy acme-card wp-block-acme-card
bloku sa odstránia. Ak má volajúci pridať triedy k bloku, deklarujte pre ne pole a zlúčte
ho v šablóne.
Každý iný atribút, ktorý nie je deklarovaným poľom, sa zahodí. Obyčajné class="wide" na <bs:acme-card>
vykreslí kartu bez tohto atribútu. Blockstudio 7.7 takéto atribúty nahlási oznámením _doing_it_wrong(),
keď je zapnuté WP_DEBUG.
Tie isté značky v zdrojových súboroch stránok
V stránkach založených na súboroch, vzoroch a šablónach stránok sa značky nevykresľujú. Pri spracovaní zdrojového kódu sa konvertujú na bloky, takže sa zobrazia v editore. Zdrojový kód tejto stránky:
<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>
sa spracuje na toto označenie blokov (riadkové zlomy sú pridané pre lepšiu čitateľnosť):
<!-- 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í sa ukladajú pod blockstudio.attributes, kde ich uchovávajú bloky Blockstudio,
a odsek aj oba vnorené bloky sa stanú vnorenými blokmi sekcie. Predpony a aliasy sa tu
riešia rovnako ako v šablónach.
Značky v obsahu príspevkov
Obsah napísaný v editore alebo uložený vo widgetoch sa predvolene nekontroluje.
V blockstudio.json zapnite vykresľovanie na úrovni stránky:
{
"blockTags": {
"enabled": true
}
}
Značky v the_content a widget_text sa potom vykreslia s prioritou 5. Rovnaké
nastavenie zaregistruje aj filter na vykresľovanie značiek v ľubovoľnom reťazci:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Pomocou vzorov allow a deny obmedzte značky, ktoré sa môžu vykresliť. Podporujú
zástupné znaky fnmatch() a uplatňujú sa na všetky syntaxe aj oba režimy vykresľovania:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Po nastavení tohto pravidla zostanú <acme-ui-button> a <bs:acme-ui-button> vo výstupe nevykreslené.
deny má prednosť pred allow. Filtre blockstudio/block_tags/allow a blockstudio/block_tags/deny menia
rovnaké zoznamy z PHP.
Analýza kontroluje kanonický zápis
Rozšírenie PHPStan overuje značky blokov v šablónach PHP, Twig a Blade. Nesprávne napísané pole alebo názov bloku sa nahlási spolu s blokom, na ktorý sa názov vyriešil:
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
Vo verzii 7.6 sa kontrolujú značky <bs:> a <block>. Značka s predponou, napríklad
<acme-card txt="...">, sa nekontroluje. Blockstudio 7.7 rozširuje pravidlo aj na značky s predponami,
zdrojové súbory stránok a namapované prvky HTML. Jeho upozornenie uvádza globálne
atribúty, ktoré môže značka odovzdať.
Prevod skrátených zápisov na kanonický zápis
Značky s predponami a aliasmi sú praktické pre konkrétny projekt. Vyriešia sa iba tam,
kde sú načítané filtre a nastavenia projektu. Šablóna skopírovaná do iného projektu,
knižnice blokov alebo kontextu programovacieho agenta preto stráca svoj význam.
<bs:namespace-slug> uvádza skutočný názov bloku a funguje všade. Preto ho používajú aj vlastné
príklady, diagnostické hlásenia a generovaný výstup Blockstudio.
Samostatný príkaz prepíše skrátené zápisy na kanonický tvar. Predstavte si projekt, ktorého zdrojové súbory stále používajú skrátené tvary vrátane aliasu, značky pre blok, ktorý už neexistuje, a príkladu v ukážke kódu:
<div useBlockProps class="acme-features">
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</div>
<acme-section heading="Why Acme">
<acme-cta label="Talk to us" href="/contact" />
<acme-quote text="Missing block" />
</acme-section>
<pre><code><acme-card /> <acme-card title="Example" /></code></pre>
Príkaz nenačíta WordPress, preto prevezme konfiguráciu projektu ako súbory JSON uložené mimo prehľadávaného stromu:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Začnite skúšobným spustením; je to aj predvolený režim:
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
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.
Prehľad uvádza každé mapovanie, ktoré by sa použilo, aj všetky prípady, pri ktorých príkaz odmietne hádať:
{
"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" }
]
}
Prehľad je tu skrátený. Zaznamenáva aj konfiguráciu a kontrolné súčty pred a po
spracovaní pre každý súbor. Otváracia a uzatváracia značka sekcie sa počítajú ako dva
výskyty. acme-quote zodpovedá predpone acme, no neoznačuje žiadny známy blok,
preto je neznáma. Zápis acme-card v <pre><code> je príklad, nie označenie bloku,
preto sa nahlási na manuálnu kontrolu a nikdy sa neprepíše. To isté platí pre komentáre
HTML a vložený kód.
Zmeny sa odmietnu, kým zostávajú neznáme, nejednoznačné alebo dynamické značky:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Príkaz skončí s kódom 2. Opravte neznámu značku, v tomto prípade jej odstránením,
a spustite príkaz s --apply namiesto --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Menia sa iba názvy značiek. Atribúty sa zachovajú bajt po bajte:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Opakované skúšobné spustenie po vykonaní zmien nahlási 0 changed, 0 replacements. Potom môžete
ponechať zaregistrované predpony, takže projekty sa neporušia, kým iné vetvy stále
používajú skrátený tvar.
Ďalšie kroky
- Vykresľovanie: úplná syntax značiek, vlastné vykresľovače a analyzátor.
- Nastavenia: všetky možnosti
blockTags. - Tvorba stránok zo súborov: zdrojové súbory stránok, v ktorých sa značky menia na upraviteľné bloky.
- Migrácia značiek blokov: všetky možnosti migračného príkazu.
- Kontrolované šablóny s PHPStan: spustenie analýzy, ktorá overuje značky.