Renderización programática
Ahora que Gutenberg se ha convertido en la herramienta principal para crear sitios web fáciles de editar para los clientes, tiene sentido crear como bloques todas las áreas necesarias del sitio. Aunque este enfoque sirve para la mayoría, los usuarios avanzados y algunos casos de uso concretos quizá necesiten utilizar esos bloques existentes fuera del editor.
Blockstudio ofrece dos métodos para renderizar bloques mediante programación:
- Funciones PHP:
bs_render_blockybs_blockpara renderizar desde código PHP - Etiquetas HTML: etiquetas
<bs:block-name>que se sustituyen por el resultado del bloque en cualquier parte de la página
Se admiten todas las funciones específicas de Blockstudio, como los estilos integrados, los scripts y los estilos con alcance limitado.
Islas también funciona con estas rutas de renderización. Una isla dinámica renderizada con bs_render_block(), bs_block() o una etiqueta de bloque devuelve el mismo marcador de posición que un bloque renderizado desde el contenido de una entrada, y el entorno de ejecución del frontend se inyecta cuando ese marcador está presente en la respuesta.
Composiciones estructuradas y documentos completos
Para herramientas de larga duración, vistas previas, exportaciones y galerías de componentes, usa el Blockstudio\Render API con versiones. Acepta una declaración o una lista ordenada y renderiza sin imprimirla:
use Blockstudio\Render;
$composition = [
'root' => 'theme/card',
'example' => [
'data' => [
'heading' => 'Example card',
],
'layers' => [
[
'name' => 'theme/button',
'data' => [
'label' => 'Continue',
],
],
],
],
];
$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
'title' => 'Component preview',
'contentElement' => 'main',
'contentClasses' => ['component-preview'],
]);
La declaración normalizada canónica tiene cuatro claves:
[
'name' => 'theme/card',
'attributes' => [],
'content' => '',
'children' => [],
]
data, inner, innerBlocks, root, layers y example son opciones de entrada prácticas que se eliminan durante la normalización. Las declaraciones anidadas se renderizan de forma recursiva mediante la misma canalización de Blockstudio.
Render::document() devuelve schemaVersion, html, body, blocks, assets, warnings y errors. El valor assets separa head, footer, styles, scripts, modules, interactivity, ui y tailwind. La lista de bloques y los recursos incluyen las dependencias a las que hacen referencia las plantillas seleccionadas, pero excluyen los recursos no relacionados y los exclusivos del editor.
Los documentos completos pueden establecer bodyClasses/bodyAttributes y, de forma opcional, envolver el cuerpo renderizado con contentElement, contentClasses y contentAttributes. El contenedor se limita a un nombre de elemento seguro; body, que se devuelve, sigue siendo el contenido renderizado sin envolver. Las opciones head y footer añaden marcado de documento de confianza en sus posiciones correspondientes y se incluyen en el conjunto de recursos devuelto.
Para ensamblar un documento alrededor de HTML que ya está renderizado, proporciona los nombres conocidos de sus bloques raíz:
$document = Render::document_from_html(
$rendered_html,
['theme/hero', 'theme/button'],
['title' => 'Homepage preview']
);
Usa Render::content() para el contenido de bloque WordPress serializado. Los consumidores que rendericen varios documentos independientes en una solicitud deben llamar a Blockstudio\Batch_Render::reset() entre ellos; Canvas::documents() lo hace automáticamente.
Renderizado fuera de la página
Blockstudio coloca un comentario de <!--blockstudio/namespace/slug--> delante de cada bloque que renderiza. En una página de la interfaz pública, el búfer lee estos comentarios para detectar qué bloques están presentes, cargar sus recursos y eliminar los comentarios antes de enviar la respuesta.
El contenido que no pasa por ese búfer conserva los comentarios. Esto se aplica a las respuestas de REST, los feeds, los controladores AJAX y el contenido de HTML que guardes o envíes a otro lugar después de do_blocks(), Render::content() o bs_render_block(). Usa
bs_strip_render_markers() para eliminarlos:
$html = bs_strip_render_markers(do_blocks($post->post_content));
La función elimina los comentarios de los bloques Blockstudio registrados y deja intacto todo lo demás, incluidos otros comentarios de HTML. Busca los mismos marcadores que elimina el búfer de página. Llámala después de registrar los bloques (init o más tarde).
No elimines el marcado que aún se imprime en una página de la interfaz pública que pasa por el búfer. La página necesita los comentarios para saber qué recursos de bloque cargar, y Blockstudio los elimina al final.
Eliminar los comentarios no añade recursos. Los archivos CSS y JavaScript de bloques solo los inyecta el búfer de página. Usa bs_block_assets() o Render::document() cuando el consumidor también los necesite.
Inspeccionar bloques
Usa bs_block_fields() después de registrar los bloques (en init o más tarde) para obtener las definiciones de campos resueltas sin leer los registros internos:
$fields = bs_block_fields('theme/card');
if ($fields === null) {
// Unknown block, or not a Blockstudio block.
}
El valor devuelto es la matriz de definiciones de campos registrada, incluidos los filtros de atributos, los campos personalizados expandidos, las anulaciones y los grupos, pestañas y repetidores anidados. Un bloque Blockstudio sin campos devuelve []. El resultado es una copia: modificarla no cambia el bloque registrado.
Estas son definiciones, no valores guardados. Para validar el marcado guardado, use bs_validate_block() en lugar de mantener un recorrido de campos independiente. Para describir los valores que acepta un bloque, use bs_block_schema(). Los atributos gestionados por WordPress siguen siendo independientes.
Los campos añadidos mediante extensiones no forman parte de bs_block_fields(). Usa bs_block_extension_fields() para obtenerlos. Busca las extensiones por nombre de bloque, por lo que también funciona con bloques del núcleo y de terceros:
$fields = array_merge(
bs_block_fields('core/paragraph') ?? [],
bs_block_extension_fields('core/paragraph')
);
El valor devuelto enumera las definiciones de campos de cada extensión coincidente, en el orden en que se registraron, con la misma estructura que bs_block_fields(). Si ninguna extensión coincide con un bloque, devuelve []. Los valores de las extensiones se guardan en el mismo objeto attrs.blockstudio.attributes que los valores de campo propios del bloque, por lo que todos los identificadores comparten el mismo espacio de nombres. Si dos extensiones definen el mismo identificador, se devuelven ambas definiciones y editan el mismo valor; al renderizar, se aplica la definición de la extensión registrada más tarde.
Para leer los valores de un bloque guardado tal como los recibe su plantilla, usa bs_block_values().
Usa bs_block_assets() para inspeccionar el CSS y el JavaScript detectados del bloque. Para obtener un documento de vista previa completo, incluidos los bloques anidados y las dependencias compartidas del entorno de ejecución, usa Render::document(), como se describió anteriormente.
Validar valores almacenados
Usa bs_validate_block() después de registrar los bloques (init o más tarde) para comprobar los atributos de bloques generados mediante programación o importados antes de guardarlos:
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);
if ($findings === null) {
// No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
// No stored-value problems were found.
} else {
// Review the findings before saving.
}
Pasa la matriz completa de attrs, no solo blockstudio.attributes. Un renderizado de Blockstudio también acepta en el nivel superior los campos declarados, y los valores anidados prevalecen si se proporcionan ambos. Las extensiones de bloques del núcleo y de terceros solo leen blockstudio.attributes. Un bloque Blockstudio vacío está gestionado y devuelve [], no null.
La validación es explícita y de solo lectura. No renderiza plantillas, modifica valores, guarda entradas, consulta medios ni ejecuta funciones de población. No se ejecuta automáticamente al guardar, sincronizar páginas ni renderizar. No es un sanitizador, una comprobación de autorización ni una verificación de que exista un archivo adjunto.
Cada hallazgo contiene estas claves estables:
[
'code' => 'unknown_option',
'path' => 'steps/1/style',
'source' => 'block',
'message' => 'This value is not among the field options.',
'value' => 'c',
'expected' => ['a', 'b'],
]
Use code, no el traducido message, en las herramientas. source es block o
extension. Las rutas usan claves de almacenamiento e índices de fila de repetidor o de selección basados en cero, sin barra inicial. Los ~ y / literales de una clave se escapan como ~0 y
~1. Un grupo de nivel superior antepone su nombre a sus elementos (cta_title); los grupos anónimos y las pestañas no añaden ningún nivel. El constructor no admite grupos con un ID dentro de otro grupo o repetidor, por lo que sus claves no se aceptan. Los campos de mensaje no tienen un valor almacenado. Un campo de archivos permite su complemento <id>__size. En la raíz de un bloque Blockstudio, las claves de contabilidad y los atributos globales HTML que se reenvían al elemento renderizado no son campos desconocidos. Esto no permite claves arbitrarias en filas de repetidor ni extensiones de bloques del núcleo.
| Código | Significado | expected |
|---|---|---|
unknown_field |
Ningún campo conservado declara esta clave de almacenamiento. | Claves de almacenamiento conocidas. |
unknown_option |
La selección no está entre las opciones conocidas. | Valores de opción permitidos. |
wrong_type |
La estructura almacenada no es compatible con el campo. | Familia o tipo de almacenamiento esperado. |
too_few_rows, too_many_rows |
Un repetidor presente está fuera de sus límites de min o max. |
Límite de filas. |
definition_conflict |
Las definiciones aplicables a una clave requieren estructuras de almacenamiento distintas. | Origen y tipo de campo de cada definición. |
shadowed_value |
Un valor anidado sustituye a otro valor distinto de un campo de nivel superior. | El valor anidado que prevalece. |
extension_top_level |
La plantilla puede leer un valor de nivel superior, pero los enlaces de extensión no. | Su ruta requerida en blockstudio/attributes. |
unknown_attribute |
La ruta de renderizado no lee una clave de nivel superior de un bloque Blockstudio y la descarta. | Nombres de atributos registrados, campos de extensión y blockstudio. |
missing_container |
attributes, disabled, name o editor se almacena en el nivel superior y falta blockstudio. |
Su ruta requerida en blockstudio. |
invalid_container |
blockstudio o blockstudio.attributes no es un objeto. |
object. |
El mensaje de un hallazgo unknown_field indica la clave de almacenamiento más cercana del mismo nivel si está a tres ediciones o menos, conforme a la regla que usan los ajustes desconocidos: This storage key is not declared by the block or its extensions. Did you mean "title"?
expected sigue mostrando todas las claves conocidas.
La coincidencia no distingue mayúsculas de minúsculas y solo considera las claves de almacenamiento de ese contenedor. Los mensajes se traducen; las integraciones deben usar code, path y expected en lugar de analizar el texto del mensaje.
Una clave de nivel superior de un bloque Blockstudio que no sea un atributo registrado (sus campos y los atributos que WordPress añade para supports, lock y
metadata), un campo de una extensión coincidente, blockstudio, una clave de contabilidad ni un atributo reenviado HTML se descarta antes de ejecutar la plantilla. Una clave de este tipo, por ejemplo, un ID de campo mal escrito o un objeto de valores almacenado sin su contenedor blockstudio, genera un hallazgo porque el bloque se renderiza sin ese valor. Los bloques que solo contienen campos de extensión no se comprueban para detectar claves de nivel superior.
Las estructuras aceptadas se ajustan al renderizado: los selectores múltiples y las casillas de verificación pueden contener una lista, un objeto de opción o un escalar importado, incluido el cero numérico. Se aceptan cadenas numéricas para los números. Los archivos pueden contener IDs de adjuntos, objetos de ID, listas o referencias de cadena. Los valores de enlace e icono deben ser objetos; los tipos de campo personalizados usan el tipo de atributo registrado.
Un campo attributes contiene una lista de pares con un nombre attribute no vacío y un valor escalar value; se conservan los metadatos opcionales, como data.media.
WordPress valida los atributos de nivel superior registrados antes del renderizado, por lo que puede rechazar una estructura aceptada dentro de blockstudio.attributes. Por ejemplo, un valor de radio "a" funciona en el objeto anidado, pero se descarta en el nivel superior, donde su tipo registrado es object. Ese valor genera wrong_type. Use el objeto anidado para emplear la misma estructura de almacenamiento que escribe el editor.
Los campos ausentes no son obligatorios. Los valores anidados vacíos (null, false, '', []) y los campos desactivados no generan errores de valor. Un repetidor explícitamente vacío sigue comprobándose con min; un repetidor ausente o desactivado no. Se informa de un valor de nivel superior vacío si WordPress lo descarta y restaura en su lugar un valor predeterminado no vacío. El mismo valor en el objeto anidado puede borrarlo. Se informa de conflictos de definiciones incluso si la clave no tiene un valor guardado.
Las opciones estáticas y las opciones de población ya resueltas durante el registro se comprueban sin volver a invocar la población. Se omiten las opciones remotas de fetch y los argumentos de población que contienen {attributes.*}. Los valores de color y degradado pueden ser personalizados, salvo que se establezca disableCustomColors o disableCustomGradients.
Esto comprueba los valores almacenados, no default, fallback ni las reglas de validación del editor.
Los campos de extensión coincidentes se incluyen para cada bloque al que se aplican. Las definiciones posteriores prevalecen dentro del bloque o sus extensiones en la raíz, como ocurre al renderizar. El campo propio de un bloque y un campo de extensión siguen siendo definiciones separadas de la misma clave, y se aplican ambos. Dentro de las filas de repetidor, el renderizador lee el primer campo con un ID coincidente en cada origen, por lo que se aplican sus opciones y límites. Se conservan las definiciones duplicadas para diagnosticar conflictos: las estructuras de almacenamiento incompatibles generan definition_conflict, aunque una definición duplicada posterior no se lea al renderizar.
La función comprueba un bloque. Recorra innerBlocks al validar un documento; los patrones sincronizados y otras referencias no se expanden automáticamente. El comando wp bs blocks validate recorre los bloques de una o más entradas y muestra sus rutas de bloque.
Los sitios con un resolver personalizado en tiempo de renderizado pueden adaptar los hallazgos sin cambiar los datos almacenados:
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
if ($name !== 'my-theme/card') {
return $findings;
}
return array_values(array_filter($findings, function($finding) {
return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
}));
}, 10, 3);
Devuelva siempre una lista de hallazgos; devolver [] acepta el bloque. Este filtro solo se ejecuta para los bloques administrados, nunca para el resultado de null.
Descripción de los valores almacenados
Use bs_block_schema() después de registrar el bloque (init o posterior) para describir los valores que almacena un bloque; por ejemplo, para generar marcado de bloque en una herramienta o integración de IA, o para comprobar entradas en una ruta REST:
$schema = bs_block_schema('theme/card');
if ($schema === null) {
// No Blockstudio fields or matching extensions apply.
}
El resultado es un esquema JSON del objeto guardado en attrs.blockstudio.attributes. Incluye los campos del bloque y los de las extensiones coincidentes, junto con las claves de almacenamiento que usa la validación: un grupo de nivel superior antepone su prefijo a los campos secundarios, los grupos anónimos y las pestañas no añaden ningún nivel, y un campo de archivo añade su complemento <id>__size. Los repetidores son listas de objetos de fila con minItems y maxItems de min y max. additionalProperties es false en la raíz del almacenamiento de campos y en las filas de repetidores. Los campos cuyos valores son objetos, como los enlaces y los objetos personalizados, pueden incluir sus propios metadatos. Un bloque sin campos no tiene properties, por lo que solo coincide un objeto vacío.
Cada campo se describe en una forma canónica aceptada por bs_validate_block():
| Campo | Esquema |
|---|---|
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block |
Una cadena. |
number, range |
Un número, con minimum y maximum de min y max. |
toggle |
Un valor booleano. |
select, radio, checkbox |
Un valor de opción o una lista de valores de opción para checkbox y multiple, con enum. |
color, gradient |
Una cadena, con enum cuando se configura disableCustomColors o disableCustomGradients. |
token |
Una lista de cadenas. |
files |
Un ID de adjunto entero no negativo o una lista de ID con multiple. |
link |
Un objeto con url, title y opensInNewTab; se requiere url. |
icon |
Un objeto con set, subSet y icon; se requieren set y icon. |
attributes |
Una lista de objetos con un attribute no vacío y un value escalar. |
repeater |
Una lista de objetos de fila. |
| Tipos de campo personalizados | Su tipo de atributo registrado. |
enum enumera las opciones que comprueba la validación: opciones estáticas y opciones de población ya resueltas durante el registro. Las opciones remotas de fetch y los argumentos de población que contienen {attributes.*} no tienen enum. Se omite una clave cuyas definiciones tengan distintas formas de almacenamiento, porque la validación informa de todos los valores almacenados en ella. Cuando un campo del bloque y uno de una extensión comparten una clave, enum enumera los valores que aceptan ambos. Los repetidores compartidos combinan sus campos secundarios y aplican los límites de fila más estrictos de ambas definiciones. Dentro de las filas de repetidores, se aplica el primer campo con un ID coincidente de cada origen, como durante el renderizado. Un campo explícito llamado <id>__size tiene prioridad sobre un complemento de tamaño de archivo añadido automáticamente.
Cuando un campo cerrado no tiene opciones disponibles o dos conjuntos de opciones aplicables no se solapan, su valor canónico es null para una selección única o una lista vacía para varias selecciones. Una lista de opciones vacía no convierte el campo en uno sin restricciones. Las opciones remotas y las dependientes de atributos siguen siendo abiertas.
El label de un campo pasa a ser title, su help pasa a ser description y su default se conserva como anotación. El title propio del esquema es el título del bloque. Los campos nunca son obligatorios y la lógica condicional no forma parte del esquema.
Las restricciones solo usan palabras clave que comprueba rest_validate_value_from_schema(), por lo que el esquema sirve tal cual como esquema de entrada de una ruta REST o de una capacidad:
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
$result = rest_validate_value_from_schema($values, $schema);
}
El esquema describe un formulario por campo; la validación también acepta
estructuras importadas, como objetos de opciones, cadenas numéricas y objetos
con ID. No sustituye a bs_validate_block(): los conflictos de definición son problemas de configuración
y aún pueden generar hallazgos aunque se omita la clave en conflicto.
Los filtros de validación también pueden imponer reglas específicas del sitio. Usa
bs_validate_block() para comprobar el contenido almacenado. Los sitios con un
resolutor personalizado en tiempo de renderizado pueden adaptar el esquema con el
filtro blockstudio/blocks/attributes/schema.
Funciones de PHP
Sin datos
En su forma más sencilla, la función acepta un único valor que es el ID del bloque que debe renderizarse en la página.
bs_render_block('blockstudio/cta');
Con datos
Para renderizar el bloque con datos personalizados, se debe usar una matriz en lugar de un único valor como primer parámetro. El valor de la clave data se pasará a las variables $attributes y $a dentro de la plantilla del bloque.
bs_render_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
]);
Anidamiento
Los bloques se pueden anidar usando la función bs_block junto con la potente variable $content dentro de las plantillas de bloque.
<div>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => bs_block([
'id' => 'blockstudio/button',
'data' => [
'text' => 'Button Text',
]
])
]);
El bloque de botón se renderizará en lugar de la variable $content dentro de la plantilla del bloque.
Los bloques incrustados renderizados con bs_render_block() o bs_block() siempre generan HTML resuelto para el frontend, incluso cuando el bloque principal está renderizando una vista previa del editor. Los pseudocomponentes de plantilla, como <RichText /> y <InnerBlocks />, se resuelven antes de devolver el bloque incrustado.
Varias ranuras
También se pueden crear varias ranuras de contenido convirtiendo la variable $content en una matriz asociativa y llamando a las claves correspondientes en la función bs_block.
<div>
<?php echo $content['beforeContent']; ?>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content['afterContent']; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => [
'beforeContent' => bs_block([
'id' => 'blockstudio/badge',
'data' => ['text' => 'Before Content']
]),
'afterContent' => bs_block([
'id' => 'blockstudio/button',
'data' => ['text' => 'Button Text']
])
]
]);
Etiquetas de bloque
Incrusta cualquier bloque con la sintaxis de etiqueta HTML. Se admiten dos formatos:
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
Ambos renderizan el mismo bloque. La sintaxis <bs:> convierte un guion en el separador del espacio de nombres (acme-hero se convierte en acme/hero). Los guiones se prueban de izquierda a derecha y se elige el primer candidato registrado, por lo que también se resuelven los espacios de nombres que contienen guiones: <bs:acme-ui-button> prueba acme/ui-button y luego acme-ui/button. La sintaxis <block> acepta el nombre completo del bloque como atributo name.
Funcionan tanto los bloques Blockstudio como los bloques principales de WordPress. Los bloques Blockstudio se renderizan mediante el flujo completo (plantillas, Tailwind, recursos). Los bloques principales se renderizan mediante el sistema de renderizado de bloques de WordPress usando los renderizadores de bloques integrados.
Cómo funciona
Las etiquetas de bloque se comportan de manera distinta según dónde aparezcan:
En plantillas de bloque y contenido de entradas, las etiquetas se sustituyen en tiempo de ejecución por HTML renderizados. El resultado es el marcado final del bloque referenciado, incrustado directamente en la página. No hay ningún bloque WordPress en el editor para estos casos. Son únicamente un mecanismo de renderizado.
En páginas, patrones y plantillas del sitio, las etiquetas se convierten en bloques WordPress nativos antes de sincronizar el archivo de origen o registrarlo en WordPress. Esto significa que los bloques aparecen en el editor, se pueden editar cuando el destino lo permite y siguen el ciclo de vida completo de bloques de WordPress. La sintaxis de etiquetas es una forma abreviada de definir el contenido de bloques en archivos de plantilla.
Esta distinción es importante: las etiquetas de bloque en las plantillas generan resultados; las etiquetas de bloque en páginas, patrones y plantillas del sitio generan bloques nativos.
En plantillas de bloque
Las etiquetas de bloque se renderizan automáticamente dentro de las plantillas Twig y PHP. No hace falta configurar nada. Esto incluye las sintaxis <bs:> y <block>, así como cualquier etiqueta de prefijo o alias registrada, por lo que una plantilla puede emitirlas directamente en lugar de llamar a bs_render_block(). El resultado se renderiza HTML e incrusta directamente en la salida de la plantilla del bloque:
<div class="my-page">
<bs:mytheme-card title="Featured" />
<block name="core/separator" />
<bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
<block name="core/heading" level="2">Also WordPress</block>
<theme-card title="Prefix shorthand" />
</div>
En el contenido de entradas
El renderizado a nivel de página (contenido de entradas, áreas de widgets) es opcional:
{
"blockTags": {
"enabled": true
}
}
O mediante un filtro:
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
Sintaxis
Etiquetas autocerradas:
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
Etiquetas emparejadas con contenido interno:
<bs:mytheme-section layout="wide">
<p>Content inside the block.</p>
</bs:mytheme-section>
<block name="core/group">
<block name="core/paragraph">Inside a group.</block>
</block>
Puedes combinar ambas libremente. Las dos sintaxis se pueden anidar entre sí:
<bs:mytheme-section>
<block name="core/heading" level="2">Title</block>
<bs:mytheme-card title="Features" />
<block name="core/paragraph">Description text.</block>
</bs:mytheme-section>
Abreviaturas de prefijo
Las etiquetas de bloque también pueden usar abreviaturas de prefijo específicas del proyecto. Registra un prefijo con uno o más espacios de nombres y Blockstudio resolverá <prefix-slug> al primer bloque registrado según el orden de esos espacios de nombres:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components', 'bsui'];
return $prefixes;
});
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />
Con el ejemplo anterior, <theme-card> se resuelve como theme-components/card, <theme-button> recurre a bsui/button si theme-components/button no está registrado, y <theme-ui-feature-matrix> se resuelve como theme-components/ui-feature-matrix.
Los prefijos también se pueden combinar. Cuando una etiqueta con prefijo no se resuelve directamente y el slug restante es a su vez una etiqueta de prefijo registrada, la resolución continúa de forma recursiva, de modo que un prefijo de marca puede apoyarse en un prefijo de espacio de nombres:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components'];
$prefixes['ui'] = ['bsui'];
return $prefixes;
});
<theme-ui-input />
<theme-ui-input> no tiene ningún bloque theme-components/ui-input, así que pasa al prefijo ui y se resuelve como bsui/input. Las coincidencias directas siempre tienen prioridad frente a la resolución anidada, y las reglas de permitir y denegar se aplican al bloque resuelto final.
También puedes configurar prefijos en blockstudio.json:
{
"blockTags": {
"prefixes": {
"theme": ["theme-components", "bsui"]
}
}
}
Los prefijos deben contener solo letras minúsculas o números, empezar por una letra y no pueden incluir guiones. Los alias explícitos de blockstudio/block_tags/tag_aliases tienen prioridad sobre la resolución de prefijos. Las etiquetas con prefijo desconocido se dejan intactas.
Las etiquetas de prefijo y alias siguen siendo comodidades de autoría compatibles. La forma canónica y portable siempre es <bs:namespace-slug>, porque registra el nombre real del bloque sin depender de filtros del proyecto:
<bs:theme-components-card />
<bs:bsui-input />
Los ejemplos de Blockstudio, los diagnósticos generados y la salida programática usan esta forma canónica. Los proyectos que quieran retirar una sintaxis abreviada antigua pueden usar la migración independiente de etiquetas canónicas, que primero permite una ejecución de prueba, sin iniciar WordPress.
Bloques principales
Se puede usar cualquier bloque que tenga un renderizador registrado:
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
<bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>
O con la sintaxis <block>:
<block name="core/group">
<block name="core/columns">
<block name="core/column">
<block name="core/paragraph">Left column</block>
</block>
<block name="core/column">
<block name="core/paragraph">Right column</block>
</block>
</block>
</block>
Listas de permitidos y denegados
Controla qué bloques se pueden renderizar mediante etiquetas:
{
"blockTags": {
"enabled": true,
"allow": ["mytheme/*", "core/*"],
"deny": ["mytheme/internal-*"]
}
}
allow limita el resultado a los patrones coincidentes. deny excluye los patrones coincidentes y tiene prioridad. Ambos admiten comodines * mediante fnmatch(). Se aplican a las dos sintaxis y al renderizado tanto a nivel de plantilla como de página.
Filtros: blockstudio/block_tags/allow y blockstudio/block_tags/deny.
HTML passthrough
Los atributos con el prefijo data- se transfieren al elemento raíz del bloque renderizado. Los atributos con el prefijo html- también se transfieren, pero se elimina el prefijo. Funciona con ambas sintaxis. Un atributo transferido sustituye el valor existente del elemento raíz en lugar de combinarse con él, así que html-class reemplaza las clases propias del bloque.
Un bloque Blockstudio también coloca en su elemento raíz los atributos globales que no declara como campos: id, style, role, title, lang, dir, hidden, tabindex y todos los atributos aria-*. Un campo declarado siempre tiene prioridad, por lo que un bloque con un campo title recibe en su lugar el valor de $a['title']. Los estilos reenviados pasan por safecss_filter_attr(); el filtro WordPress se aplica a los atributos de estilo en el contenido de entradas, y se añaden al estilo que ya establece la plantilla.
Los valores de los atributos se HTML, por lo que las entidades se decodifican una vez al analizar una etiqueta: title="Tom & Jerry" llega a la plantilla como Tom & Jerry y se vuelve a escapar al mostrarse. Los valores entre comillas pueden contener >, como ocurre con las variantes Tailwind y los selectores de animación, tanto en etiquetas autocerradas como en etiquetas emparejadas.
Cualquier otro atributo que el bloque no declare, incluido class, nunca llega a HTML. Si WP_DEBUG está activado, Blockstudio informa una vez por solicitud de cada atributo de este tipo mediante _doing_it_wrong(). Declara un campo para el atributo o escríbelo como atributo data-, aria- o html-.
<bs:mytheme-card
title="My Card"
html-class="featured-card"
html-id="main-card"
data-analytics="card-click"
/>
<block name="core/paragraph" html-class="highlight" data-section="intro">
Highlighted paragraph.
</block>
Renderizadores personalizados
Registra renderizadores de bloques personalizados para tipos de bloque adicionales. Los renderizadores reciben una matriz de atributos y una cadena de contenido interno, y devuelven una matriz de bloque WordPress:
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
$builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
$html = '<div class="my-block">' . $inner_content . '</div>';
return [
'blockName' => 'myplugin/custom-block',
'attrs' => $attrs,
'innerBlocks' => [],
'innerHTML' => $html,
'innerContent' => [$html],
];
};
return $builders;
}, 10, 2);
Para los bloques contenedores que necesitan analizar el contenido interno y convertirlo en bloques secundarios, añade una segunda entrada dentro del mismo filtro:
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
$content = ['<div class="my-wrapper">'];
foreach ($inner_blocks as $block) {
$content[] = null;
}
$content[] = '</div>';
return [
'blockName' => 'myplugin/wrapper',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '<div class="my-wrapper"></div>',
'innerContent' => $content,
];
};
blockstudio/block_tags/builders se aplica tanto a las etiquetas de bloque como a los bloques personalizados seleccionados mediante blockstudio/parser/element_mapping. Este es el hook adecuado cuando un bloque de proyecto con elementos asignados necesita trasladar el texto interno a un campo Blockstudio o construir una matriz de bloque personalizada.
blockstudio/block_tags/renderers y blockstudio/parser/renderers reciben el mismo registro y la misma estructura de callback. Siguen disponibles por compatibilidad y para sobrescrituras finales a nivel del analizador. Los filtros se ejecutan en este orden:
blockstudio/block_tags/buildersblockstudio/block_tags/renderersblockstudio/parser/renderers
Un filtro posterior puede sustituir un renderizador registrado por uno anterior.
Uso programático
Aplica el renderizado de etiquetas a cualquier cadena de PHP:
$html = apply_filters('blockstudio/block_tags/render', $content);
Componentes
Las etiquetas de bloque combinan bien con los componentes. Los componentes son bloques que solo se renderizan mediante programación y nunca aparecen en el editor.
<bs:mytheme-card title="My Card" description="Card content." />
Analizador
Las etiquetas de bloque se procesan con un analizador de cadenas ligero que sustituye a DOMDocument. El analizador admite las sintaxis <bs:> y <block>, etiquetas anidadas con el mismo nombre mediante seguimiento de profundidad, valores de atributos entre comillas y bloques contenedores recursivos. Está diseñado específicamente para este caso de uso; las pruebas de rendimiento muestran que es más rápido que DOMDocument y que WordPress de WP_HTML_Tag_Processor, y evita problemas conocidos de DOMDocument, como la eliminación de prefijos de espacios de nombres y la conversión de atributos a minúsculas.
Para páginas, patrones y plantillas del sitio, el mismo analizador también procesa elementos HTML sin procesar (<p>, <div>, <h1>, etc.) y los asigna a sus bloques principales WordPress correspondientes.
Cuando una asignación de elementos vincula <p> a un bloque Blockstudio no principal registrado que declara un atributo richtext content, el contenido HTML interno se dirige automáticamente a ese atributo content, incluidas etiquetas en línea como code y img que están asignadas a nivel de bloque. Un párrafo cuyo único elemento secundario es una imagen se convierte en el bloque al que asigna <img>. Las etiquetas de bloque anidadas o los elementos HTML a nivel de bloque siguen recurriendo al análisis normal de bloques internos. <block name="core/shortcode"> conserva el texto de su shortcode como contenido del bloque.