Hoppa till innehåll

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:

HTML
<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:

JSON
{
  "$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": "" }
    ]
  }
}
PHP
<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:

PHP
<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:

PHP
<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:

PHP
<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:

HTML
<!--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:

HTML
<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>
HTML
<!--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:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "blockTags": {
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    }
  }
}

Du kan också registrera samma mappning från PHP:

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.

HTML
<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_aliases har 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" blir id="intro".
HTML
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
HTML
<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:

HTML
<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):

HTML
<!-- 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:

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:

PHP
$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:

JSON
{
  "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:

Text
  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:

PHP
<div useBlockProps class="acme-features">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</div>
PHP
<acme-section heading="Why Acme">
  <acme-cta label="Talk to us" href="/contact" />
  <acme-quote text="Missing block" />
</acme-section>
<pre><code>&lt;acme-card /&gt; <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:

JSON
{ "acme": ["acme"], "ui": ["acme-ui"] }
JSON
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
JSON
{ "acme-cta": "acme-ui/button" }

Börja med en torrkörning, som också är standard:

Shell
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
Text
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:

JSON
{
  "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:

Text
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:

Text
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.

Endast taggnamnen ändras. Attributen bevaras byte för byte:

HTML
<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