Pular para o conteúdo

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:

Código
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:

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

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

HTML
<!-- 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.

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:

JSON
{
  "slug": "footer",
  "title": "Footer",
  "area": "footer"
}
HTML
<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.

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template"
}
PHP
<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:

JSON
{
  "slug": "single",
  "title": "Single Post"
}
PHP
<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:

HTML
<!-- 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:

JSON
{
  "slug": "page-landing",
  "title": "Landing Page",
  "description": "Full-width page without a header",
  "postTypes": ["page"]
}
PHP
<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 é:

  1. Uma personalização do Editor do Site armazenada no banco de dados.
  2. Um arquivo .html nativo no tema ativo.
  3. A fonte baseada em arquivos Blockstudio.
  4. 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:

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

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

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

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