Plantillas y partes del Editor del sitio desde archivos
Un tema de bloques describe su diseño en templates/*.html y parts/*.html:
archivos llenos de comentarios de bloques serializados como
<!-- wp:template-part {"slug":"header"} /-->. A nadie le gusta escribirlos a
mano, así que normalmente se crean en el Editor del sitio y se exportan. Esto funciona
hasta que dos personas editan la misma plantilla o alguien que revisa tiene que leer un diff de
JSON escapado en comentarios de HTML.
Blockstudio permite escribir las mismas plantillas como se escriben las
páginas basadas en archivos: una carpeta con un pequeño manifiesto JSON y un archivo de origen con marcado similar a HTML, que usa elementos sencillos, etiquetas <block> y sus propios bloques Blockstudio.
Blockstudio compila el origen en marcado de bloques nativo y se lo entrega a WordPress
como archivo del tema. El Editor del sitio sigue funcionando igual que antes: los usuarios pueden
personalizar una plantilla y, al restablecerla, se recupera la versión del archivo.
Esta guía crea una parte de encabezado y otra de pie de página, plantillas para la portada y entradas individuales, y una plantilla personalizada que los editores pueden elegir para las páginas; después muestra cómo WordPress las resuelve.
Estructura de carpetas
Las plantillas van en templates/ y las partes de plantilla, en parts/. Cada una es una carpeta
con un manifiesto y un archivo de origen:
theme/
├── templates/
│ ├── front-page/
│ │ ├── template.json
│ │ └── index.php
│ ├── single/
│ │ ├── template.json
│ │ └── index.php
│ └── page-landing/
│ ├── template.json
│ └── index.php
└── parts/
├── header/
│ ├── part.json
│ └── index.php
└── footer/
├── part.json
└── index.html
Son las mismas carpetas templates/ y parts/ que WordPress lee para un tema
de bloques. Blockstudio examina primero el tema activo y después el tema principal.
Las carpetas con un archivo template.json o part.json son fuentes de Blockstudio; los archivos
.html sencillos que estén junto a ellas siguen siendo plantillas WordPress nativas.
El archivo de origen puede ser index.php, index.blade.php, index.twig o
index.html, en ese orden de prioridad. Twig requiere Timber y Blade necesita su paquete de renderizado, como se explica en
Template Engines.
Paso 1: La parte del encabezado
Cada parte necesita un part.json. area indica al Editor del sitio dónde
va la parte:
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
El origen usa la misma sintaxis que las páginas y los patrones de Blockstudio. Un <div>
se convierte en un bloque de grupo, los atributos se convierten en atributos de bloque y los elementos <block>
producen cualquier bloque registrado:
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
Blockstudio lo compila en este marcado de bloques:
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} --><div class="wp-block-group is-layout-flex"><!-- wp:site-title /--><!-- wp:navigation {"overlayMenu":"mobile"} /--></div><!-- /wp:group -->
Eso es lo que, de otro modo, habría escrito a mano. Sus propios bloques funcionan igual: <block name="acme/announcement" />, una etiqueta <bs:acme-announcement />
o un prefijo de etiqueta configurado se compilan en el comentario de bloque correspondiente.
Paso 2: La parte del pie de página
Una parte puede constar de un solo párrafo. Esta usa index.html para dejar claro
que el origen es marcado, no un programa:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
Se compila en <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.
Paso 3: Plantillas para la portada y entradas individuales
Las plantillas usan template.json. slug debe ser un nombre WordPress exacto de la jerarquía de plantillas,
como front-page, single, page, archive, 404 o
single-product. Blockstudio nunca lo precede.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
La plantilla para entradas individuales sigue la misma estructura, con bloques de entrada:
{
"slug": "single",
"title": "Single Post"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-title" level="1" />
<block name="core/post-date" />
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
La plantilla individual compilada:
<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-title {"level":1} /--><!-- wp:post-date /--><!-- wp:post-content /--></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
<main> se convirtió en un bloque de grupo con tagName: "main", y los bloques de partes de plantilla
hacen referencia por slug a las partes de los pasos 1 y 2. Cuando WordPress procesa
la plantilla, esas referencias se resuelven como partes basadas en archivos; por eso, la salida de la portada empieza con
<header class="wp-block-template-part">, que contiene el título y la navegación del sitio,
y termina con <footer class="wp-block-template-part">, que contiene el párrafo del pie de página.
Paso 4: Una plantilla personalizada para páginas
Las plantillas cuyo slug no forma parte de la jerarquía son plantillas personalizadas. Indique
los tipos de contenido a los que se aplican con postTypes para que los editores puedan elegirlas en
el selector de plantillas:
{
"slug": "page-landing",
"title": "Landing Page",
"description": "Full-width page without a header",
"postTypes": ["page"]
}
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
get_block_templates( array( 'post_type' => 'page' ), 'wp_template' ) ahora
incluye page-landing y el objeto de plantilla contiene
post_types: ["page"].
Los orígenes se compilan una sola vez
El origen se lee y se compila una vez como marcado de bloques, no en cada solicitud. No tiene una entrada actual ni el contexto de la solicitud. index.php se lee como marcado: el código PHP que contiene no se ejecuta, por lo que <?php echo get_bloginfo( 'name' ); ?> no compila nada. Todo lo que dependa de la solicitud debe estar en un bloque que se renderice en tiempo de ejecución: core/site-title en lugar de un nombre de sitio mostrado, core/post-title en lugar de the_title() o un bloque Blockstudio propio y dinámico.
Los resultados compilados se almacenan en caché junto con metadatos de vigilancia de archivos. Al editar un manifiesto o un archivo de origen, se invalida el contenido almacenado de ese elemento, de modo que la siguiente solicitud ve el cambio sin necesidad de una compilación aparte.
Cómo WordPress encuentra los archivos
Blockstudio se integra en las mismas búsquedas que WordPress usa para las plantillas del tema. En
get_block_templates(), las plantillas basadas en archivos aparecen con
source: "theme" y origin: "theme", igual que los archivos nativos del tema; además,
get_block_template( 'acme//header', 'wp_template_part' ) devuelve la parte del encabezado
con su area.
El orden de búsqueda es:
- Una personalización del Editor del sitio almacenada en la base de datos.
- Un archivo
.htmlnativo del tema activo. - El origen basado en archivos Blockstudio.
- Alternativas del tema principal o de los plugins.
Ese orden mantiene intacto el flujo de trabajo del Editor del sitio. Cuando un usuario edita el pie de página y guarda los cambios, WordPress almacena una entrada wp_template_part y get_block_template() devuelve esa personalización con source: "custom".
Los cambios posteriores en parts/footer/index.html no se muestran mientras exista la personalización. Cuando el usuario restablece la parte o se elimina la entrada, la búsqueda recurre al archivo y devuelve de nuevo el origen compilado más reciente.
Blockstudio no escribe en los archivos los cambios realizados en el Editor del sitio. Si un cambio del usuario debe convertirse en el nuevo valor predeterminado, cópielo en el archivo de origen y restablezca la personalización.
index.html anidados y slugs
WordPress detecta recursivamente archivos .html en templates/ y parts/. Por eso,
una carpeta con manifiesto que use index.html, como parts/footer/index.html, también aparecería
como una parte nativa con el slug derivado de la ruta footer/index. Como Blockstudio 7.6.6, una parte index.html definida por un manifiesto
solo se muestra con el slug declarado, así que el Editor del sitio muestra un solo pie de página, no dos. Los archivos .html anidados sin manifiesto se dejan intactos.
Comprobar plantillas desde PHP
La clase Blockstudio\Site_Templates lee y compila los orígenes, lo que resulta útil en pruebas y comprobaciones de despliegue:
$templates = Blockstudio\Site_Templates::templates();
$header = Blockstudio\Site_Templates::get_part( 'header' );
echo $header['area']; // header
echo $header['content']; // compiled block markup
$errors = Blockstudio\Site_Templates::errors();
Cada elemento incluye slug, title, description, type (wp_template o
wp_template_part), status, source_type, postTypes para plantillas o
area para partes, meta y el content compilado. Pase una lista para compilar
solo los elementos seleccionados y consulte los problemas de esa selección con
selection_errors():
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
Añadir otras carpetas
Para mantener separados los orígenes Blockstudio de las plantillas nativas o distribuirlos desde un plugin, añada raíces de detección con filtros:
add_filter( 'blockstudio/site_templates/template_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-templates';
return $paths;
} );
add_filter( 'blockstudio/site_templates/part_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-parts';
return $paths;
} );
Los filtros blockstudio/site_templates/template_content y part_content
ajustan un origen antes de analizarlo, y blockstudio/site_templates/parser
sustituye el analizador para un elemento. La lista completa está en la
tabla de enlaces de Site Templates.
Cuándo usar cada opción
| Lo que necesita | Opción |
|---|---|
| El diseño del tema que WordPress elige para un URL: encabezado, pie de página, entrada individual o archivo | Plantillas y partes del sitio |
| Una página accesible mediante una ruta cuyo contenido está en archivos | Páginas basadas en archivos |
| Una sección reutilizable que los editores insertan | Patrones |
Las plantillas no crean entradas; las páginas sí. Por ejemplo, una sección de documentación es una colección de páginas cuyas entradas se muestran mediante una plantilla que aún puede crear aquí.
Próximos pasos
- Referencia de Site Templates: todas las propiedades del manifiesto, la PHP API y todos los enlaces.
- Descripción general de Pages & Patterns: el analizador HTML, las etiquetas de bloque y la asignación de elementos que usan los orígenes de las plantillas.
- Building a Documentation Site: colecciones de páginas con Markdown, cargadores y diseños.