Páginas y patrones
Blockstudio te permite definir páginas WordPress, patrones de bloques y plantillas del Editor del sitio como archivos en tu tema. Escribe plantillas similares a HTML y el analizador de Blockstudio las convierte en bloques nativos de WordPress.
- Páginas se sincronizan con la base de datos como entradas WordPress, lo que mantiene sincronizadas las plantillas de archivos y el contenido de las páginas.
- Patrones se registran en memoria mediante
register_block_pattern()y están disponibles en el insertador de bloques para que los usuarios los coloquen donde quieran. - Plantillas del sitio proporcionan fuentes de
wp_templateywp_template_partrespaldadas por archivos para el Editor del sitio de WordPress.
Las tres funciones comparten el mismo analizador HTML y la misma sintaxis de bloques.
Crear páginas basadas en archivos
Guía práctica sobre plantillas de páginas basadas en archivos, sincronización y bloqueo.
Estructura de carpetas
theme/
├── pages/
│ ├── about/
│ │ ├── page.json
│ │ └── index.php
│ └── contact/
│ ├── page.json
│ └── index.twig
├── patterns/
├── hero/
│ ├── pattern.json
│ └── index.php
└── cta/
├── pattern.json
└── index.blade.php
├── templates/
└── front-page/
├── template.json
└── index.php
└── parts/
└── header/
├── part.json
└── index.php
Cada subcarpeta contiene un archivo de configuración JSON (page.json, pattern.json, template.json o part.json) y un archivo de plantilla.
Motores de plantillas
Las plantillas pueden escribirse como marcado sin formato en index.php, o en Twig o Blade:
| Archivo | Motor | Requisito |
|---|---|---|
index.php |
Ninguno (se lee tal cual, el código PHP no se ejecuta) | Ninguno |
index.twig |
Twig | Timber |
index.blade.php |
Blade | illuminate/view |
Si existen varios archivos de plantilla, el orden de prioridad es: index.php > index.blade.php > index.twig.
Como las plantillas se compilan durante la inicialización (antes de que exista un contexto de solicitud), las plantillas Twig y Blade no tienen acceso a variables dinámicas. Son útiles para funciones integradas y filtros como {{ "text"|upper }} o {{ strtoupper("text") }}.
Correspondencia de HTML con bloques
Los elementos HTML estándar se convierten automáticamente en los bloques WordPress correspondientes.
Texto
| HTML | Bloque |
|---|---|
<p> |
core/paragraph |
<h1> – <h6> |
core/heading |
<ul> |
core/list (sin ordenar) |
<ol> |
core/list (ordenada) |
<li> |
core/list-item |
<blockquote> |
core/quote |
<code> |
core/code |
<pre> |
core/preformatted |
Las listas conservan su estructura. Un <ul> o <ol> dentro de un <li> se convierte en un bloque interno core/list de ese core/list-item, que es la estructura que guarda el editor, por lo que las listas pueden anidarse a cualquier profundidad. Un class en una lista o elemento se convierte en su className, que permite establecer un estilo de bloque como is-style-checks desde un archivo de página; <block name="core/list" className="..."> hace lo mismo.
Medios
| HTML | Bloque |
|---|---|
<img> |
core/image |
<figure> |
core/image (con leyenda) |
<audio> |
core/audio |
<video> |
core/video |
Diseño
| HTML | Bloque |
|---|---|
<div>, <section> |
core/group |
<main>, <header>, <footer>, <article>, <aside> |
core/group que conserva el elemento como su tagName |
<hr> |
core/separator |
<details> |
core/details |
<table> |
core/table |
Sintaxis de bloques
Para los bloques que no tienen un equivalente HTML directo, usa el elemento <block>:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
Bloques principales
<!-- Pullquote -->
<block name="core/pullquote">
<p>An important quote.</p>
</block>
<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>
<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
<h2>Cover Title</h2>
</block>
<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />
<!-- Spacer -->
<block name="core/spacer" height="50px" />
<!-- Gallery -->
<block name="core/gallery">
<img src="https://example.com/1.jpg" alt="Image 1" />
<img src="https://example.com/2.jpg" alt="Image 2" />
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<h3>Column 1</h3>
</block>
<block name="core/column">
<h3>Column 2</h3>
</block>
</block>
<!-- Buttons -->
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
</block>
<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Item 1</p>
<p>Item 2</p>
</block>
Bloques personalizados
La misma sintaxis funciona con cualquier bloque registrado:
<block name="blockstudio/section">
<h1>Welcome</h1>
</block>
<block name="acf/hero" title="Hero Title" background="dark">
<p>Inner content becomes InnerBlocks.</p>
</block>
Atributos
Los atributos HTML de los elementos <block> se pasan como atributos de bloque. Se admiten valores JSON:
<block name="core/heading" level="3">Custom Heading</block>
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked content.</p>
</block>
<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />
Los valores de los atributos se decodifican una vez, como los lee un navegador, por lo que data-animate="[&>span]:fade" y data-animate="[&>span]:fade" guardan el mismo valor.
En un elemento asignado a un bloque Blockstudio, todos los atributos se guardan con el bloque. Los campos declarados llegan a la plantilla; los atributos globales que el bloque no declara (id, style, role, title, lang, dir, hidden, tabindex, aria-* y data-*) se añaden al elemento raíz del bloque al renderizarse, igual que en las etiquetas de bloque. En las fuentes de páginas y patrones, un prefijo html- solo identifica uno de esos atributos globales, así que html-role="note" se reenvía como role, mientras que los controladores de eventos como html-onclick nunca se renderizan. Todo lo demás, incluido un class no declarado, permanece en el contenido de la entrada sin llegar a la página, y wp bs pages sync lo informa por cada página que analiza.
Renderizadores de bloques personalizados
El analizador HTML usa una arquitectura basada en registros. Añade un generador para un bloque personalizado con blockstudio/block_tags/builders:
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
$builders['acf/hero'] = function( array $attrs, string $inner_content ) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );
return array(
'blockName' => 'acf/hero',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '',
'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
);
};
return $builders;
}, 10, 2 );
Luego úsalo en cualquier plantilla:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
También puedes reemplazar la forma en que se renderizan los bloques principales:
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
$renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
$content = trim( $inner_content );
$attrs['align'] = $attrs['align'] ?? 'center';
return array(
'blockName' => 'core/paragraph',
'attrs' => $attrs,
'innerBlocks' => array(),
'innerHTML' => '<p class="has-text-align-center">' . $content . '</p>',
'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
);
};
return $renderers;
}, 10, 2 );
Las funciones de devolución de llamada del generador reciben los atributos analizados y el contenido interno sin procesar. Deben devolver una matriz de bloques WordPress. Consulta Renderizadores personalizados para ver el orden completo de los filtros y un ejemplo de contenedor.
Firma de la función generadora
/**
* @param array $attrs Parsed element or block-tag attributes.
* @param string $inner_content Raw inner content.
* @return array WordPress block array.
*/
function my_builder( array $attrs, string $inner_content ): array {}
Asignación de elementos
De forma predeterminada, los elementos HTML estándar, como <h1>, <p> y <img>, se asignan a bloques principales WordPress. Puedes cambiar esta asignación para dirigir cualquier elemento HTML a otro bloque mediante el filtro blockstudio/parser/element_mapping:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['h1'] = 'custom/heading';
$mapping['h2'] = 'custom/heading';
$mapping['p'] = 'custom/paragraph';
$mapping['img'] = 'custom/image';
return $mapping;
}, 10, 2 );
Con este filtro activo, cada <h1> de tus plantillas generará un bloque custom/heading en lugar de core/heading. Los atributos del elemento se pasan al bloque de destino. Si hay un renderizador registrado para el nombre del bloque de destino, se usará. De lo contrario, se crea una estructura de bloque genérica.
Esto resulta útil cuando tu tema o plugin proporciona tipos de bloque personalizados que deben reemplazar los predeterminados en todas las plantillas de páginas y patrones.
Para asignaciones sencillas de <p>, Blockstudio puede dirigir el contenido interno de HTML directamente al atributo de texto enriquecido content de un bloque Blockstudio no principal registrado. El bloque de destino debe declarar un atributo con id: "content" y type: "richtext".
El formato en línea (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) permanece en el valor dirigido, incluso cuando la misma etiqueta se asigna a un elemento, como ocurre de forma predeterminada con code y img. Si el único elemento hijo de un párrafo es una imagen, se convierte en el bloque al que <img> asigna, que es lo que Markdown genera para una imagen independiente. Las etiquetas de bloque anidadas y el contenido HTML a nivel de bloque siguen analizándose como bloques internos.
Los valores de asignación también pueden ser funciones si el bloque de destino depende de los atributos del elemento:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['div'] = function( array $attrs ) {
if ( isset( $attrs['width'] ) ) {
return 'theme/row';
}
if ( isset( $attrs['gap'] ) ) {
return 'theme/flow';
}
return 'theme/div';
};
return $mapping;
} );
Los bloques personalizados asignados desde elementos contenedores como <section> y <div> analizan recursivamente los elementos secundarios HTML anidados, por lo que los encabezados internos, las imágenes, las etiquetas de bloque y los párrafos se convierten en bloques secundarios nativos.
Ejemplo completo
Una plantilla de página completa que combina varios tipos de bloques:
<div>
<h1>Welcome to Our Site</h1>
<p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>
<block name="core/columns">
<block name="core/column">
<h3>Feature One</h3>
<p>First feature description.</p>
</block>
<block name="core/column">
<h3>Feature Two</h3>
<p>Second feature description.</p>
</block>
</block>
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Our Mission</h2>
<p>Building amazing things together.</p>
</block>
<details>
<summary>FAQ</summary>
<p>Answers to common questions.</p>
</details>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
<block name="core/button" url="/learn-more">Learn More</block>
</block>
</div>