Veidņu veidošana ar bloku tagiem
Kad projektā ir vairāki bloki, veidnēm jāspēj izmantot citai citu. Funkciju bloks vēlas parādīt trīs kartītes. Galvenajā lapā vajadzīga sadaļa ar pogu. Katram blokam var izsaukt bs_render_block(), taču veidni, kas pilna ar PHP izsaukumiem un ligzdotiem masīviem, ir grūti lasīt un vēl grūtāk ligzdot.
Bloku tagi ļauj ievietot bloku tieši tur, kur jāparādās tā izvadei, izmantojot HTML tagu:
<bs:acme-card title="Fast" text="Rendered on the server." />
Atkarībā no tā, kur tags ierakstīts, tas nozīmē divas dažādas lietas. Bloka veidnē vai ieraksta saturā tas tiek aizstāts ar attēloto bloka HTML. Lapas, šablona vai vietnes veidnes avotā tas kļūst par īstu WordPress bloku, kas parādās redaktorā. Šajā pamācībā izveidosim dažus blokus, saliksim tos abos veidos, pievienosim projekta prefiksu īsākiem nosaukumiem un parādīsim, kā pārveidot saīsinājumus atpakaļ pārnesamajā pierakstā.
Bloki
Pietiek ar trim nelieliem blokiem. Kartīte ar diviem laukiem:
{
"$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>
Sadaļa, kas ietver visu tajā ievietoto saturu, un tajā ir heading lauks, kas deklarēts tāpat kā kartītes lauks:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
Poga citā nosaukumvietā — acme-ui/button — ar laukiem label un href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Tagi bloka veidnē
Bloku veidnēs tagi tiek attēloti automātiski. Nekādi iestatījumi nav vajadzīgi. Funkciju blokā var tieši attēlot divas kartītes un pamata atdalītāju:
<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>
acme/features attēlo šādi:
<!--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>
Katram izvades Blockstudio blokam priekšā ir <!--blockstudio/namespace/slug--> komentārs. Lapas buferis to noņem no atbildes; izvadei, kas apiet buferi, izmantojiet bs_strip_render_markers().
Abas sintakses ir līdzvērtīgas. <bs:acme-card> iekodē bloka nosaukumu tagā, bet <block name="acme/card"> nodod to kā atribūtu. Katrs cits atribūts kļūst par lauka vērtību, tāpēc title kartītes veidnē nonāk kā $a['title']. Darbojas arī pamata bloki, kas tiek renderēti, izmantojot WordPress ar iebūvētajiem bloku renderētājiem.
Pāra tagi un iekšējais saturs
Pāra tags nodod bloka bērnelementus. Blokam Blockstudio tie aizpilda <InnerBlocks />, un iekšpusē ligzdotie tagi tiek attēloti vispirms:
<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>
Kā taga nosaukums kļūst par bloka nosaukumu
Taga <bs:> nosaukumā nav slīpsvītras, tāpēc Blockstudio to atrod. Tas pēc kārtas, no kreisās uz labo pusi, aizstāj katru defisi ar slīpsvītru un izmanto pirmo atrasto kandidātu, kas ir reģistrēts. <bs:acme-card> jau pirmajā mēģinājumā tiek atrisināts kā acme/card. <bs:acme-ui-button> izmēģina acme/ui-button, neko neatrod, un tad tiek atrisināts kā acme-ui/button. Tāpēc nosaukumvietas ar defisēm darbojas bez konfigurācijas, ja vien nav reģistrēti abi kandidāti.
Īsāki nosaukumi ar prefiksiem
<bs:acme-ui-button> ir precīzs, taču garš nosaukums. Projekta prefikss sasaista īsu taga prefiksu ar vienu vai vairākām nosaukumvietām. Konfigurējiet to failā blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Vai arī reģistrējiet to pašu kartējumu no PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Tagad <acme-card> tiek atrisināts kā acme/card, bet <ui-button> — kā acme-ui/button. Ja prefiksam ir norādītas vairākas nosaukumvietas, tās tiek izmēģinātas pēc kārtas un tiek izmantots pirmais reģistrētais bloks. Tādējādi projekta bloks var aizēnot bibliotēkas bloku ar tādu pašu slug.
Prefiksus var arī kombinēt. Vispirms <acme-ui-button> izmēģina acme/ui-button. Šāda bloka nav, bet taga atlikusī daļa ui-button pati ir reģistrēts prefiksa tags, tāpēc meklēšana nonāk pie acme-ui/button. Tiešā atbilstība vienmēr ir prioritāra pār ligzdoto.
<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>
Tas attēlo tieši to pašu HTML, ko iepriekš parādītā kanoniskā versija.
Uz prefiksiem attiecas daži noteikumi:
- Prefiksā drīkst būt mazie burti un cipari. Tam jāsākas ar burtu, un tajā nedrīkst būt defises.
- Ja prefiksa tags neatbilst nevienam reģistrētam blokam, izvades tags paliek nemainīts, tātad
<acme-missing title="x" />saglabājas, kā rakstīts. - Precīzie aizstājvārdi no filtra
blockstudio/block_tags/tag_aliasesir prioritāri pār prefiksiem. Aizstājvārds piesaista vienu tagu ar defisi vienam blokam. Piemēram,$aliases['acme-cta'] = 'acme-ui/button';panāk, ka<acme-cta>attēlo pogu.
Prefiksa un aizstājvārda tagi tiek attēloti bloku veidnēs kopā ar <bs:> un <block> tagiem no Blockstudio 7.5.
Atribūti
Atribūti, kas atbilst lauka ID, kļūst par lauku vērtībām. Divi prefiksi darbojas citādi:
data-*atribūti tiek kopēti uz attēlotā bloka saknes elementu.html-*atribūti tiek kopēti uz saknes elementu, noņemot prefiksu, tāpēchtml-id="intro"kļūst parid="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 iestata atribūtu, nevis papildina to. Bloka paša acme-card wp-block-acme-card klases tiek noņemtas. Ja izsaucējam jāpievieno bloka klases, deklarējiet tām lauku un apvienojiet vērtības veidnē.
Visi pārējie atribūti, kas nav deklarēti lauki, tiek atmesti. Parasts class="wide" uz <bs:acme-card> attēlo kartīti bez šī atribūta. Ja ir ieslēgts WP_DEBUG, Blockstudio 7.7 par šādiem atribūtiem izvada paziņojumu _doing_it_wrong().
Tie paši tagi lapu avotos
Failos balstītās lapās, šablonos un vietnes veidnēs tagi netiek attēloti. Avots tiek parsēts un tagi pārvērsti blokos, tāpēc tie parādās redaktorā. Šis lapas avots:
<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>
tiek parsēts šādi, veidojot šo bloka marķējumu (pārskatāmības labad pievienotas rindu atstarpes):
<!-- 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 -->
Lauku vērtības nonāk zem blockstudio.attributes — tur Blockstudio bloki tās glabā. Rindkopa un abi iekšējie bloki kļūst par sadaļas iekšējiem blokiem. Prefiksus un aizstājvārdus šeit atrod tieši tāpat kā veidnēs.
Tagi ierakstu saturā
Redaktorā rakstītais vai logrīkos glabātais saturs pēc noklusējuma netiek skenēts. Iespējojiet lapu līmeņa attēlošanu failā blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Pēc tam tagi the_content un widget_text tiek attēloti ar prioritāti 5. Tas pats slēdzis reģistrē filtru tagu attēlošanai jebkurā virknē:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Ierobežojiet attēlojamos tagus, izmantojot allow un deny paraugus. Tie pieņem fnmatch() aizstājējzīmes un darbojas ar visu sintaksi abos attēlošanas režīmos:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Pēc šī noteikuma ieviešanas <acme-ui-button> un <bs:acme-ui-button> izvade paliek neattēloti. deny ir prioritārs pār allow. Filtri blockstudio/block_tags/allow un blockstudio/block_tags/deny maina tos pašus sarakstus no PHP.
Analīze pārbauda kanonisko pierakstu
Paplašinājums PHPStan pārbauda bloku tagus veidnēs PHP, Twig un Blade. Ja laukā vai bloka nosaukumā ir drukas kļūda, tiek norādīts bloks, kas tika atrasts:
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
Versijā 7.6 tiek pārbaudīti tagi <bs:> un <block>. Prefiksa tags, piemēram, <acme-card txt="...">, pārbaudei netiek pakļauts. Blockstudio 7.7 pārbaudi attiecina arī uz prefiksu tagiem, lapu avotiem un kartētajiem HTML elementiem. Tā ieteikumā ir uzskaitīti globālie atribūti, ko tags var nodot tālāk.
Pārveidojiet saīsinājumus kanoniskajā pierakstā
Prefiksu un aizstājvārdu tagi ir ērti projekta ietvaros. Tie tiek atrisināti tikai tad, ja ir ielādēti projekta filtri un iestatījumi, tāpēc citā projektā izmantota veidne, bloku bibliotēka vai koda aģenta konteksts zaudē to nozīmi. <bs:namespace-slug> satur īsto bloka nosaukumu un darbojas jebkur, tāpēc Blockstudio piemēros, diagnostikas ziņojumos un ģenerētajā izvadē izmanto šo pierakstu.
Atsevišķa komanda pārveido saīsinājumus šajā pierakstā. Pieņemsim, ka projektā joprojām izmanto īsās formas, tostarp aizstājvārdu, vairs neesoša bloka tagu un piemēru koda paraugā:
<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 neielādē WordPress, tāpēc tā pieņem projekta konfigurāciju kā JSON failus, kas glabājas ārpus skenējamā koka:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Vispirms palaidiet sauso pārbaudi — tā tiek izmantota arī pēc noklusējuma:
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.
Pārskatā uzskaitīti visi piemērojamie kartējumi un katrs gadījums, ko komanda nemēģinās uzminēt:
{
"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" }
]
}
Šeit parādīts saīsināts pārskats. Tajā ir reģistrēta arī konfigurācija un katra faila jaucējvērtības pirms un pēc izmaiņām. Sadaļas atverošais un aizverošais tags tiek skaitīti kā divas parādīšanās reizes. acme-quote atbilst prefiksam acme, bet nenorāda zināmu bloku, tāpēc tas ir nezināms. acme-card iekš <pre><code> ir piemērs, nevis marķējums, tāpēc tas ir atzīmēts manuālai pārskatīšanai un nekad netiek pārrakstīts. Tas pats attiecas uz komentāriem HTML un iekļautu kodu.
Lietošana tiek liegta, kamēr paliek nezināmi, neskaidri vai dinamiski tagi:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Komanda beidzas ar 2. Izlabojiet nezināmo tagu, šajā gadījumā to noņemot, un palaidiet ar --apply, nevis --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Mainās tikai tagu nosaukumi. Atribūti tiek saglabāti baits baitā:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Atkārtoti palaižot sauso pārbaudi pār rezultātu, pārskatā tiek ziņots 0 changed, 0 replacements. Prefiksus pēc tam var atstāt reģistrētus, tāpēc nekas nedarbojas nepareizi, kamēr citos atzaros vēl tiek izmantota īsā forma.
Nākamās darbības
- Atveidošana: pilna tagu sintakse, pielāgoti attēlotāji un parsētājs.
- Iestatījumi: visas
blockTagsopcijas. - Lapu veidošana no failiem: lapu avoti, kuros tagi kļūst par rediģējamiem blokiem.
- Bloku tagu migrācija: visas migrācijas komandas opcijas.
- Veidņu pārbaude ar PHPStan: palaidiet analīzi, kas pārbauda tagus.