Comporre template con i tag dei blocchi
Quando un progetto ha una manciata di blocchi, i template iniziano ad aver bisogno l’uno dell’altro. Un blocco delle funzionalità vuole mostrare tre schede. Una pagina di destinazione vuole una sezione con un pulsante al suo interno. Potete richiamare bs_render_block() per ognuno, ma un template pieno di chiamate PHP con array annidati è difficile da leggere e ancora più difficile da annidare.
I tag dei blocchi permettono di scrivere un blocco nel punto in cui deve apparire il suo output, come tag HTML:
<bs:acme-card title="Fast" text="Rendered on the server." />
Lo stesso tag ha due significati diversi a seconda di dove viene scritto. In un template di blocco o nel contenuto di un articolo, viene sostituito con l’HTML del blocco renderizzato. In una pagina, un pattern o una sorgente Site Template, diventa un vero blocco WordPress che appare nell’editor. Questa guida crea alcuni blocchi, li compone in entrambi i modi, aggiunge un prefisso di progetto per usare nomi più brevi e mostra come riconvertire le forme abbreviate nella grafia portabile.
I blocchi
Bastano tre piccoli blocchi. Una scheda con due campi:
{
"$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>
Una sezione che racchiude ciò che viene inserito al suo interno, con un campo heading
dichiarato come quello della scheda:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
E un pulsante in un secondo spazio dei nomi, acme-ui/button, con i campi label e href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Tag all’interno di un template di blocco
I template di blocco eseguono automaticamente il rendering dei tag. Non serve alcuna impostazione. Un blocco delle funzionalità può mostrare direttamente due schede e un separatore core:
<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>
Il rendering di acme/features produce:
<!--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>
Ogni blocco Blockstudio nell’output è preceduto da un commento <!--blockstudio/namespace/slug-->. Il buffer della pagina lo rimuove dalla risposta; per l’output che evita il buffer, usate bs_strip_render_markers().
Le due sintassi sono equivalenti. <bs:acme-card> codifica il nome del blocco nel tag, mentre <block name="acme/card"> lo passa come attributo. Ogni altro attributo diventa un valore di campo, quindi title raggiunge il template della scheda come $a['title']. Funzionano anche i blocchi core, renderizzati tramite WordPress con i renderer di blocchi integrati.
Tag accoppiati e contenuto interno
Un tag accoppiato passa i propri elementi figli al blocco. Per un blocco Blockstudio, questi riempiono <InnerBlocks /> e i tag annidati vengono prima renderizzati:
<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>
Come il nome di un tag diventa il nome di un blocco
Il nome del tag <bs:> non contiene una barra, quindi Blockstudio ne cerca una. Sostituisce ogni trattino con una barra, procedendo da sinistra a destra, e usa il primo candidato registrato. <bs:acme-card> si risolve al primo tentativo in acme/card.
<bs:acme-ui-button> prova acme/ui-button, non trova nulla e poi si risolve in acme-ui/button. Gli spazi dei nomi che contengono trattini funzionano quindi senza configurazione, purché i due candidati non esistano entrambi.
Nomi più brevi con i prefissi
<bs:acme-ui-button> è preciso ma lungo. Un prefisso di progetto associa un prefisso breve del tag a uno o più spazi dei nomi. Configuratelo in blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Oppure registrate la stessa mappa da PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Ora <acme-card> si risolve in acme/card e <ui-button> in acme-ui/button. Se un prefisso elenca più spazi dei nomi, vengono provati in ordine e prevale il primo blocco registrato: così un blocco del progetto può avere la precedenza su un blocco di libreria con lo stesso slug.
Anche i prefissi possono comporsi. <acme-ui-button> prova prima acme/ui-button. Quel blocco non esiste e il resto del tag, ui-button, è a sua volta un tag di prefisso registrato, quindi la risoluzione prosegue con acme-ui/button. Una corrispondenza diretta prevale sempre su una annidata.
<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>
Questo produce esattamente lo stesso HTML della versione canonica qui sopra.
Ai prefissi si applicano alcune regole:
- Un prefisso è composto da lettere minuscole e numeri, inizia con una lettera e non contiene trattini.
- Un tag con prefisso che non si risolve in un blocco registrato viene lasciato invariato nell’output, quindi
<acme-missing title="x" />resta come scritto. - Gli alias esatti del filtro
blockstudio/block_tags/tag_aliaseshanno la precedenza sui prefissi. Un alias associa un tag con trattini a un blocco; per esempio,$aliases['acme-cta'] = 'acme-ui/button';fa sì che<acme-cta>esegua il rendering del pulsante.
I tag con prefisso e gli alias vengono renderizzati nei template di blocco insieme ai tag <bs:> e <block> di Blockstudio 7.5.
Attributi
Gli attributi che corrispondono a un ID di campo diventano valori del campo. Due prefissi hanno un altro comportamento:
- Gli attributi
data-*vengono copiati sull’elemento radice del blocco renderizzato. - Gli attributi
html-*vengono copiati sull’elemento radice senza il prefisso, quindihtml-id="intro"diventaid="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 imposta l’attributo, non vi aggiunge contenuto: le classi acme-card wp-block-acme-card del blocco vengono rimosse. Se chi richiama il blocco deve aggiungere classi, dichiarate un campo apposito e unitelo al template.
Qualsiasi altro attributo che non sia un campo dichiarato viene scartato. Un semplice class="wide" su <bs:acme-card> esegue il rendering della scheda senza di esso. Blockstudio 7.7 segnala tali attributi con un avviso _doing_it_wrong() quando è attivo WP_DEBUG.
Gli stessi tag nelle sorgenti delle pagine
Nelle pagine basate su file, nei pattern e nei Site Template, i tag non vengono renderizzati. Vengono convertiti in blocchi durante l’analisi della sorgente, così appaiono nell’editor. Questa sorgente di pagina:
<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>
viene analizzata producendo questo markup di blocchi (con interruzioni di riga aggiunte per facilitarne la lettura):
<!-- 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 -->
I valori dei campi finiscono sotto blockstudio.attributes, dove Blockstudio conserva i propri valori, e il paragrafo e i due blocchi interni diventano blocchi interni della sezione. I prefissi e gli alias vengono risolti qui esattamente come nei template.
Tag nel contenuto degli articoli
Per impostazione predefinita, i contenuti scritti nell’editor o salvati nei widget non vengono analizzati. Abilitate il rendering a livello di pagina in blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
I tag in the_content e widget_text vengono quindi renderizzati con priorità 5. La stessa opzione registra un filtro per eseguire il rendering dei tag in qualsiasi stringa:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Limitate i tag di cui è consentito il rendering con i pattern allow e deny, che accettano i caratteri jolly fnmatch() e si applicano a ogni sintassi e a entrambe le modalità di rendering:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Con questa regola, <acme-ui-button> e <bs:acme-ui-button> restano nell’output senza essere renderizzati. deny ha la precedenza su allow. I filtri blockstudio/block_tags/allow e blockstudio/block_tags/deny modificano gli stessi elenchi da PHP.
L’analisi verifica la grafia canonica
L’estensione PHPStan convalida i tag dei blocchi nei template PHP, Twig e Blade. Un nome di campo o di blocco errato viene segnalato insieme al blocco a cui è stato risolto:
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
Nella versione 7.6 questo copre i tag <bs:> e <block>. Un tag con prefisso come <acme-card txt="..."> non viene verificato. Blockstudio 7.7 estende la regola ai tag con prefisso, alle sorgenti delle pagine e agli elementi HTML mappati; il suggerimento elenca gli attributi globali che un tag può inoltrare.
Convertire le forme abbreviate nella grafia canonica
I tag con prefisso e gli alias sono una comodità per il progetto. Vengono risolti solo dove sono caricati i filtri e le impostazioni del progetto, quindi un template copiato in un altro progetto, in una libreria di blocchi o nel contesto di un agente di programmazione perde il proprio significato. <bs:namespace-slug> registra il vero nome del blocco e viene risolto ovunque; per questo gli esempi, i messaggi diagnostici e l’output generato di Blockstudio usano questa grafia.
Un comando indipendente riscrive le forme abbreviate usando quella grafia. Supponiamo che le sorgenti di un progetto usino ancora le forme brevi, compresi un alias, un tag per un blocco che non esiste più e un esempio all’interno di un frammento di codice:
<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>
Il comando non carica WordPress, quindi prende la configurazione del progetto dai file JSON conservati al di fuori dell’albero analizzato:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Iniziate con un’esecuzione di prova, che è anche l’impostazione predefinita:
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.
Il rapporto elenca ogni mappatura che applicherebbe e ogni caso per cui non farà supposizioni:
{
"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" }
]
}
Qui il rapporto è abbreviato. Registra anche la configurazione e gli hash dei singoli file prima e dopo. I tag di apertura e chiusura della sezione contano come due occorrenze. acme-quote corrisponde al prefisso acme ma non indica alcun blocco noto, quindi è sconosciuto. acme-card all’interno di <pre><code> è un esempio, non markup: viene segnalato per la revisione manuale e non viene mai riscritto. Lo stesso vale per i commenti HTML e per il codice inline.
L’applicazione delle modifiche viene rifiutata se restano tag sconosciuti, ambigui o dinamici:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Il comando termina con 2. Correggete il tag sconosciuto, in questo caso rimuovendolo, ed eseguite il comando con --apply anziché con --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Cambiano solo i nomi dei tag. Gli attributi vengono conservati byte per byte:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Una nuova esecuzione di prova sul risultato segnala 0 changed, 0 replacements. Potete lasciare registrati i prefissi in seguito, così nulla si interrompe mentre altri branch usano ancora la forma breve.
Passaggi successivi
- Rendering: la sintassi completa dei tag, i renderer personalizzati e il parser.
- Impostazioni: tutte le opzioni
blockTags. - Creare pagine basate su file: sorgenti delle pagine in cui i tag diventano blocchi modificabili.
- Migrazione dei tag dei blocchi: tutte le opzioni del comando di migrazione.
- Template verificati con PHPStan: eseguire l’analisi che convalida i tag.