Componer plantillas con etiquetas de bloque
Cuando un proyecto tiene varios bloques, las plantillas empiezan a necesitarse unas a otras. Un bloque de características quiere mostrar tres tarjetas. Una página de destino quiere una sección con un botón dentro. Puede llamar a bs_render_block() para cada bloque, pero una plantilla llena de llamadas PHP con matrices anidadas cuesta de leer y aún más de anidar.
Las etiquetas de bloque permiten escribir un bloque donde debe aparecer su salida, como una etiqueta HTML:
<bs:acme-card title="Fast" text="Rendered on the server." />
La misma etiqueta tiene dos significados según dónde se escriba. En la plantilla de un bloque o en el contenido de una entrada, se sustituye por el HTML renderizado del bloque. En una página, un patrón o el código fuente de una plantilla del sitio, se convierte en un bloque WordPress real que aparece en el editor. Esta guía crea varios bloques, los combina de ambas formas, añade un prefijo del proyecto para acortar los nombres y muestra cómo migrar esas formas abreviadas a la grafía portátil.
Los bloques
Bastan tres bloques pequeños. Una tarjeta con dos campos:
{
"$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 sección que envuelve lo que se coloque dentro, con un campo heading declarado igual que el de la tarjeta:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
Y un botón en un segundo espacio de nombres, acme-ui/button, con los campos label y href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Etiquetas dentro de una plantilla de bloque
Las plantillas de bloque renderizan las etiquetas automáticamente. No hace falta configurar nada. Un bloque de características puede mostrar dos tarjetas y un separador del núcleo directamente:
<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>
Al renderizar acme/features se obtiene:
<!--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>
Cada bloque Blockstudio de la salida va precedido de un comentario <!--blockstudio/namespace/slug-->. El búfer de página lo elimina de la respuesta; para una salida que omita el búfer, usa bs_strip_render_markers().
Las dos sintaxis son equivalentes. <bs:acme-card> codifica el nombre del bloque en la etiqueta y <block name="acme/card"> lo pasa como atributo. Cada uno de los demás atributos se convierte en un valor de campo, así que title llega a la plantilla de tarjeta como $a['title']. Los bloques del núcleo también funcionan y se renderizan mediante WordPress con los renderizadores de bloques integrados.
Etiquetas pareadas y contenido interno
Una etiqueta pareada pasa sus elementos secundarios al bloque. En un bloque Blockstudio, estos rellenan <InnerBlocks /> y las etiquetas anidadas se renderizan primero:
<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>
Cómo se convierte el nombre de una etiqueta en el nombre de un bloque
El nombre de una etiqueta <bs:> no lleva barra, así que Blockstudio busca una. Sustituye cada guion por una barra, de izquierda a derecha, y usa el primer candidato registrado. <bs:acme-card> se resuelve como acme/card a la primera. <bs:acme-ui-button> prueba acme/ui-button, no encuentra nada y después se resuelve como acme-ui/button. Los espacios de nombres que contienen guiones funcionan sin configuración, siempre que no existan ambos candidatos.
Nombres más cortos con prefijos
<bs:acme-ui-button> es preciso, pero largo. Un prefijo del proyecto asigna un prefijo de etiqueta corto a uno o más espacios de nombres. Configúrelo en blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
O registre el mismo mapa desde PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Ahora <acme-card> se resuelve como acme/card y <ui-button> como acme-ui/button. Si un prefijo enumera varios espacios de nombres, se prueban en orden y gana el primer bloque registrado; así, un bloque del proyecto puede prevalecer sobre un bloque de biblioteca con el mismo identificador.
Los prefijos también se pueden combinar. <acme-ui-button> prueba primero acme/ui-button. Ese bloque no existe y el resto de la etiqueta, ui-button, es a su vez una etiqueta de prefijo registrada, así que la resolución continúa hasta acme-ui/button. Una coincidencia directa siempre prevalece sobre la anidada.
<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>
Esto renderiza exactamente el mismo HTML que la versión canónica anterior.
Hay varias reglas para los prefijos:
- Un prefijo contiene letras minúsculas y números, empieza por una letra y no lleva guiones.
- Si una etiqueta con prefijo no se resuelve en ningún bloque registrado, se deja intacta en la salida; así,
<acme-missing title="x" />permanece como se escribió. - Los alias exactos del filtro
blockstudio/block_tags/tag_aliasestienen prioridad sobre los prefijos. Un alias asigna una etiqueta con guiones a un bloque; por ejemplo,$aliases['acme-cta'] = 'acme-ui/button';hace que<acme-cta>renderice el botón.
Las etiquetas con prefijo y alias se renderizan en las plantillas de bloque junto con las etiquetas <bs:> y <block> de Blockstudio 7.5.
Atributos
Los atributos que coinciden con un ID de campo se convierten en valores de campo. Hay dos prefijos que hacen otra cosa:
- Los atributos
data-*se copian en el elemento raíz del bloque renderizado. - Los atributos
html-*se copian en el elemento raíz sin el prefijo, de modo quehtml-id="intro"se convierte enid="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 establece el atributo, no añade contenido al valor existente: las clases acme-card wp-block-acme-card del propio bloque desaparecen. Si quien llama debe añadir clases a un bloque, declare un campo para ellas e incorpórelas en la plantilla.
Se descartan todos los demás atributos que no sean campos declarados. Un class="wide" sin más en <bs:acme-card> renderiza la tarjeta sin ese atributo. Blockstudio 7.7 muestra esos atributos con un aviso _doing_it_wrong() cuando está activado WP_DEBUG.
Las mismas etiquetas en el código fuente de las páginas
En las páginas basadas en archivos, los patrones y las plantillas del sitio, las etiquetas no se renderizan. Se convierten en bloques al analizar el código fuente, por lo que aparecen en el editor. Este código fuente de página:
<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>
se analiza y produce este marcado de bloques (se añaden saltos de línea para facilitar la lectura):
<!-- 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 -->
Los valores de los campos se guardan en blockstudio.attributes, donde Blockstudio almacena los de sus bloques; el párrafo y ambos bloques internos se convierten en bloques internos de la sección. Los prefijos y los alias se resuelven aquí igual que en las plantillas.
Etiquetas en el contenido de las entradas
De forma predeterminada, no se analizan el contenido escrito en el editor ni el almacenado en widgets. Active el renderizado a nivel de página en blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
A continuación, las etiquetas de the_content y widget_text se renderizan con prioridad 5. La misma opción registra un filtro para renderizar etiquetas en cualquier cadena:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Restrinja qué etiquetas se pueden renderizar mediante los patrones allow y deny, que admiten comodines fnmatch() y se aplican a todas las sintaxis y a ambos modos de renderizado:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Con esa regla, <acme-ui-button> y <bs:acme-ui-button> se dejan sin renderizar en la salida. deny tiene prioridad sobre allow. Los filtros blockstudio/block_tags/allow y blockstudio/block_tags/deny modifican las mismas listas desde PHP.
El análisis comprueba la grafía canónica
La extensión PHPStan valida las etiquetas de bloque en las plantillas PHP, Twig y Blade. Si un campo o nombre de bloque está mal escrito, el aviso indica el bloque al que se resolvió:
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
En la versión 7.6, esto cubre las etiquetas <bs:> y <block>. Las etiquetas con prefijo, como <acme-card txt="...">, no se comprueban. Blockstudio 7.7 amplía la regla a las etiquetas con prefijo, el código fuente de las páginas y los elementos HTML asignados; además, la sugerencia enumera los atributos globales que puede reenviar una etiqueta.
Migrar las formas abreviadas a la grafía canónica
Las etiquetas con prefijo y alias son una comodidad del proyecto. Solo se resuelven cuando se cargan los filtros y la configuración del proyecto; por eso, una plantilla copiada en otro proyecto, una biblioteca de bloques o el contexto de un agente de programación pierde su significado. <bs:namespace-slug> registra el nombre real del bloque y se resuelve en cualquier lugar, por lo que los ejemplos, diagnósticos y resultados generados de Blockstudio usan esa grafía.
Un comando independiente cambia las formas abreviadas a esa grafía. Supongamos un proyecto cuyas fuentes aún usan las formas cortas, incluido un alias, una etiqueta de un bloque que ya no existe y un ejemplo dentro de una muestra de código:
<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>
El comando no carga WordPress, así que toma la configuración del proyecto de archivos JSON guardados fuera del árbol analizado:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Empiece con una ejecución de prueba, que también es el modo predeterminado:
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.
El informe enumera cada correspondencia que aplicaría y cada caso que no puede resolver por sí solo:
{
"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" }
]
}
El informe aparece recortado aquí. También registra la configuración y los hashes de cada archivo, antes y después. Las etiquetas de apertura y cierre de una sección cuentan como dos apariciones. acme-quote coincide con el prefijo acme, pero no nombra ningún bloque conocido, por lo que es desconocida. acme-card dentro de <pre><code> es un ejemplo, no marcado; se marca para revisión manual y nunca se reescribe. Lo mismo se aplica a los comentarios HTML y al código en línea.
No se permite aplicar los cambios mientras queden etiquetas desconocidas, ambiguas o dinámicas:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
El comando termina con 2. Corrija la etiqueta desconocida, en este caso eliminándola, y vuelva a ejecutarlo con --apply en lugar de --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Solo cambian los nombres de las etiquetas. Los atributos se conservan byte por byte:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Si vuelve a ejecutar la prueba con el resultado, se informa 0 changed, 0 replacements. Después puede dejar registrados los prefijos para que nada deje de funcionar mientras otras ramas sigan usando las formas cortas.
Pasos siguientes
- Renderizado: toda la sintaxis de etiquetas, los renderizadores personalizados y el analizador.
- Configuración: todas las opciones de
blockTags. - Construir páginas basadas en archivos: fuentes de páginas en las que las etiquetas se convierten en bloques editables.
- Migración de etiquetas de bloque: todas las opciones del comando de migración.
- Plantillas comprobadas con PHPStan: ejecutar el análisis que valida las etiquetas.