Sätt ihop mallar med blocktaggar
När ett projekt har några block börjar mallarna behöva varandra. Ett
funktionsblock vill skriva ut tre kort. En landningssida vill ha en sektion med
en knapp inuti. Du kan anropa bs_render_block() för varje block, men en
mall full av anrop till PHP med nästlade arrayer är svår att läsa och ännu
svårare att nästla.
Med blocktaggar kan du skriva ett block där dess utdata hör hemma, som en HTML-tagg:
<bs:acme-card title="Fast" text="Rendered on the server." />
Samma tagg betyder olika saker beroende på var den skrivs. I en blockmall eller i inläggsinnehåll ersätts den med blockets renderade HTML. På en sida, i ett mönster eller i källan till en webbplatsmall blir den ett riktigt WordPress-block som visas i redigeraren. Den här guiden skapar några block, sätter ihop dem på båda sätten, lägger till ett projektprefix för kortare namn och visar sedan hur kortformerna migreras tillbaka till den portabla stavningen.
Blocken
Det räcker med tre små block. Ett kort med två fält:
{
"$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>
En sektion som omsluter det som placeras inuti den, med ett heading-fält
deklarerat på samma sätt som kortets:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
Och en knapp i ett andra namnutrymme, acme-ui/button, med fälten label och href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Taggar i en blockmall
Blockmallar renderar taggar automatiskt. Ingen inställning behövs. Ett funktionsblock kan skriva ut två kort och en inbyggd avdelare direkt:
<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>
När acme/features renderas blir resultatet:
<!--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>
Varje Blockstudio-block i utdata föregås av en <!--blockstudio/namespace/slug-->-kommentar. Sidbufferten tar bort den från svaret; använd bs_strip_render_markers() för utdata som går förbi bufferten.
De två syntaxerna är likvärdiga. <bs:acme-card> kodar blocknamnet i taggen, och <block name="acme/card"> skickar det som ett attribut. Alla andra attribut blir fältvärden, så title når kortmallen som $a['title']. Kärnblock fungerar också och återges via WordPress med de inbyggda blockrenderarna.
Parade taggar och inre innehåll
En parad tagg skickar sina underordnade element till blocket. För ett block av typen
Blockstudio fyller de <InnerBlocks />, och nästlade taggar renderas först:
<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>
Så blir ett taggnamn ett blocknamn
Ett <bs:>-taggnamn saknar snedstreck, så Blockstudio letar efter ett. Det ersätter varje
bindestreck med ett snedstreck i tur och ordning, från vänster till höger, och använder den första kandidat
som är registrerad. <bs:acme-card> löses till acme/card vid första försöket.
<bs:acme-ui-button> provar acme/ui-button, hittar inget och löser sedan
acme-ui/button. Namnutrymmen som innehåller bindestreck fungerar därför utan
konfiguration, så länge inte båda kandidaterna finns.
Kortare namn med prefix
<bs:acme-ui-button> är exakt men långt. Ett projektprefix kopplar ett kort taggprefix
till ett eller flera namnutrymmen. Konfigurera det i blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Du kan också registrera samma mappning från PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Nu löses <acme-card> till acme/card och <ui-button> till
acme-ui/button. Om ett prefix listar flera namnutrymmen provas de i
ordning, och det första registrerade blocket används. På så sätt kan ett projektblock åsidosätta ett
biblioteksblock med samma slug.
Prefix kan också kombineras. <acme-ui-button> provar först acme/ui-button. Det
blocket finns inte, och den återstående delen av taggen, ui-button, är själv en
registrerad prefixtagg, så lösningen går vidare till acme-ui/button. En
direkt matchning väljs alltid före en nästlad.
<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>
Detta renderar exakt samma HTML som den kanoniska versionen ovan.
Några regler gäller för prefix:
- Ett prefix består av små bokstäver och siffror, börjar med en bokstav och innehåller inga bindestreck.
- En tagg med prefix som inte löser till något registrerat block lämnas orörd i utdata,
så
<acme-missing title="x" />förblir som den skrevs. - Exakta alias från filtret
blockstudio/block_tags/tag_aliaseshar företräde framför prefix. Ett alias kopplar en tagg med bindestreck till ett block. Till exempel gör$aliases['acme-cta'] = 'acme-ui/button';att<acme-cta>renderar knappen.
Prefix- och aliastaggar renderas i blockmallar tillsammans med taggarna <bs:> och <block>
från Blockstudio 7.5.
Attribut
Attribut som matchar ett fält-ID blir fältvärden. Två prefix gör något annat:
- Attribut med prefixet
data-*kopieras till rotelementet i det renderade blocket. - Attribut med prefixet
html-*kopieras till rotelementet med prefixet borttaget, såhtml-id="intro"blirid="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 anger attributet, det lägger inte till det: blockets egna
acme-card wp-block-acme-card-klasser försvinner. Om den som anropar ska lägga till klasser
i ett block, deklarerar du ett fält för dem och slår ihop värdena i mallen.
Alla andra attribut som inte är deklarerade fält tas bort. En vanlig
class="wide" på <bs:acme-card> renderar kortet utan attributet. Blockstudio 7.7
rapporterar sådana attribut med en notis från _doing_it_wrong() när WP_DEBUG är aktiverat.
Samma taggar i sidkällor
I sidor med filbaserat innehåll, mönster och webbplatsmallar renderas taggar inte. De omvandlas till block när källan tolkas, så att de visas i redigeraren. Den här sidkällan:
<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>
tolkas till den här blockmarkeringen (radbrytningar har lagts till för läsbarhet):
<!-- 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 -->
Fältvärden hamnar under blockstudio.attributes, där Blockstudio
block lagrar dem, och stycket samt båda inre blocken blir inre block
i sektionen. Prefix och alias löses här på samma sätt som i
mallar.
Taggar i inläggsinnehåll
Innehåll som skrivs i redigeraren eller lagras i widgetar skannas inte som standard.
Aktivera rendering på sidnivå i blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Därefter renderas taggar i the_content och widget_text med prioritet 5. Samma
inställning registrerar ett filter som renderar taggar i valfri sträng:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Begränsa vilka taggar som får renderas med mönstren allow och deny, som godtar
jokertecknet fnmatch() och gäller för alla syntaxer och båda renderingslägena:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Med den regeln på plats lämnas <acme-ui-button> och <bs:acme-ui-button> orenderade
i utdata. deny har företräde framför allow. Filtren
blockstudio/block_tags/allow och blockstudio/block_tags/deny ändrar samma listor från PHP.
Analysen kontrollerar den kanoniska stavningen
Tillägget PHPStan validerar blocktaggar i PHP, Twig och Blade-mallar. Ett felstavat fält- eller blocknamn rapporteras tillsammans med blocket som det löstes till:
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
I 7.6 omfattar detta taggarna <bs:> och <block>. En prefixtagg som
<acme-card txt="..."> kontrolleras inte. Blockstudio 7.7 utökar regeln till
prefixtaggar, sidkällor och mappade HTML-element, och dess tips listar de globala
attribut som en tagg får vidarebefordra.
Migrera kortformer till den kanoniska stavningen
Prefix- och aliastaggar är praktiska i ett projekt. De löses bara där
projektets filter och inställningar har lästs in, så en mall som kopieras till ett annat
projekt, ett blockbibliotek eller en kodagents kontext förlorar sin betydelse.
<bs:namespace-slug> anger det riktiga blocknamnet och fungerar överallt,
vilket är anledningen till att Blockstudios egna exempel, diagnostik och genererade utdata använder
det.
Ett fristående kommando skriver om kortformer till den stavningen. Anta ett projekt där källorna fortfarande använder kortformerna, inklusive ett alias, en tagg för ett block som inte längre finns och ett exempel i ett kodexempel:
<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>
Kommandot läser inte in WordPress, så det tar projektets konfiguration som JSON-filer som lagras utanför det genomsökta trädet:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Börja med en torrkörning, som också är standard:
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.
Rapporten listar varje mappning som skulle tillämpas och varje fall som den inte kan gissa sig till:
{
"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" }
]
}
Rapporten visas här i förkortad form. Den dokumenterar också konfigurationen och hashvärden före och efter för varje fil. Sektionens öppnings- och stängningstaggar räknas som två förekomster. acme-quote matchar prefixet acme men anger inget känt block,
så den är okänd. acme-card i <pre><code> är ett exempel, inte
markering, så den rapporteras för manuell granskning och skrivs aldrig om. Detsamma
gäller kommentarer med HTML och kod i löptext.
Ändringar kan inte tillämpas så länge okända, tvetydiga eller dynamiska taggar finns kvar:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Kommandot avslutas med 2. Åtgärda den okända taggen, till exempel genom att ta bort den, och kör
med --apply i stället för --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Endast taggnamnen ändras. Attributen bevaras byte för byte:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Om du kör torrkörningen igen på resultatet rapporteras
0 changed, 0 replacements. Prefixen kan fortsätta vara registrerade efteråt, så
inget går sönder medan andra grenar fortfarande använder kortformen.
Nästa steg
- Rendera: den fullständiga taggsyntaxen, anpassade renderare och parsern.
- Inställningar: alla alternativ för
blockTags. - Bygga filbaserade sidor: sidkällor där taggar blir redigerbara block.
- Migrering av blocktaggar: alla alternativ för migreringskommandot.
- Kontrollerade mallar med PHPStan: kör analysen som validerar taggar.