Pular para o conteúdo

Modelos do site

Os modelos do site permitem que temas de blocos definam fontes WordPress wp_template e wp_template_part usando a mesma sintaxe baseada em arquivos que as páginas e os padrões de Blockstudio.

Use modelos do site quando quiser controlar o layout do tema selecionado por WordPress através da hierarquia de modelos do Editor do site: página inicial, publicações individuais, arquivos, pesquisa, páginas 404, cabeçalhos, rodapés e outras partes de modelo.

Páginas, padrões ou modelos do site?

Recurso Cria Ideal para
Páginas Publicações ou entradas de tipos de publicação personalizados Páginas de conteúdo reais, páginas de documentação, páginas de destino e conteúdo acessível por rotas.
Padrões Padrões de blocos Seções reutilizáveis inseridas por editores.
Modelos do site wp_template e fontes de arquivos wp_template_part Layout do tema controlado pelo Editor do site e pela hierarquia de modelos WordPress.

Os modelos do site não criam páginas comuns. Eles fornecem a fonte de arquivos usada por WordPress para resolver um modelo de tema de blocos. Se um usuário personaliza o modelo no Editor do site, WordPress armazena essa personalização no banco de dados, onde ela prevalece sobre a fonte de arquivos até que seja redefinida.

Estrutura de pastas

Coloque os modelos completos em templates/ e as partes de modelo em 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 pasta contém um manifesto e um arquivo de origem.

Arquivo Mecanismo
index.php Marcação de blocos semelhante a HTML, lida como está (o código PHP não é executado)
index.blade.php Blade
index.twig Twig
index.html Marcação de blocos semelhante a HTML

Se houver vários arquivos de origem, Blockstudio usa esta ordem:

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.html

WordPress também encontra arquivos .html recursivamente e normalmente expõe um index.html aninhado com um slug derivado do caminho, como header/index. Quando esse arquivo pertence a um manifesto Blockstudio, Blockstudio remove a duplicata derivada do caminho e expõe somente o slug declarado no manifesto. Os modelos .html nativos aninhados sem um manifesto Blockstudio permanecem inalterados.

A origem é compilada uma vez em marcação de blocos nativa WordPress. Ela não deve depender da solicitação nem da publicação atual. Coloque o comportamento de execução dentro de blocos dinâmicos.

template.json

template.json define um modelo completo do Editor do site.

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template",
  "postTypes": ["page"]
}

Propriedades

Propriedade Tipo Padrão Descrição
slug / name string Nome da pasta Slug do modelo WordPress. Use slugs exatos da hierarquia, como front-page, single, archive-product ou 404.
title string Título derivado do slug Título exibido no Editor do site.
description string "" Descrição exibida no Editor do site.
postTypes string[] [] Tipos de publicação para modelos personalizados. Modelos da hierarquia do núcleo podem omitir isso.
source / template / file string Arquivo de índice detectado automaticamente Caminho opcional do arquivo de origem relativo à pasta do modelo.
status string "publish" Status do modelo.
sync boolean false Reservado para materialização futura no banco de dados. Personalizações dos usuários nunca são sobrescritas em v1.
meta object {} Metadados personalizados para APIs auxiliares. Chaves desconhecidas do manifesto também são armazenadas aqui.

Os slugs de modelos não têm prefixo. WordPress precisa de nomes exatos para a hierarquia de modelos:

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 uma parte de modelo do Editor do site.

JSON
{
  "slug": "header",
  "title": "Header",
  "description": "Main site header",
  "area": "header"
}

Propriedades

Propriedade Tipo Padrão Descrição
slug / name string Nome da pasta Slug da parte de modelo WordPress.
title string Título derivado do slug Título exibido no Editor do site.
description string "" Descrição exibida no Editor do site.
area string "uncategorized" Área da parte de modelo. Os valores comuns são header, footer e sidebar.
source / template / file string Arquivo de índice detectado automaticamente Caminho opcional do arquivo de origem relativo à pasta da parte.
status string "publish" Status da parte de modelo.
meta object {} Metadados personalizados para APIs auxiliares. Chaves desconhecidas do manifesto também são armazenadas aqui.

Autoria da marcação

As fontes dos modelos do site usam o mesmo analisador que páginas e padrões:

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>

