Plantillas del sitio
Las plantillas del sitio permiten que los temas de bloques definan fuentes de WordPress wp_template y wp_template_part con la misma sintaxis que prioriza los archivos usada por las páginas y patrones de Blockstudio.
Use las plantillas del sitio cuando quiera controlar el diseño del tema que WordPress selecciona mediante la jerarquía de plantillas del Editor del sitio: portada, entradas individuales, archivos, búsqueda, páginas 404, encabezados, pies de página y otras partes de plantilla.
¿Páginas, patrones o plantillas del sitio?
| Función | Crea | Ideal para |
|---|---|---|
| Páginas | Entradas o elementos de tipos de contenido personalizados | Páginas de contenido reales, páginas de documentación, páginas de destino y contenido al que se puede acceder mediante rutas. |
| Patrones | Patrones de bloques | Secciones reutilizables que insertan los editores. |
| Plantillas del sitio | Fuentes de archivos wp_template y wp_template_part |
Diseño del tema controlado por el Editor del sitio y la jerarquía de plantillas de WordPress. |
Las plantillas del sitio no crean páginas normales. Proporcionan la fuente de archivos que WordPress usa al resolver una plantilla de tema de bloques. Si un usuario personaliza la plantilla en el Editor del sitio, WordPress guarda esa personalización en la base de datos y esta prevalece sobre la fuente de archivos hasta que se restablezca.
Estructura de carpetas
Coloque las plantillas completas en templates/ y las partes de plantilla en parts/:
theme/
templates/
front-page/
template.json
index.php
single/
template.json
index.twig
parts/
header/
part.json
index.php
footer/
part.json
index.php
Cada carpeta tiene un manifiesto y un archivo de origen.
| Archivo | Motor |
|---|---|
index.php |
Marcado de bloques similar a HTML, leído tal cual (el código PHP no se ejecuta) |
index.blade.php |
Blade |
index.twig |
Twig |
index.html |
Marcado de bloques similar a HTML |
Si existen varios archivos de origen, Blockstudio usa este orden:
index.phpindex.blade.phpindex.twigindex.html
WordPress también detecta archivos .html de forma recursiva y normalmente muestra un index.html anidado bajo el slug derivado de su ruta, como header/index.
Cuando ese archivo pertenece a un manifiesto Blockstudio, Blockstudio elimina el duplicado derivado de la ruta y muestra únicamente el slug declarado en el manifiesto.
Las plantillas nativas .html anidadas que no tienen un manifiesto Blockstudio no cambian.
El origen se compila una vez en marcado de bloques nativo de WordPress. No debe depender de la solicitud actual ni de la entrada actual. Coloque el comportamiento de ejecución dentro de bloques dinámicos.
template.json
template.json define una plantilla completa del Editor del sitio.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template",
"postTypes": ["page"]
}
Propiedades
| Propiedad | Tipo | Predeterminado | Descripción |
|---|---|---|---|
slug / name |
string |
Nombre de carpeta | Slug de WordPress plantilla. Use slugs jerárquicos exactos como front-page, single, archive-product o 404. |
title |
string |
Título del slug | Título que se muestra en el Editor del sitio. |
description |
string |
"" |
Descripción que se muestra en el Editor del sitio. |
postTypes |
string[] |
[] |
Tipos de contenido para plantillas personalizadas. Las plantillas de jerarquía del núcleo pueden omitir este campo. |
source / template / file |
string |
Archivo de índice autodetectado | Ruta opcional al archivo de origen relativa a la carpeta de la plantilla. |
status |
string |
"publish" |
Estado de la plantilla. |
sync |
boolean |
false |
Reservado para la materialización futura en la base de datos. Las personalizaciones de usuario nunca se sobrescriben en v1. |
meta |
object |
{} |
Metadatos personalizados para las API auxiliares. Las claves de manifiesto desconocidas también se almacenan aquí. |
Los slugs de plantilla no llevan prefijo. WordPress necesita nombres exactos para la jerarquía de plantillas:
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat
part.json
part.json define una parte de plantilla del Editor del sitio.
{
"slug": "header",
"title": "Header",
"description": "Main site header",
"area": "header"
}
Propiedades
| Propiedad | Tipo | Predeterminado | Descripción |
|---|---|---|---|
slug / name |
string |
Nombre de carpeta | Slug de WordPress parte de plantilla. |
title |
string |
Título del slug | Título que se muestra en el Editor del sitio. |
description |
string |
"" |
Descripción que se muestra en el Editor del sitio. |
area |
string |
"uncategorized" |
Área de la parte de plantilla. Los valores comunes son header, footer y sidebar. |
source / template / file |
string |
Archivo de índice autodetectado | Ruta opcional al archivo de origen relativa a la carpeta de la parte. |
status |
string |
"publish" |
Estado de la parte de plantilla. |
meta |
object |
{} |
Metadatos personalizados para las API auxiliares. Las claves de manifiesto desconocidas también se almacenan aquí. |
Cómo escribir el marcado
Las fuentes de plantillas del sitio usan el mismo analizador que las páginas y los patrones:
<div class="site-shell">
<block name="core/template-part" slug="header" />
<main>
<h1>Welcome</h1>
<p>This template is compiled from Blockstudio files.</p>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" />
</div>
El elemento <main> se convierte en un bloque core/group que se representa como <main>,
y sus elementos secundarios, incluida la etiqueta de bloque core/post-content, se convierten en sus bloques internos. Puede usar:
- elementos estándar de HTML como
<h1>,<p>,<ul>,<div>y los elementos de sección<main>,<header>,<footer>,<article>y<aside> <block name="namespace/block"><bs:namespace-block>- prefijos de etiqueta de bloque configurados
- bloques y componentes de Blockstudio
Los bloques de partes de plantilla reciben el atributo del tema activo cuando WordPress representa la plantilla compilada.
Personalizaciones del Editor del sitio
Blockstudio proporciona la fuente de archivos. WordPress administra las personalizaciones de usuario.
El orden de búsqueda es:
- Personalización de la base de datos del Editor del sitio
- Archivo
.htmldel tema activo nativo - Fuente basada en archivos de Blockstudio
- Alternativas del tema principal o los plugins
Cuando un usuario guarda una plantilla basada en archivos de Blockstudio en el Editor del sitio,
WordPress crea una entrada normal de base de datos wp_template o wp_template_part.
Esa entrada guardada prevalece sobre futuros cambios en los archivos. Al restablecer o eliminar la personalización, vuelve a mostrarse la fuente basada en archivos más reciente.
Blockstudio no escribe en los archivos de v1 las ediciones realizadas en el Editor del sitio.
Rendimiento
El descubrimiento de plantillas se almacena en caché por solicitud y se conserva con los metadatos de vigilancia de archivos. Si se cambia un manifiesto o un archivo de origen, se invalida el contenido compilado en caché. Las personalizaciones de la base de datos no se almacenan en caché por encima de WordPress, que sigue comprobándolas primero.
Las integraciones de ejecución que componen archivos desde varias raíces pueden proporcionar una fuente de descubrimiento lógica para las plantillas y las partes de plantilla. Los manifiestos y las plantillas de origen seleccionadas pueden residir en distintas raíces físicas y conservar un único árbol lógico de tema.
PHP API
$templates = Blockstudio\Site_Templates::templates();
$parts = Blockstudio\Site_Templates::parts();
$template = Blockstudio\Site_Templates::get_template('front-page');
$header = Blockstudio\Site_Templates::get_part('header');
$paths = Blockstudio\Site_Templates::get_paths();
Pase una lista explícita para leer y compilar únicamente los slugs, las rutas o las rutas de origen exactos:
$templates = Blockstudio\Site_Templates::templates([
'front-page',
]);
$parts = Blockstudio\Site_Templates::parts([
'header',
]);
$errors = Blockstudio\Site_Templates::selection_errors('templates');
Si se omite el argumento, se conserva el comportamiento completo del registro. Si se pasa una lista vacía, no se devuelve ningún elemento. Las solicitudes de slug y ruta convencionales limitan el descubrimiento a los directorios coincidentes; los slugs personalizados del manifiesto pueden requerir un análisis de metadatos, pero no se compilan ni devuelven otras fuentes.
También hay funciones auxiliares de plantillas disponibles:
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');
Hooks
La superficie de extensión completa de las plantillas del sitio es:
| Hook | Tipo | Descripción |
|---|---|---|
blockstudio/site_templates/template_paths |
Filtro | Ajusta las raíces de descubrimiento de plantillas completas. |
blockstudio/site_templates/part_paths |
Filtro | Ajusta las raíces de descubrimiento de partes de plantilla. |
blockstudio/site_templates/paths |
Filtro | Ajusta ambas listas de rutas como templates y parts. |
blockstudio/site_templates/template_candidates |
Filtro | Ajusta los archivos de origen candidatos para un manifiesto. |
blockstudio/site_templates/templates |
Filtro | Ajusta las plantillas devueltas por el API del registro. |
blockstudio/site_templates/parts |
Filtro | Ajusta las partes de plantilla devueltas por el API del registro. |
blockstudio/site_templates/template_content |
Filtro | Ajusta el origen de plantilla completa compilado antes del análisis. |
blockstudio/site_templates/part_content |
Filtro | Ajusta el origen de parte de plantilla compilado antes del análisis. |
blockstudio/site_templates/parser |
Filtro | Reemplaza la instancia de Html_Parser de un elemento. |
blockstudio/site_templates/source_compiled |
Acción | Se ejecuta inmediatamente antes de compilar un origen seleccionado. |
blockstudio/site_templates/discovered |
Acción | Se ejecuta tras una pasada en frío de descubrimiento y compilación. |
blockstudio/site_templates/registered |
Acción | Se ejecuta después de guardar el registro reconstruido. |
Añadir o sustituir rutas de descubrimiento:
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;
});
add_filter('blockstudio/site_templates/paths', function ($paths) {
return $paths;
});
Filtrar los datos descubiertos:
add_filter('blockstudio/site_templates/templates', function ($templates) {
return $templates;
});
add_filter('blockstudio/site_templates/parts', function ($parts) {
return $parts;
});
Filtrar el origen antes del análisis:
add_filter('blockstudio/site_templates/template_content', function ($content, $template) {
return $content;
}, 10, 2);
add_filter('blockstudio/site_templates/part_content', function ($content, $part) {
return $content;
}, 10, 2);
Cambiar los orígenes candidatos o el analizador:
add_filter(
'blockstudio/site_templates/template_candidates',
function ($candidates, $directory, $manifest) {
$candidates[] = $directory . '/template.custom.php';
return $candidates;
},
10,
3
);
add_filter(
'blockstudio/site_templates/parser',
function ($parser, $item) {
return $parser;
},
10,
2
);
discovered y registered son acciones del ciclo de vida de reconstrucción de la caché. No se ejecutan cuando se encuentra una caché de registro activa.