Modelos e partes de modelos do Editor do Site a partir de arquivos
Um tema de blocos descreve seu layout em templates/*.html e parts/*.html:
arquivos repletos de comentários de bloco serializados, como
<!-- wp:template-part {"slug":"header"} /-->. Ninguém gosta de escrevê-los à
mão, então normalmente eles são criados no Editor do Site e exportados. Isso funciona
até que duas pessoas editem o mesmo modelo ou alguém precise revisar um diff de
JSON escapado em comentários HTML.
Blockstudio permite escrever os mesmos modelos como páginas baseadas em arquivos:
uma pasta com um pequeno manifesto JSON e um arquivo-fonte com marcação no estilo HTML, usando elementos simples, tags <block> e seus próprios blocos Blockstudio.
Blockstudio compila o código-fonte em marcação de bloco nativa e o entrega ao WordPress
como arquivo de tema. O Editor do Site continua funcionando exatamente como antes: os usuários podem
personalizar um modelo e, ao redefini-lo, restaurar a versão do arquivo.
Este guia cria uma parte de cabeçalho e rodapé, modelos para a página inicial e para conteúdo individual, e um modelo personalizado que os editores podem escolher para páginas; em seguida, mostra como WordPress resolve esses arquivos.
Estrutura de pastas
Os modelos ficam em templates/ e as partes de modelos, em parts/. Cada item é uma pasta
com um manifesto e um arquivo-fonte:
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
São as mesmas pastas templates/ e parts/ que WordPress lê para um tema
de blocos. Blockstudio verifica primeiro o tema ativo e depois o tema pai.
Pastas com template.json ou part.json são fontes de Blockstudio; arquivos
.html simples ao lado delas continuam sendo modelos WordPress nativos.
O arquivo-fonte pode ser index.php, index.blade.php, index.twig ou
index.html, nessa ordem de verificação. Twig requer Timber, e Blade requer seu
pacote de renderização, conforme descrito em
Mecanismos de modelo.
Etapa 1: A parte do cabeçalho
Cada parte precisa de um part.json. O area informa ao Editor do Site onde a parte
deve ficar:
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
A fonte usa a mesma sintaxe que as páginas e os padrões Blockstudio. Um <div>
se torna um bloco de grupo, os atributos se tornam atributos de bloco e elementos <block>
geram qualquer bloco registrado:
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
Blockstudio compila o conteúdo para esta marcação de bloco:
<!-- 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 -->
Isso é o que você teria escrito à mão. Seus próprios blocos funcionam da
mesma forma: <block name="acme/announcement" />, uma tag <bs:acme-announcement />
ou um prefixo de tag configurado compilam para o comentário de bloco correspondente.
Etapa 2: A parte do rodapé
Uma parte pode ser tão pequena quanto um parágrafo. Esta usa index.html para deixar
claro que a fonte é marcação, não um programa:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
O resultado da compilação é <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.
Etapa 3: Página inicial e modelos de conteúdo individual
Os modelos usam template.json. O slug deve ser um nome de hierarquia
exato de modelo WordPress, como front-page, single, page, archive, 404 ou
single-product. Blockstudio nunca é prefixado a ele.
{
"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" />
O modelo de post individual segue o mesmo formato, com blocos de post:
{
"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" />
O modelo individual compilado:
<!-- 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 tornou um bloco de grupo com tagName: "main", e os blocos de partes de modelo
referenciam por slug as partes das etapas 1 e 2. Quando WordPress renderiza
o modelo, essas referências apontam para as partes baseadas em arquivos; assim, a saída da página inicial começa
com <header class="wp-block-template-part">, que contém o título e a navegação do site, e termina com <footer class="wp-block-template-part">, que contém o parágrafo do rodapé.
Etapa 4: Um modelo personalizado para páginas
Modelos cujo slug não faz parte da hierarquia são modelos personalizados. Liste
os tipos de post aos quais se aplicam com postTypes, e os editores poderão escolhê-los
no seletor de modelos:
{
"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' ) agora
inclui page-landing, e o objeto do modelo contém
post_types: ["page"].
As fontes são compiladas uma vez
A fonte é lida e compilada em marcação de bloco uma vez, não a cada requisição. Ela não tem
post atual nem contexto da requisição. index.php é lido como marcação: o código PHP
nele não é executado, então <?php echo get_bloginfo( 'name' ); ?> é compilado como
nada. Tudo que depende da requisição deve ficar em um bloco renderizado
em tempo de execução: core/site-title em vez de um nome de site exibido, core/post-title
em vez de the_title(), ou um bloco dinâmico Blockstudio próprio.
Os resultados compilados são armazenados em cache com metadados de monitoramento de arquivos. A edição de um manifesto ou arquivo-fonte invalida o conteúdo em cache desse item, e a próxima requisição recebe a alteração sem uma etapa de compilação separada.
Como WordPress encontra os arquivos
Blockstudio usa as mesmas consultas que WordPress usa para modelos de tema. Em
get_block_templates(), os modelos baseados em arquivos aparecem com
source: "theme" e origin: "theme", como arquivos nativos do tema, e
get_block_template( 'acme//header', 'wp_template_part' ) retorna a parte do cabeçalho
com seu area.
A ordem de consulta é:
- Uma personalização do Editor do Site armazenada no banco de dados.
- Um arquivo
.htmlnativo no tema ativo. - A fonte baseada em arquivos Blockstudio.
- Alternativas do tema pai ou de plugins.
Essa ordem mantém intacto o fluxo de trabalho do Editor do Site. Quando um usuário edita o rodapé
e salva, WordPress armazena um post wp_template_part, e
get_block_template() retorna essa personalização com source: "custom".
Alterações posteriores em parts/footer/index.html não aparecem enquanto a
personalização existir. Quando o usuário redefine a parte ou o post é excluído,
a consulta recorre ao arquivo e retorna novamente a versão mais recente compilada da fonte.
Blockstudio não grava nos arquivos as edições feitas no Editor do Site. Se uma alteração do usuário dever se tornar o novo padrão, copie-a para o arquivo-fonte e redefina a personalização.
index.html aninhados e slugs
WordPress localiza recursivamente arquivos .html em templates/ e parts/. Por isso, uma
pasta de manifesto que use index.html, como parts/footer/index.html, também
apareceria como uma parte nativa com o slug derivado do caminho
footer/index. Como Blockstudio 7.6.6, um index.html pertencente a um manifesto
fica disponível apenas com o slug declarado; assim, o Editor do Site lista um único rodapé, não dois. Arquivos .html aninhados sem manifesto são mantidos como estão.
Verificando modelos de PHP
A classe Blockstudio\Site_Templates lê e compila as fontes, o que é
útil em testes e verificações de implantação:
$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 item inclui slug, title, description, type (wp_template ou
wp_template_part), status, source_type, postTypes para modelos ou
area para partes, meta e o content compilado. Passe uma lista para compilar
apenas os itens selecionados e consulte os problemas dessa seleção com
selection_errors():
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
Adicionando outras pastas
Para manter as fontes Blockstudio separadas dos modelos nativos ou distribuí-las por um plugin, adicione raízes de descoberta com 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;
} );
Os filtros blockstudio/site_templates/template_content e part_content
ajustam uma fonte antes de ela ser analisada, e blockstudio/site_templates/parser
troca o analisador de um item. A lista completa está na
tabela de hooks de modelos do site.
Quando usar cada opção
| Você quer | Use |
|---|---|
| O layout do tema que WordPress escolhe para um URL: cabeçalho, rodapé, conteúdo individual, arquivo | Modelos e partes do site |
| Uma página acessível por rota cujo conteúdo fica em arquivos | Páginas baseadas em arquivos |
| Uma seção reutilizável que os editores inserem | Padrões |
Modelos não criam posts. Páginas, sim. Uma seção de documentação, por exemplo, é uma coleção de páginas cujos posts são renderizados por um modelo que você ainda pode criar por aqui.
Próximas etapas
- Referência de modelos do site: cada propriedade do manifesto, o PHP API e todos os hooks.
- Visão geral de páginas e padrões: o analisador HTML, as tags de bloco e o mapeamento de elementos usados pelas fontes de modelos.
- Criação de um site de documentação: coleções de páginas com Markdown, carregadores e layouts.