Saltar al contenido

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/:

Text
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:

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.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.

JSON
{
  "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:

Text
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.

JSON
{
  "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:

PHP
<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:

  1. Personalización de la base de datos del Editor del sitio
  2. Archivo .html del tema activo nativo
  3. Fuente basada en archivos de Blockstudio
  4. 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

PHP
$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:

PHP
$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:

PHP
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:

PHP
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:

PHP
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:

PHP
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:

PHP
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.