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/:
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:
index.phpindex.blade.phpindex.twigindex.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.
{
"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:
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.
{
"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:
<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 é:
- Personalização no banco de dados do Editor do site
- Arquivo
.htmldo tema ativo nativo - Fonte baseada em arquivo de Blockstudio
- 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
$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:
$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:
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:
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:
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:
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:
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.