Sammensætning af templates med block-tags
Når et projekt har en håndfuld blocks, begynder templates at få brug for hinanden. En features-block vil vise tre kort. En landingsside vil have en sektion med en knap indeni. Du kan kalde bs_render_block() for hver af dem, men en template fyldt med PHP-kald med indlejrede arrays er svær at læse og endnu sværere at indlejre.
Block-tags lader dig skrive en block dér, hvor dens output skal være, som et HTML-tag:
<bs:acme-card title="Fast" text="Rendered on the server." />
Det samme tag betyder to forskellige ting, afhængigt af hvor det skrives. I en block-template eller i indlægsindhold erstattes det af block’ens renderede HTML. I en side-, mønster- eller Site Template-kilde bliver det til en rigtig WordPress-block, som vises i editoren. I denne vejledning opretter vi nogle blocks, sammensætter dem på begge måder, tilføjer et projektpræfiks for at få kortere navne og viser derefter, hvordan forkortelserne migreres tilbage til den portable stavemåde.
Blocksene
Tre små blocks er nok. Et kort med to felter:
{
"$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, der omslutter det, der placeres indeni, med et heading-felt, der er deklareret på samme måde som kortets:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
Og en knap i et andet namespace, acme-ui/button, med felterne label og href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Tags i en block-template
Block-templates renderer tags automatisk. Ingen indstilling er nødvendig. En features-block kan vise to kort og en core-separator direkte:
<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>
Rendering af acme/features giver:
<!--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>
Hver Blockstudio-blok i outputtet indledes med en <!--blockstudio/namespace/slug-->-kommentar. Sidebufferen fjerner den fra svaret; for output, der springer bufferen over, skal du bruge bs_strip_render_markers().
De to syntakser er ækvivalente. <bs:acme-card> indkoder bloknavnet i tagget, og <block name="acme/card"> angiver det som en attribut. Alle andre attributter bliver feltværdier, så title når kortskabelonen som $a['title']. Kerneblokke virker også og gengives via WordPress med de indbyggede blokrenderere.
Parrede tags og indhold indeni
Et parret tag sender sine underordnede elementer til block’en. For en Blockstudio-block udfylder de <InnerBlocks />, og indlejrede tags renderes 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ådan bliver et tag-navn til et block-navn
Et <bs:>-tag har intet skråstregstegn, så Blockstudio finder et. Den erstatter hver bindestreg med en skråstreg, én ad gangen fra venstre mod højre, og bruger den første kandidat, der er registreret. <bs:acme-card> løses til acme/card ved første forsøg. <bs:acme-ui-button> prøver acme/ui-button, finder ingen match og løses derefter til acme-ui/button. Namespaces med bindestreger fungerer derfor uden konfiguration, så længe begge kandidater ikke findes.
Kortere navne med præfikser
<bs:acme-ui-button> er præcist, men langt. Et projektpræfiks knytter et kort tagpræfiks til et eller flere namespaces. Konfigurér det i blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Eller registrér det samme map fra 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> til acme/card og <ui-button> til acme-ui/button. Når et præfiks angiver flere namespaces, afprøves de i rækkefølge, og den første registrerede block vinder. Det gør det muligt for en projekt-block at skygge for en library-block med samme slug.
Præfikser kan også kombineres. Først prøver <acme-ui-button> acme/ui-button. Den block findes ikke, og resten af tagget, ui-button, er selv et registreret præfikstag, så opløsningen fortsætter til acme-ui/button. Et direkte match vinder altid over et indlejret.
<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>
Dette renderer præcis samme HTML som den kanoniske version ovenfor.
Der gælder nogle regler for præfikser:
- Et præfiks består af små bogstaver og tal, begynder med et bogstav og indeholder ingen bindestreger.
- Et præfikstag, der ikke løses til en registreret block, forbliver uændret i outputtet, så
<acme-missing title="x" />står som skrevet. - Eksakte aliaser fra filteret
blockstudio/block_tags/tag_aliaseshar forrang frem for præfikser. Et alias knytter ét tag med bindestreg til én block. For eksempel får$aliases['acme-cta'] = 'acme-ui/button';<acme-cta>til at rendre knappen.
Præfiks- og aliastags renderes i block-templates sammen med <bs:>– og <block>-tags fra Blockstudio 7.5.
Attributter
Attributter, der matcher et felt-ID, bliver feltværdier. To præfikser gør noget andet:
- Attributter med præfikset
data-*kopieres til det renderede blocks rootelement. - Attributter med præfikset
html-*kopieres til rootelementet uden præfikset, såhtml-id="intro"bliver tilid="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 sætter attributten; den føjer ikke noget til den. Block’ens egne acme-card wp-block-acme-card-klasser forsvinder. Hvis en kaldende part skal kunne tilføje klasser til en block, skal du deklarere et felt til dem og flette dem ind i templaten.
Enhver anden attribut, der ikke er et deklareret felt, fjernes. Et almindeligt class="wide" på <bs:acme-card> renderer kortet uden attributten. Blockstudio 7.7 rapporterer sådanne attributter med en _doing_it_wrong()-meddelelse, når WP_DEBUG er slået til.
De samme tags i sidekilder
I filbaserede sider, mønstre og Site Templates renderes tags ikke. De konverteres til blocks, når kilden parses, så de vises i editoren. Denne sidekilde:
<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>
bliver parset til denne block-markup (linjeskift er tilføjet for læsbarhedens skyld):
<!-- 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 -->
Feltværdierne placeres under blockstudio.attributes, hvor Blockstudio-blocks gemmer dem, og afsnittet samt begge indre blocks bliver til indre blocks i sektionen. Præfikser og aliaser løses her på præcis samme måde som i templates.
Tags i indlægsindhold
Indhold skrevet i editoren eller gemt i widgets gennemgås ikke som standard. Aktivér rendering på sideniveau i blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Tags i the_content og widget_text renderes derefter med prioriteten 5. Samme indstilling registrerer et filter til rendering af tags i enhver streng:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Begræns, hvilke tags der må renderes, med mønstrene allow og deny. De accepterer jokertegn af typen fnmatch() og gælder for alle syntakser og begge renderingstilstande:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Med den regel på plads forbliver <acme-ui-button> og <bs:acme-ui-button> urenderede i outputtet. deny har forrang frem for allow. Filtrene blockstudio/block_tags/allow og blockstudio/block_tags/deny ændrer de samme lister fra PHP.
Analyse kontrollerer den kanoniske stavemåde
Udvidelsen PHPStan validerer block-tags i templates af typen PHP, Twig og Blade. Et forkert stavet felt- eller block-navn rapporteres sammen med den block, det blev løst til:
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 gælder dette for tags af typen <bs:> og <block>. Et præfikstag som <acme-card txt="..."> kontrolleres ikke. Blockstudio 7.7 udvider reglen til præfikstags, sidekilder og tilknyttede elementer af typen HTML. Vinket viser de globale attributter, et tag kan videresende.
Migrér forkortelser til den kanoniske stavemåde
Præfiks- og aliastags er en bekvemmelighed i projektet. De løses kun dér, hvor projektets filtre og indstillinger er indlæst. Derfor mister en template, der kopieres til et andet projekt, et block-bibliotek eller en kodningsagents kontekst, sin betydning. <bs:namespace-slug> angiver det rigtige block-navn og løses overalt. Derfor bruger Blockstudio det i egne eksempler, diagnosticering og genereret output.
En selvstændig kommando omskriver forkortelser til den stavemåde. Forestil dig et projekt, hvis kilder stadig bruger de korte former, herunder et alias, et tag til en block, der ikke længere findes, og et eksempel inde i et kodestykke:
<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>
Kommandoen indlæser ikke WordPress, så den tager projektets konfiguration som JSON-filer, der ligger uden for det scannede træ:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Start med en prøvekørsel, som også er 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 viser alle tilknytninger, den ville anvende, og alle tilfælde, den ikke vil gætte på:
{
"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 er forkortet her. Den registrerer også konfiguration samt hashes før og efter for hver fil. Sektionens start- og sluttags tæller som to forekomster. acme-quote matcher præfikset acme, men angiver ingen kendt block, så den er ukendt. acme-card inde i <pre><code> er et eksempel, ikke markup, så det markeres til manuel gennemgang og omskrives aldrig. Det samme gælder HTML-kommentarer og inline-kode.
Anvendelse afvises, så længe der er ukendte, tvetydige eller dynamiske tags:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Kommandoen afsluttes med 2. Ret det ukendte tag, her ved at fjerne det, og kør med --apply i stedet for --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Kun tagnavne ændres. Attributter bevares byte for byte:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Hvis du kører prøvekørslen igen på resultatet, rapporterer den 0 changed, 0 replacements. Præfikserne kan fortsat være registreret bagefter, så intet går i stykker, mens andre branches stadig bruger den korte form.
Næste trin
- Rendering: den fulde tagsyntaks, brugerdefinerede renderere og parseren.
- Indstillinger: alle valgmuligheder i
blockTags. - Oprettelse af filbaserede sider: sidekilder, hvor tags bliver til redigerbare blocks.
- Migrering af block-tags: alle valgmuligheder i migreringskommandoen.
- Kontrollerede templates med PHPStan: kør analysen, der validerer tags.