Templates samenstellen met blocktags
Zodra een project een handvol blocks heeft, beginnen templates elkaar nodig te hebben. Een features-block wil drie kaarten weergeven. Een landingspagina wil een sectie met een knop erin. Je kunt voor elk block bs_render_block() aanroepen, maar een template vol PHP-aanroepen met geneste arrays is lastig te lezen en nog lastiger te nesten.
Met blocktags schrijf je een block op de plek waar de uitvoer moet komen, als een HTML-tag:
<bs:acme-card title="Fast" text="Rendered on the server." />
Dezelfde tag betekent iets anders, afhankelijk van waar je die schrijft. In een blocktemplate of in berichtinhoud wordt die vervangen door de gerenderde HTML van het block. In een pagina, patroon of Site Template-bron wordt die een echt WordPress-block dat in de editor verschijnt. In deze handleiding maken we een paar blocks, stellen die op beide manieren samen, voegen een projectprefix toe voor kortere namen en laten vervolgens zien hoe je die verkorte schrijfwijzen terugzet naar de draagbare canonieke spelling.
De blocks
Drie kleine blocks volstaan. Een kaart met twee velden:
{
"$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>
Een sectie die alles omsluit wat erin wordt geplaatst, met een veld heading dat op dezelfde manier is gedefinieerd als dat van de kaart:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
En een knop in een tweede namespace, acme-ui/button, met de velden label en href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Tags in een blocktemplate
Blocktemplates renderen tags automatisch. Je hoeft niets in te stellen. Een features-block kan twee kaarten en een core-scheidingsteken rechtstreeks weergeven:
<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>
Het renderen van acme/features levert dit op:
<!--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>
Elk Blockstudio-blok in de uitvoer wordt voorafgegaan door een <!--blockstudio/namespace/slug-->-commentaar. De paginabuffer verwijdert dit uit de respons; gebruik voor uitvoer die de buffer overslaat bs_strip_render_markers().
De twee syntaxisvormen zijn equivalent. <bs:acme-card> codeert de bloknaam in de tag, en <block name="acme/card"> geeft deze door als attribuut. Elk ander attribuut wordt een veldwaarde, dus title komt als $a['title'] in de kaarttemplate terecht. Core-blokken werken ook; ze worden gerenderd via WordPress met de ingebouwde blokrenderers.
Gepaarde tags en inhoud binnenin
Een gepaarde tag geeft de onderliggende elementen door aan het block. Bij een Blockstudio-block vullen ze <InnerBlocks />, en geneste tags worden eerst gerenderd:
<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>
Hoe een tagnaam de blocknaam bepaalt
Een <bs:>-tagnaam bevat geen slash, dus Blockstudio zoekt er een. Het vervangt elke koppelteken door een slash, van links naar rechts, en gebruikt de eerste kandidaat die is geregistreerd. <bs:acme-card> wordt meteen omgezet naar acme/card. <bs:acme-ui-button> probeert acme/ui-button, vindt niets en wordt daarna omgezet naar acme-ui/button. Namespaces met koppeltekens werken dus zonder configuratie, zolang niet beide kandidaten bestaan.
Kortere namen met prefixen
<bs:acme-ui-button> is nauwkeurig, maar lang. Met een projectprefix koppel je een korte tagprefix aan een of meer namespaces. Configureer die in blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Je kunt dezelfde koppeling ook registreren vanuit PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Nu wordt <acme-card> omgezet naar acme/card en <ui-button> naar acme-ui/button. Als een prefix meerdere namespaces bevat, worden die op volgorde geprobeerd en wint het eerste geregistreerde block. Zo kan een projectblock een libraryblock met dezelfde slug overschrijven.
Prefixen kunnen ook worden gecombineerd. <acme-ui-button> probeert eerst acme/ui-button. Dat block bestaat niet, en de rest van de tag, ui-button, is zelf een geregistreerde prefixtag. Daarom wordt verder gezocht naar acme-ui/button. Een directe overeenkomst krijgt altijd voorrang op een geneste.
<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>
Dit rendert precies hetzelfde HTML als de canonieke versie hierboven.
Voor prefixen gelden enkele regels:
- Een prefix bestaat uit kleine letters en cijfers, begint met een letter en bevat geen koppeltekens.
- Een geprefixte tag die niet naar een geregistreerd block wordt omgezet, blijft ongewijzigd in de uitvoer staan.
<acme-missing title="x" />blijft dus zoals geschreven. - Exacte aliassen uit het filter
blockstudio/block_tags/tag_aliaseskrijgen voorrang op prefixen. Een alias koppelt één tag met koppeltekens aan één block. Zo zorgt$aliases['acme-cta'] = 'acme-ui/button';ervoor dat<acme-cta>de knop rendert.
Prefix- en aliastags worden in blocktemplates gerenderd naast <bs:>– en <block>-tags uit Blockstudio 7.5.
Attributen
Attributen die overeenkomen met een veld-ID worden veldwaarden. Twee prefixen doen iets anders:
- Attributen met
data-*worden gekopieerd naar het hoofdelement van het gerenderde block. - Attributen met
html-*worden naar het hoofdelement gekopieerd, waarbij de prefix wordt verwijderd. Zo wordthtml-id="intro"omgezet naarid="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 stelt het attribuut in; het voegt er niets aan toe. De eigen acme-card wp-block-acme-card-klassen van het block verdwijnen. Als een aanroeper klassen aan een block moet toevoegen, declareer dan een veld daarvoor en voeg het samen in de template.
Elk ander attribuut dat geen gedeclareerd veld is, wordt verwijderd. Een gewone class="wide" op <bs:acme-card> rendert de kaart zonder dat attribuut. Blockstudio 7.7 meldt zulke attributen met een _doing_it_wrong()-melding wanneer WP_DEBUG is ingeschakeld.
Dezelfde tags in paginabronnen
In pagina’s op basis van bestanden, patronen en Site Templates worden tags niet gerenderd. Ze worden omgezet naar blocks wanneer de bron wordt verwerkt, zodat ze in de editor verschijnen. Deze paginabron:
<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>
wordt verwerkt tot deze blockmark-up (met regeleinden voor de leesbaarheid):
<!-- 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 -->
Veldwaarden komen onder blockstudio.attributes terecht. Daar bewaren Blockstudio-blocks ze. De alinea en beide onderliggende blocks worden inner blocks van de sectie. Prefixen en aliassen worden hier op precies dezelfde manier omgezet als in templates.
Tags in berichtinhoud
Inhoud die in de editor is geschreven of in widgets is opgeslagen, wordt standaard niet doorzocht. Schakel renderen op paginaniveau in via blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Tags in the_content en widget_text worden daarna met prioriteit 5 gerenderd. Met dezelfde instelling wordt een filter geregistreerd voor het renderen van tags in elke tekenreeks:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Beperk welke tags mogen worden gerenderd met de patronen allow en deny. Deze accepteren jokertekens fnmatch() en gelden voor alle syntaxisvarianten en beide renderingsmodi:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Met deze regel blijven <acme-ui-button> en <bs:acme-ui-button> ongerenderd in de uitvoer staan. deny krijgt voorrang op allow. De filters blockstudio/block_tags/allow en blockstudio/block_tags/deny wijzigen dezelfde lijsten vanuit PHP.
Analyse controleert de canonieke spelling
De extensie PHPStan valideert blocktags in PHP-, Twig- en Blade-templates. Een verkeerd gespeld veld of block wordt gemeld met het block waarnaar de tag is omgezet:
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
In 7.6 geldt dit voor tags <bs:> en <block>. Een prefixtag zoals <acme-card txt="..."> wordt niet gecontroleerd. Blockstudio 7.7 breidt de regel uit naar prefixtags, paginabronnen en gekoppelde HTML-elementen; de hint vermeldt welke algemene attributen een tag mag doorgeven.
Verkorte schrijfwijzen omzetten naar de canonieke spelling
Prefix- en aliastags zijn handig voor een project. Ze worden alleen omgezet op plekken waar de filters en instellingen van het project zijn geladen. Een template die naar een ander project, een blockbibliotheek of de context van een programmeeragent wordt gekopieerd, verliest daardoor zijn betekenis. <bs:namespace-slug> legt de echte blocknaam vast en wordt overal herkend. Daarom gebruikt Blockstudio die spelling in zijn voorbeelden, diagnostische meldingen en gegenereerde uitvoer.
Met een losstaand commando zet je verkorte schrijfwijzen om naar die spelling. Neem een project waarvan de bronnen nog korte vormen gebruiken, waaronder een alias, een tag voor een block dat niet meer bestaat en een voorbeeld in een codefragment:
<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>
Het commando laadt WordPress niet. Daarom geef je de projectconfiguratie op als JSON-bestanden die buiten de doorzochte map staan:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Begin met een proefuitvoering; die is ook de standaard:
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.
Het rapport vermeldt elke koppeling die het zou toepassen en elk geval waarover het geen aanname doet:
{
"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" }
]
}
Het rapport is hier ingekort. Het bevat ook configuratie- en hashes van elk bestand voor en na de wijziging. De openings- en sluitingstag van de sectie tellen als twee voorkomens. acme-quote komt overeen met de prefix acme, maar verwijst niet naar een bekend block en is dus onbekend. De acme-card in <pre><code> is een voorbeeld, geen mark-up. Daarom wordt die gemeld voor handmatige controle en nooit herschreven. Hetzelfde geldt voor opmerkingen HTML en inline code.
Omzetten is niet toegestaan zolang er onbekende, ambigue of dynamische tags overblijven:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Het commando eindigt met 2. Los de onbekende tag op, bijvoorbeeld door die te verwijderen, en voer het commando opnieuw uit met --apply in plaats van --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Alleen tagnamen veranderen. Attributen blijven byte voor byte behouden:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Als je de proefuitvoering opnieuw uitvoert op het resultaat, meldt die 0 changed, 0 replacements. Je kunt de prefixen daarna geregistreerd laten, zodat er niets stukgaat terwijl andere branches de korte vorm nog gebruiken.
Volgende stappen
- Weergave: de volledige tagsyntaxis, aangepaste renderers en de parser.
- Instellingen: elke optie van
blockTags. - Pagina’s op basis van bestanden bouwen: paginabronnen waarin tags bewerkbare blocks worden.
- Blocktags omzetten: alle opties van het omzetcommando.
- Templates controleren met PHPStan: de analyse uitvoeren die tags valideert.