O elemento <main> se torna um bloco core/group que é renderizado como <main>, e seus elementos filhos, incluindo a tag de bloco core/post-content, tornam-se blocos internos. Você pode usar:

  • elementos HTML padrão, como <h1>, <p>, <ul>, <div> e os elementos de seção <main>, <header>, <footer>, <article> e <aside>
  • <block name="namespace/block">
  • <bs:namespace-block>
  • prefixos configurados para tags de bloco
  • blocos e componentes Blockstudio

Os blocos de partes de modelo recebem o atributo do tema ativo quando WordPress renderiza o modelo compilado.

Personalizações do Editor do site

Blockstudio fornece a fonte de arquivos. WordPress gerencia as personalizações dos usuários.

A ordem de consulta é:

  1. Personalização no banco de dados do Editor do site
  2. Arquivo .html do tema ativo nativo
  3. Fonte baseada em arquivo de Blockstudio
  4. Alternativas do tema pai ou do plugin

Quando um usuário salva no Editor do site um modelo baseado em arquivo Blockstudio, WordPress cria uma entrada normal de banco de dados wp_template ou wp_template_part. Essa entrada salva prevalece sobre futuras alterações no arquivo. Redefinir ou excluir a personalização revela novamente a versão mais recente da fonte baseada em arquivo.

Blockstudio não grava no arquivo v1 as edições feitas no Editor do site.

Desempenho

A descoberta de modelos é armazenada em cache por solicitação e persistida com metadados de monitoramento de arquivos. Alterar um manifesto ou arquivo de origem invalida o conteúdo compilado em cache. As personalizações do banco de dados não são armazenadas em cache: WordPress ainda as verifica primeiro.

Integrações de execução que reúnem arquivos de várias raízes podem fornecer uma fonte de descoberta lógica para modelos e partes de modelo. Os manifestos e os modelos de origem selecionados podem estar em raízes físicas diferentes, mantendo uma única árvore lógica 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();

Passe uma lista explícita para ler e compilar somente slugs, caminhos ou caminhos de origem exatos:

PHP
$templates = Blockstudio\Site_Templates::templates([
    'front-page',
]);

$parts = Blockstudio\Site_Templates::parts([
    'header',
]);

$errors = Blockstudio\Site_Templates::selection_errors('templates');

Omitir o argumento mantém o comportamento completo do registro. Passar uma lista vazia não retorna nenhum item. Solicitações convencionais de slugs e caminhos limitam a descoberta aos diretórios correspondentes; slugs personalizados do manifesto podem exigir uma verificação de metadados, mas fontes não relacionadas não são compiladas nem retornadas.

As funções auxiliares de modelos também estão disponíveis:

PHP
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');

Hooks

A superfície completa de extensão dos modelos do site é:

Gancho Tipo Descrição
blockstudio/site_templates/template_paths Filtro Ajusta as raízes de descoberta de modelos completos.
blockstudio/site_templates/part_paths Filtro Ajusta as raízes de descoberta de partes de modelo.
blockstudio/site_templates/paths Filtro Ajusta ambas as listas de caminhos como templates e parts.
blockstudio/site_templates/template_candidates Filtro Ajusta os arquivos de origem candidatos para um manifesto.
blockstudio/site_templates/templates Filtro Ajusta os modelos retornados pelo API do registro.
blockstudio/site_templates/parts Filtro Ajusta as partes de modelo retornadas pelo API do registro.
blockstudio/site_templates/template_content Filtro Ajusta a origem compilada do modelo completo antes da análise.
blockstudio/site_templates/part_content Filtro Ajusta a origem compilada da parte de modelo antes da análise.
blockstudio/site_templates/parser Filtro Substitui a instância Html_Parser de um item.
blockstudio/site_templates/source_compiled Ação Executa imediatamente antes da compilação de uma origem selecionada.
blockstudio/site_templates/discovered Ação Executa após uma descoberta a frio e uma etapa de compilação.
blockstudio/site_templates/registered Ação Executa após a persistência do registro reconstruído.

Adicione ou substitua caminhos de descoberta:

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;
});

Filtre os dados descobertos:

PHP
add_filter('blockstudio/site_templates/templates', function ($templates) {
    return $templates;
});

add_filter('blockstudio/site_templates/parts', function ($parts) {
    return $parts;
});

Filtre a origem antes da análise:

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);

Altere as origens candidatas ou o analisador:

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 e registered são ações do ciclo de vida de reconstrução do cache. Elas não são acionadas quando há um acerto no cache aquecido do registro.