Šablonų komponavimas naudojant blokų žymas
Kai projekte atsiranda keletas blokų, šablonams pradeda reikėti vienas kito.
Funkcijų blokas nori pateikti tris korteles. Nukreipimo puslapiui reikia
sekcijos su mygtuku viduje. Galite kiekvienam iš jų kviesti bs_render_block(), tačiau
šabloną su daugybe PHP iškvietimų ir įdėtais masyvais sunku skaityti ir dar
sunkiau įdėti į kitą šabloną.
Blokų žymomis galite įrašyti bloką ten, kur turi būti jo išvestis, kaip HTML žymą:
<bs:acme-card title="Fast" text="Rendered on the server." />
Ta pati žyma reiškia du skirtingus dalykus, priklausomai nuo to, kur ji parašyta. Bloko šablone arba įrašo turinyje ji pakeičiama sugeneruota bloko HTML išvestimi. Puslapio, šablono ar svetainės šablono šaltinyje ji tampa tikru WordPress bloku, rodomu redaktoriuje. Šiame vadove sukursime kelis blokus, komponuosime juos abiem būdais, trumpesniems pavadinimams pridėsime projekto prefiksą ir parodysime, kaip šiuos trumpinius perkelti į perkeliamą formą.
Blokai
Pakanka trijų nedidelių blokų. Kortelė su dviem laukais:
{
"$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>
Sekcija, apgaubianti bet kokį į ją įdėtą turinį, su heading lauku, apibrėžtu taip pat kaip kortelės laukas:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
Ir mygtukas antroje vardų srityje – acme-ui/button – su laukais label ir href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Žymos bloko šablone
Blokų šablonai žymas atvaizduoja automatiškai. Jokių nustatymų nereikia. Funkcijų blokas gali tiesiogiai pateikti dvi korteles ir pagrindinį skirtuką:
<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>
Atvaizdavus acme/features gaunama:
<!--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>
Prieš kiekvieną išvesties Blockstudio bloką įterpiamas <!--blockstudio/namespace/slug--> komentaras. Puslapio buferis jį pašalina iš atsakymo; jei išvestis apeina buferį, naudokite bs_strip_render_markers().
Abi sintaksės yra lygiavertės. <bs:acme-card> užkoduoja bloko pavadinimą žymoje, o <block name="acme/card"> perduoda jį kaip atributą. Kiekvienas kitas atributas tampa lauko reikšme, todėl title kortelės šabloną pasiekia kaip $a['title']. Veikia ir pagrindiniai blokai: jie atvaizduojami naudojant WordPress bei integruotas blokų atvaizdavimo funkcijas.
Atidarančios ir uždarančios žymos bei vidinis turinys
Žyma su pradžios ir pabaigos žymekliais perduoda blokui savo vidinius elementus.
Bloko Blockstudio atveju jie užpildo <InnerBlocks />, o viduje esančios žymos atvaizduojamos pirmiausia:
<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>
Kaip žymos pavadinimas tampa bloko pavadinimu
Žymos <bs:> pavadinime nėra pasvirojo brūkšnio, todėl Blockstudio jo ieško.
Jis paeiliui, iš kairės į dešinę, kiekvieną brūkšnelį pakeičia pasviruoju brūkšniu
ir naudoja pirmą rastą registruotą variantą. <bs:acme-card> jau pirmuoju bandymu
atitinka acme/card. <bs:acme-ui-button> išbando acme/ui-button, nieko neranda ir tada
atitinka acme-ui/button. Taigi vardų sritims su brūkšneliais nereikia jokios
konfigūracijos, jei abu kandidatai neegzistuoja vienu metu.
Trumpesni pavadinimai su prefiksais
<bs:acme-ui-button> yra tikslus, bet ilgas pavadinimas. Projekto prefiksu trumpą žymos
prefiksą galima susieti su viena ar keliomis vardų sritimis. Sukonfigūruokite jį
blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Arba užregistruokite tą patį susiejimą iš PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Dabar <acme-card> atitinka acme/card, o <ui-button> – acme-ui/button.
Jei prefiksui priskirtos kelios vardų sritys, jos tikrinamos iš eilės ir
laimi pirmasis registruotas blokas. Taip projekto blokas gali perimti tos pačios
žymos bibliotekos bloko vietą.
Galima komponuoti ir prefiksus. <acme-ui-button> pirmiausia bando acme/ui-button.
Šio bloko nėra, o likusi žymos dalis ui-button pati yra registruota prefikso žyma,
todėl galiausiai randamas acme-ui/button. Tiesioginis atitikmuo visada turi pirmenybę prieš įdėtąjį.
<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>
Tai atvaizduoja lygiai tokį patį HTML kaip ir aukščiau pateikta kanoninė versija.
Prefiksams taikomos kelios taisyklės:
- Prefiksą sudaro mažosios raidės ir skaičiai, jis prasideda raide ir neturi brūkšnelių.
- Prefiksinė žyma, neatitinkanti jokio registruoto bloko, išvestyje paliekama
nepakeista, todėl
<acme-missing title="x" />lieka toks, koks buvo. - Tiksliosios slapyvardžių reikšmės iš
blockstudio/block_tags/tag_aliasesfiltro turi pirmenybę prieš prefiksus. Slapyvardis vieną žymą su brūkšneliu susieja su vienu bloku, pavyzdžiui,$aliases['acme-cta'] = 'acme-ui/button';leidžia atvaizduoti mygtuką kaip<acme-cta>.
Blokų šablonuose atvaizduojamos prefiksų ir slapyvardžių žymos, taip pat
Blockstudio 7.5 žymos <bs:> ir <block>.
Atributai
Atributai, atitinkantys lauko ID, tampa laukų reikšmėmis. Du prefiksai veikia kitaip:
data-*atributai nukopijuojami į atvaizduoto bloko šakninį elementą.html-*atributai nukopijuojami į šakninį elementą be prefikso, todėlhtml-id="intro"tampaid="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 nustato atributo reikšmę, o ne ją papildo: bloko savosios acme-card wp-block-acme-card
klasės pašalinamos. Jei iškvietimas turi pridėti bloko klasių, deklaruokite joms
lauką ir sujunkite reikšmes šablone.
Visi kiti atributai, kurie nėra deklaruoti laukai, pašalinami. Paprastas
class="wide" ant <bs:acme-card> atvaizduoja kortelę be šio atributo. Įjungus WP_DEBUG,
Blockstudio 7.7 apie tokius atributus praneša _doing_it_wrong() įspėjimu.
Tos pačios žymos puslapių šaltiniuose
Puslapiuose iš failų, šablonuose ir svetainės šablonuose žymos neatvaizduojamos. Išanalizavus šaltinį, jos paverčiamos blokais ir parodomos redaktoriuje. Štai puslapio šaltinis:
<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>
išanalizuojamas ir gaunama tokia blokų žymė (eilutės pridėtos, kad būtų lengviau skaityti):
<!-- 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 -->
Laukų reikšmės atsiduria po blockstudio.attributes, kur jas saugo Blockstudio blokai,
o pastraipa ir abu vidiniai blokai tampa sekcijos vidiniais blokais. Prefiksai ir
slapyvardžiai atpažįstami taip pat kaip šablonuose.
Žymos įrašų turinyje
Redaktoriuje įrašytas arba valdikliuose saugomas turinys pagal numatytuosius
nustatymus nenuskaitomas. Įjunkite puslapio lygmens atvaizdavimą blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Tada žymos the_content ir widget_text atvaizduojamos taikant prioritetą 5.
Tuo pačiu perjungikliu taip pat užregistruojamas filtras, atvaizduojantis žymas bet kurioje eilutėje:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Apribokite atvaizduojamas žymas naudodami allow ir deny šablonus,
kurie priima fnmatch() pakaitos simbolius ir taikomi visoms sintaksėms bei abiem atvaizdavimo režimams:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Nustačius šią taisyklę, <acme-ui-button> ir <bs:acme-ui-button> išvestyje paliekamos
neatvaizduotos. deny turi pirmenybę prieš allow. Filtrai blockstudio/block_tags/allow ir
blockstudio/block_tags/deny pakeičia tuos pačius sąrašus iš PHP.
Analizė tikrina kanoninę formą
Plėtinys PHPStan tikrina blokų žymas šablonuose PHP, Twig ir Blade. Neteisingai parašius lauką ar bloko pavadinimą, nurodomas blokas, į kurį jis buvo susietas:
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
7.6 versijoje tai taikoma žymoms <bs:> ir <block>. Prefiksinė žyma,
pavyzdžiui, <acme-card txt="...">, patikrinama nebuvo. Blockstudio 7.7 taisyklė išplečiama
prefiksinėms žymoms, puslapių šaltiniams ir susietiems HTML elementams; jos
užuominoje išvardijami visuotiniai atributai, kuriuos žyma gali perduoti.
Trumpinių perkėlimas į kanoninę formą
Prefiksų ir slapyvardžių žymos patogios konkrečiame projekte. Jos atpažįstamos
tik tada, kai įkeliami projekto filtrai ir nustatymai, todėl į kitą projektą,
blokų biblioteką ar programavimo agento kontekstą nukopijuotas šablonas praranda
savo prasmę. <bs:namespace-slug> nurodo tikrąjį bloko pavadinimą ir atpažįstamas visur,
todėl Blockstudio pavyzdžiuose, diagnostiniuose pranešimuose ir sugeneruotoje išvestyje
naudojama būtent ši forma.
Atskira komanda perrašo trumpinius į šią formą. Tarkime, projekte šaltiniuose vis dar naudojamos trumposios formos, taip pat slapyvardis, nebeegzistuojančio bloko žyma ir pavyzdys kodo fragmente:
<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>
Komanda neįkelia WordPress, todėl projekto konfigūraciją jai reikia pateikti kaip JSON failus, laikomus už skenuojamo medžio ribų:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Pirmiausia paleiskite bandomąjį vykdymą; jis taip pat naudojamas pagal numatytuosius nustatymus:
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.
Ataskaitoje pateikiamas kiekvienas susiejimas, kurį ji pritaikytų, ir kiekvienas atvejis, kurio ji nebandys nustatyti spėjimu:
{
"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" }
]
}
Ataskaita čia sutrumpinta. Joje taip pat įrašoma konfigūracija ir kiekvieno failo
maišos reikšmės prieš pakeitimus ir po jų. Sekcijos pradžios ir pabaigos žymos
skaičiuojamos kaip du atvejai. acme-quote atitinka prefiksą acme, bet nenurodo
žinomo bloko, todėl laikomas nežinomu. acme-card, esantis <pre><code>, yra pavyzdys,
o ne žymėjimas, todėl jis pažymimas kaip reikalaujantis peržiūros ir niekada
neperrašomas. Tas pats taikoma HTML komentarams ir įterptajam kodui.
Pakeitimai nepritaikomi, kol lieka nežinomų, dviprasmiškų ar dinaminių žymų:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Komanda baigiama kodu 2. Ištaisykite nežinomą žymą, šiuo atveju ją
pašalindami, ir paleiskite su --apply, o ne su --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Keičiasi tik žymų pavadinimai. Atributai išsaugomi baitas į baitą:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Dar kartą paleidus bandomąjį vykdymą pakeistam rezultatui, pateikiama
0 changed, 0 replacements. Prefiksai gali likti užregistruoti, todėl niekas nesugenda, kol kitose
šakose dar naudojama trumpoji forma.
Tolesni veiksmai
- Atvaizdavimas: visa žymų sintaksė, pasirinktiniai atvaizduotuvai ir analizatorius.
- Nustatymai: kiekviena
blockTagsparinktis. - Puslapių kūrimas iš failų: puslapių šaltiniai, kuriuose žymos tampa redaguojamais blokais.
- Blokų žymų perkėlimas: visos perkėlimo komandos parinktys.
- Patikrinti šablonai su PHPStan: žymų tikrinimo analizės paleidimas.