Pular para o conteúdo

Páginas

Páginas são modelos baseados em arquivos que sincronizam com o banco de dados WordPress como publicações. A sincronização é explícita: execute wp bs pages sync ou chame as páginas API quando quiser aplicar alterações da fonte. Carregar o frontend ou o painel administrativo WordPress nunca faz uma descoberta completa de páginas nem altera publicações de páginas.

As páginas podem ser definidas como uma única pasta page.json, como arquivos independentes Markdown ou como uma coleção com um manifesto pages.json. Coleções são úteis para documentação, bases de conhecimento, bibliotecas de páginas de destino ou qualquer conjunto de páginas aninhadas que deva ser gerado a partir de arquivos.

page.json

Para uma página definida por JSON, adicione um arquivo de configuração page.json:

JSON
{
  "name": "about",
  "title": "About Us",
  "slug": "about-us",
  "postType": "page",
  "postStatus": "publish",
  "templateLock": "all"
}

Propriedades

Propriedade Tipo Padrão Descrição
name string obrigatório Identificador exclusivo da página
title string Automático a partir do nome O título da página
slug string Igual ao nome Slug URL da página
path string "." Caminho lógico dentro de uma coleção
order integer 0 Ordem no menu da publicação sincronizada
postType string "page" Tipo de publicação WordPress
postStatus string "draft" Status das novas publicações (publish, draft, pending, private)
postId integer – Fixar a página a um ID específico de publicação WordPress
blockEditingMode string – Modo de edição de blocos: "default", "contentOnly" ou "disabled"
templateLock string|false "all" Modo de bloqueio: "all", "insert", "contentOnly" ou false
templateFor string|null null Definir como modelo padrão para um tipo de publicação
sync boolean true Se a reconciliação explícita normal pode criar ou atualizar a publicação
render string|object|false – Renderizar a página com um renderizador de páginas registrado (consulte Páginas de componentes)

Entre page.json, o frontmatter e as entradas do carregador, as chaves reconhecidas incluem blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock e title. Qualquer chave não listada acima é armazenada na matriz meta da página.

Fontes de conteúdo

A definição de uma página determina qual publicação WordPress deve existir. A fonte de conteúdo determina qual marcação de bloco será gravada nessa publicação.

Quando uma pasta de página contém um page.json, Blockstudio procura um arquivo-fonte irmão nesta ordem:

Arquivo Uso
index.php Marcação de bloco no estilo HTML, lida como está (o código PHP não é executado)
index.blade.php Conteúdo de modelo Blade
index.twig Conteúdo de modelo Twig
index.md Conteúdo Markdown

page.json também pode fornecer markdown ou html em linha, em vez de um arquivo irmão:

JSON
{
  "name": "intro",
  "title": "Intro",
  "markdown": "# Intro\n\nThis page is generated from inline markdown."
}
JSON
{
  "name": "notice",
  "title": "Notice",
  "html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}

Coleções adicionam mais dois modos de fonte:

  • Arquivos Markdown encontrados diretamente na árvore da coleção.
  • Entradas do carregador retornadas por loader.php.

As entradas do carregador podem usar markdown, html ou content com contentType. Também podem apontar para um file ou template local. Fontes de arquivos e modelos inferem o tipo pela extensão, a menos que contentType seja definido explicitamente.

Os valores de contentType compatíveis são php, blade, twig, markdown e html. Markdown é convertido primeiro em HTML e, depois, analisado em blocos nativos de WordPress. As fontes PHP, Blade, Twig e HTML passam pelo analisador normal de páginas Blockstudio.

Classes em blocos do núcleo

Uma class em um elemento HTML mapeado para um bloco do núcleo torna-se seu className. Uma tag explícita de bloco do núcleo pode usar className diretamente. Ambas as formas preservam as classes no wrapper salvo do bloco, junto com as classes geradas por WordPress:

HTML
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
  <h2 class="title">Feature</h2>
</block>

Se ambas as propriedades estiverem presentes, className terá precedência. Essa conversão se aplica somente a blocos do núcleo: um mapeamento de bloco personalizado mantém o campo class inalterado. Classes de estilo de botão, como is-style-outline, pertencem ao wrapper do botão, não ao link.

Execute wp bs pages sync para aplicar correções do analisador sintático às páginas sincronizadas anteriormente. As atualizações do analisador são reconhecidas na próxima sincronização explícita, sem precisar editar o arquivo de origem. Páginas bloqueadas e páginas com sync: false mantêm suas proteções normais; solicitações do frontend nunca realizam essa sincronização.

Blocos WordPress serializados

As fontes de páginas e padrões também podem conter blocos serializados copiados do editor de código WordPress:

HTML
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->

Quando a origem contém um delimitador de bloco <!-- wp:... -->, Blockstudio usa o analisador de blocos nativo de WordPress para toda a origem. Atributos, blocos aninhados, blocos dinâmicos como Query Loop e blocos Blockstudio mantêm sua estrutura serializada. HTML fora dos comentários de bloco permanece em HTML livre nativo; não é mapeado para blocos adicionais. Não misture as tags de bloco HTML de Blockstudio com este formato esperando que sejam convertidas. Comentários comuns de HTML não ativam o modo de blocos serializados.

Páginas Markdown

Use Markdown quando o texto deve ficar em arquivos, mas ainda se tornar conteúdo editável de blocos WordPress após a sincronização. A fonte Markdown é convertida em marcação de blocos durante a sincronização. A publicação sincronizada armazena blocos, não o corpo bruto Markdown.

Markdown pode ser usado de três formas:

Fonte Frontmatter obrigatório? Observações
Arquivo pages/example/index.md independente Sim O frontmatter fornece a identidade da página.
page.json mais index.md Não page.json define a página e Markdown fornece o conteúdo.
Markdown dentro de uma coleção Não A coleção infere name e path a partir do local do arquivo.

Um index.md independente sem frontmatter é ignorado, pois Blockstudio não tem identidade de página para sincronizar. O Markdown de uma coleção não precisa de frontmatter, pois o manifesto da coleção e o caminho do arquivo fornecem essa identidade.

Markdown
---
name: about
title: About
slug: about
postStatus: publish
---

# About

This Markdown content is synced as native WordPress blocks.

Você também pode combinar page.json com index.md. Nesse caso, page.json define a página e index.md fornece o conteúdo. O frontmatter em index.md substitui os valores correspondentes de page.json.

JSON
{
  "name": "docs-reference",
  "title": "Reference",
  "path": "reference",
  "sync": true
}
Markdown
---
title: API Reference
order: 20
---

# Reference

This page uses `page.json` with Markdown content.

Para uma coleção Markdown, o caminho do arquivo se torna o caminho lógico da página, a menos que o frontmatter o substitua:

Arquivo Caminho padrão
pages/docs/index.md .
pages/docs/getting-started.md getting-started
pages/docs/guide/install/index.md guide/install
pages/docs/guide/install.md guide/install

Chaves desconhecidas do frontmatter são preservadas no array meta da página. Assim, você pode anexar dados como section ou description e acessá-los no PHP API.

Markdown é analisado como GitHub com sabor Markdown. HTML bruto é permitido, links inseguros são removidos e títulos sem um ID explícito recebem um ID estável. O frontmatter YAML aninhado requer o analisador YAML incluído.

Markdown bruto

Fontes de arquivos Markdown podem expor o Markdown da fonte original para ferramentas externas e consumidores de documentação. O conteúdo Markdown em linha não tem um arquivo-fonte, então é sincronizado em blocos, mas não gera uma resposta .md bruta.

Solicite a página com o sufixo .md, como https://example.com/docs/reference.md. Ou envie um cabeçalho Accept: text/markdown para o URL normal da página:

Shell
curl -H "Accept: text/markdown" https://example.com/docs/reference/

O frontmatter é removido da resposta. Respostas Markdown brutas bem-sucedidas enviam Content-Type: text/markdown, X-Robots-Tag: noindex e um cabeçalho Link canônico de volta para a página HTML. Rotas .md inexistentes retornam um 404 real.

A negociação funciona com pré-renderização estática: uma solicitação cujo cabeçalho Accept contém text/markdown nunca recebe uma resposta do armazenamento de pré-renderização nem do complemento de atendimento antecipado, portanto chega a WordPress e ao manipulador Markdown. Respostas HTML pré-renderizadas, o HTML de uma página que também negocia Markdown e o Markdown respondido por Accept enviam Vary: Accept, para que os caches que respeitam Vary mantenham os dois separados. Um CDN que usa apenas URL como chave de cache precisa de uma regra própria para ignorar o cache nessas solicitações. Pages::negotiates_markdown( $post_id ) informa se uma página responde a solicitações Markdown.

A coleção Markdown mantém a mesma estrutura de URL para Markdown bruto:

Página URL Markdown URL bruto
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

Desative respostas Markdown brutas com o filtro blockstudio/pages/serve_markdown:

PHP
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );

Uma solicitação .md URL que não resolva para uma página baseada em Markdown retorna 404 somente quando o caminho está dentro de uma coleção de páginas. Fora de todas as coleções, Blockstudio deixa a solicitação para WordPress e outros plugins tratarem.

Páginas de componentes

Uma página de componente é renderizada por um renderizador de páginas, em vez de ser armazenada como blocos. Blockstudio não inclui um renderizador. Um tema ou plugin registra um para os arquivos de entrada que ele gerencia, como um renderizador React para page.tsx, e Blockstudio o chama com a página, a publicação WordPress e o conteúdo renderizado do espaço reservado.

Text
pages/legal-notice/
  page.json
  page.tsx
  data.php
JSON
{
  "name": "legal-notice",
  "title": "Legal Notice",
  "slug": "legal-notice",
  "postStatus": "publish",
  "render": { "entry": "page.tsx", "data": "data.php" }
}

render é explícito. Um diretório com um index.php e um page.tsx, mas sem render, continua sendo uma página comum, então adicionar um renderizador nunca renderiza uma página existente duas vezes. As formas são:

Valor Significado
"page.tsx" Somente entrada, sem carregador de dados
{ "entry": "page.tsx", "data": "data.php" } Entrada e carregador de dados
{ "entry": "page.tsx", "renderer": "react" } Entrada com um ID explícito de renderizador
false Sem renderizador, mesmo quando um padrão da coleção especifica um

Os caminhos são resolvidos em relação ao diretório da página ou à raiz da coleção para entradas do carregador. Eles devem permanecer dentro da origem de descoberta, a menos que blockstudio/pages/allow_external_loader_path permita isso. Sem renderer, é usado o renderizador que aceita a extensão da entrada. Um render que especifica uma entrada ou um arquivo de dados inexistente, um renderizador desconhecido ou uma extensão que nenhum renderizador aceita constitui um erro de descoberta, que interrompe a reconciliação antes que qualquer item seja removido.

O que a sincronização armazena

A sincronização armazena um bloco blockstudio/page. Quando o diretório da página também tem uma origem index.*, essa origem é analisada como qualquer origem de página e se torna os blocos internos do bloco, o espaço reservado:

HTML
<!-- wp:blockstudio/page /-->

<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->

Mantenha o conteúdo gerenciado por WordPress, como códigos de acesso, no espaço reservado. Uma origem que contém apenas um código de acesso, como [download_checkout], é armazenada como um bloco core/shortcode, para que a saída não seja envolvida por um parágrafo. Ela permanece em post_content, para que as verificações de has_shortcode() a detectem, os blocos de espaço reservado com chaves sejam mesclados com as alterações do editor como blocos aninhados com chaves, e do_shortcode expanda os códigos de acesso uma vez, na prioridade the_content habitual, depois que o renderizador os tiver envolvido.

A definição de renderização é armazenada com a publicação em caminhos theme: portáteis. A impressão digital da página abrange a definição, mas não os bytes da entrada nem do carregador de dados: editar page.tsx ou data.php não altera a publicação, e as alterações chegam aos visitantes por meio da renderização e do gráfico de pré-renderização estática, que registra a entrada, o carregador de dados e todos os arquivos informados pelo renderizador.

Registrando um renderizador

Registre renderizadores na ação blockstudio/pages/renderers. Ela é executada uma vez por solicitação, antes da primeira descoberta ou renderização, para que wp bs pages sync e as solicitações do frontend vejam o mesmo registro.

PHP
add_action(
	'blockstudio/pages/renderers',
	static function (): void {
		Blockstudio\Page_Renderers::register(
			'react',
			array(
				'extensions' => array( 'tsx' ),
				'layouts'    => array( 'layout.tsx' ),
				'render'     => 'my_theme_render_page',
			)
		);
	}
);

Os IDs dos renderizadores devem estar em letras minúsculas. Uma extensão ou um nome de layout só pode pertencer a um renderizador, e layout.php continua sendo o layout próprio de Blockstudio. A função de chamada recebe uma solicitação:

Chave Valor
kind page ou layout para um layout de renderizador
renderer ID do renderizador
entry Caminho absoluto da entrada
data Caminho absoluto do carregador de dados ou null
page Dados canônicos da página, incluindo meta
post_id ID da publicação WordPress
slot Conteúdo renderizado do espaço reservado ou conteúdo da página para um layout
context frontend, rest, feed ou cli

Ela retorna HTML, os arquivos lidos pela renderização e recursos opcionais:

PHP
function my_theme_render_page( array $request ): array {
	return array(
		'html'         => '<main>...</main>',
		'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
		'assets'       => array( array( 'path' => '/abs/path/to/page.js' ) ),
	);
}

context vem do tipo de solicitação, nunca do visitante, portanto um renderizador não pode quebrar a paridade de bytes entre usuários autenticados e anônimos ao lê-lo. Um renderizador que falha lança uma exceção: a página não é renderizada com o corpo vazio. Em uma prévia do editor REST, o bloco mostra o erro como um aviso. Após uma renderização bem-sucedida, a ação blockstudio/pages/rendered recebe a página, o HTML e suas dependências.

assets lista os arquivos de script e estilo necessários para a página. Eles passam pelo processamento de recursos de bloco (a convenção *.inline.*, módulos ES, minificação e ?ver), e a página os imprime uma vez, pelo mesmo buffer usado para imprimir recursos de bloco, para que uma página pré-renderizada os carregue. Um recurso pode definir version para substituir seu valor ?ver. O código fora de um renderizador pode usar o mesmo canal por meio de Blockstudio\Assets::register_owner(), que retorna o comentário marcador a ser impresso.

Editor

No editor, blockstudio/page mostra uma prévia renderizada no servidor da página, com o slot como blocos internos, que seguem o templateLock da página. O bloco não pode ser inserido, duplicado nem aninhado em outro bloco.

Coleções de páginas

Uma coleção é uma pasta com um manifesto pages.json. Ela agrupa várias fontes de páginas sob um slug de coleção, aplica padrões, aceita caminhos aninhados e pode registrar automaticamente um tipo de publicação dedicado.

Código
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
Propriedade Tipo Descrição
collection / slug / name string Slug da coleção. collection é a forma mais clara e se torna a base pública de URL.
title string Título legível da coleção.
postType string Tipo de post para as páginas geradas. O padrão é page. Se não existir, Blockstudio o registra.
postTypeArgs object Argumentos passados para register_post_type() quando Blockstudio registra o tipo de post da coleção.
defaults object Propriedades de página padrão aplicadas a todas as páginas da coleção. Um render padrão só se aplica a uma página quando sua entrada existe no diretório de páginas.
scope string collection (padrão) ou site. Consulte Coleções de sites.
meta object Metadados personalizados da coleção. As chaves desconhecidas do manifesto também são armazenadas em meta.

Os caminhos das páginas da coleção são caminhos lógicos. Uma página com path: "guide/install" é sincronizada como filha de guide, e guide é sincronizada como filha da raiz da coleção quando essas páginas pai existem.

Se uma coleção hierárquica tiver uma página aninhada, mas não houver uma fonte para um pai intermediário, Blockstudio gera uma página contêiner vazia para esse caminho, mantendo completa a hierarquia WordPress. Tipos de publicação não hierárquicos (que não aceitam pais por meio de page-attributes) não geram contêineres vazios. Eles usam o caminho de coleção armazenado para determinar as rotas, portanto caminhos aninhados como guide/install e setup/install podem coexistir, embora ambos terminem em install.

Tipos de publicação e URLs da coleção

Defina postType no manifesto da coleção para sincronizar todas as páginas da coleção com esse tipo de publicação. Não é necessário repetir o mesmo valor em defaults. Páginas individuais ainda podem substituir postType no frontmatter ou em page.json.

Quando o tipo de publicação não existe, Blockstudio o registra com show_in_rest: true, uma configuração de editor semelhante à de páginas e o slug da coleção como base pública de URL. postTypeArgs pode substituir os argumentos de registro. As regras de reescrita do tipo de publicação da coleção são atualizadas automaticamente quando os tipos registrados ou os argumentos de reescrita da coleção mudam, então não é necessário salvar novamente os links permanentes de WordPress.

Os URLs da coleção usam o slug da coleção seguido do path lógico de cada página:

Caminho de origem Público URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

Este modelo URL funciona tanto para tipos de post de coleção hierárquicos quanto não hierárquicos. Blockstudio também redireciona URLs duplicadas, como /docs/docs/ ou /docs/docs/getting-started/, para a URL canônica.

As páginas de coleção expõem Markdown bruto nas mesmas URLs (consulte Markdown bruto).

Se você mudar uma coleção de postType: "page" para um tipo de post personalizado, Blockstudio migra os posts de coleção já sincronizados no próprio lugar quando a identidade de página armazenada corresponde. Isso preserva os IDs dos posts, os metadados e o conteúdo existente, evitando posts duplicados com o tipo antigo. Os posts de coleção obsoletos são removidos em todos os status de post conforme o filtro blockstudio/pages/orphan_action.

Coleções de sites

Um manifesto com "scope": "site" agrupa todas as páginas abaixo dele sem transformá-las em páginas de coleção. Use-o na raiz da árvore de páginas de um site para aplicar padrões compartilhados e listar as páginas do site com blockstudio_page_tree( 'my-site' ).

JSON
{
  "collection": "my-site",
  "title": "My Site",
  "scope": "site",
  "defaults": {
    "postStatus": "publish",
    "templateLock": "all",
    "render": { "entry": "page.tsx", "data": "data.php" }
  }
}

As páginas de uma coleção de sites mantêm exatamente a mesma identidade que teriam sem o manifesto. Portanto, adicionar um manifesto a uma árvore existente não atualiza linhas de posts nem cria ou move nada para a lixeira:

  • As chaves permanecem globais: Pages::get_page( 'home' ) e as chaves de página armazenadas continuam correspondendo.
  • Os URLs continuam sendo URLs de página WordPress. Não se aplicam regras de reescrita de coleções, filtros de permalink nem redirecionamentos de URL duplicado, e nenhuma página contêiner vazia é gerada.
  • Os caminhos lógicos, slugs, pais e identidades de origem são os das páginas independentes, e os layouts são resolvidos pelo ancestral mais próximo.
  • Os manifestos pages.json aninhados mantêm suas próprias coleções, e suas subárvores ficam fora da coleção de sites.
  • Os padrões são aplicados por página: um render padrão só se aplica às páginas cujo diretório contém sua entrada, portanto páginas de shortcode e Markdown mantêm suas fontes.

Carregadores de coleção

As coleções podem incluir um loader.php local confiável. Use-o quando as páginas da coleção vierem de outra fonte local, como uma pasta externa de documentação, um pacote ou um manifesto gerado.

O carregador é executado durante a descoberta explícita de páginas e a sincronização. Ele deve ser determinístico e local. Evite buscar conteúdo remoto de loader.php, pois isso faria a sincronização de implantação depender desse serviço.

PHP
<?php

return array(
  'meta' => array(
    'source' => 'loader',
  ),
  'paths' => array(
    __DIR__ . '/external-docs',
    array(
      'path' => __DIR__ . '/cli-docs',
      'prefix' => 'cli',
      'meta' => array(
        'doc_set' => 'cli',
      ),
    ),
  ),
  'pages' => array(
    array(
      'name' => 'docs-api',
      'title' => 'API',
      'path' => 'api',
      'content' => "# API\n\nGenerated markdown content.",
      'contentType' => 'markdown',
    ),
    array(
      'name' => 'docs-template',
      'title' => 'Template',
      'path' => 'template',
      'file' => __DIR__ . '/template.md',
    ),
  ),
);

Um carregador pode retornar um array com as chaves pages, meta e paths:

Chave Descrição
pages Uma lista de matrizes de páginas. Cada página aceita as mesmas chaves reconhecidas do frontmatter de page.json e Markdown.
meta Metadados mesclados à matriz meta de cada página gerada pelo carregador.
paths Diretórios locais adicionais a descobrir como parte desta coleção. As entradas podem ser strings ou objetos de caminho.
render Uma definição de renderização para cada página Markdown descoberta a partir de paths.

Como atalho, o carregador pode retornar uma lista simples de arrays de páginas.

As entradas de página do carregador podem fornecer conteúdo destas formas:

Formato Descrição
markdown Conteúdo Markdown embutido.
html Conteúdo HTML embutido.
content + contentType Conteúdo embutido genérico. contentType deve ser resolvido para markdown ou html.
file Fonte de arquivo local. O tipo é inferido pela extensão, a menos que contentType esteja definido.
template Alias de file.

As referências de arquivo do carregador podem apontar para fontes PHP, Blade, Twig, Markdown ou HTML. Os caminhos relativos são resolvidos a partir da raiz da coleção. Caminhos absolutos e caminhos fora da raiz da coleção são permitidos somente quando o filtro blockstudio/pages/allow_external_loader_path permitir.

Por padrão, as páginas do carregador usam generated: true. Quando uma página gerada pelo carregador desaparece da saída do carregador, Blockstudio trata o post sincronizado como órfão na próxima sincronização, removendo-o de acordo com o filtro blockstudio/pages/orphan_action.

Os diretórios listados em paths são descobertos como pastas normais de coleção. Eles podem conter arquivos Markdown ou pastas page.json. Se esses caminhos estiverem fora da raiz da coleção, aplica-se o mesmo filtro de caminhos externos.

Use uma entrada de string quando o diretório externo precisar manter seus próprios caminhos lógicos. Use uma entrada de objeto quando o diretório precisar ser montado sob um prefixo de caminho da coleção:

PHP
'paths' => array(
  array(
    'path' => __DIR__ . '/cli-docs',
    'prefix' => 'cli',
    'meta' => array(
      'doc_set' => 'cli',
    ),
  ),
),

Com essa configuração, cli-docs/index.md passa a ser path: "cli" e cli-docs/getting-started.md passa a ser path: "cli/getting-started" na coleção. Os prefixos também evitam colisões nos nomes das páginas geradas, permitindo que vários diretórios montados contenham cada um index.md ou getting-started.md. Defina preserveNames como true no objeto de caminho se os valores name explícitos do frontmatter de page.json ou Markdown precisarem ser mantidos.

Propriedades do objeto de caminho:

Propriedade Tipo Descrição
path string Diretório local a descobrir. Caminhos relativos são resolvidos a partir da raiz da coleção.
prefix string Prefixo de caminho lógico opcional dentro da coleção.
preserveNames boolean Manter nomes de página explícitos em vez de gerar nomes a partir do caminho com prefixo. O padrão é false quando prefix está definido.
meta object Metadados mesclados a cada página descoberta a partir deste caminho. Os metadados da página prevalecem em caso de chaves duplicadas.
render string|object Uma definição de renderização para as páginas Markdown deste caminho, que substitui a definição render do carregador.

Renderizando Markdown por meio de um componente

Com render, as páginas Markdown descobertas por um carregador são renderizadas por meio de um renderizador de páginas, em vez de serem armazenadas como blocos:

PHP
<?php

return array(
  'paths'  => array( __DIR__ . '/external-docs' ),
  'render' => array(
    'entry' => __DIR__ . '/document.tsx',
    'data'  => __DIR__ . '/document.php',
  ),
);

Elas continuam sendo páginas Markdown: o tipo de conteúdo, o caminho do conteúdo, as respostas .md e o frontmatter não mudam. A sincronização armazena um bloco blockstudio/page, cujo conteúdo interno HTML é o Markdown convertido, sanitizado quando a coleção sanitiza seu conteúdo, em vez de blocos analisados; assim, post_content mantém o texto do documento. O renderizador recebe esse HTML como slot e pode ler a origem de page.content_path. Os caminhos relativos são resolvidos a partir da raiz da coleção; o filtro de caminho externo se aplica como nos outros caminhos. Uma página cujo frontmatter define seu próprio render ou render: false fica de fora.

Layouts

Um arquivo layout.php envolve a renderização no frontend de uma página baseada em arquivo. Ele não substitui o post_content sincronizado armazenado em WordPress e não envolve a tela do editor. O layout é executado somente em solicitações de páginas individuais no frontend.

Para coleções, coloque layout.php ao lado de pages.json para envolver todas as páginas da coleção no frontend:

PHP
<?php $current = blockstudio_current_page(); ?>

<main class="docs-layout">
  <aside>
    <?php foreach (blockstudio_page_tree('docs') as $item) : ?>
      <?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
      <a
        href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
        <?php echo $is_current ? 'aria-current="page"' : ''; ?>
      >
        <?php echo esc_html($item['title']); ?>
      </a>
    <?php endforeach; ?>
  </aside>

  <article>
    <?php echo blockstudio_page_content(); ?>
  </article>
</main>

blockstudio_page_content() imprime o corpo da página que WordPress normalmente renderizaria por meio de the_content. Se um layout não gerar blockstudio_page_content(), o conteúdo da página ficará intencionalmente oculto.

Os layouts podem usar as funções auxiliares da página:

PHP
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();

Páginas aninhadas que não pertencem a coleções também podem herdar o layout.php ancestral mais próximo dentro da árvore pages. Para páginas de coleção, o layout da raiz da coleção é armazenado em cada post sincronizado e monitorado como parte da impressão digital da página; assim, as alterações no layout são aplicadas na próxima sincronização.

Layouts de renderizador

Um layout também pode ser uma entrada de renderizador, como layout.tsx para um renderizador que registra layouts: ["layout.tsx"]. Ele é encontrado nos mesmos locais que layout.php, e um layout.data.php opcional ao lado dele funciona como carregador de dados. No momento da renderização, o renderizador recebe kind: "layout" e o conteúdo renderizado da página como slot, com a mesma prioridade de the_content que layout.php. Um diretório pode conter layout.php ou um layout de renderizador, mas não ambos; conter os dois é um erro de descoberta. Uma falha de layout aciona blockstudio/pages/layout_error e deixa o conteúdo da página sem invólucro, assim como ocorre com layout.php.

Modo de edição de blocos

A propriedade blockEditingMode controla como os blocos podem ser editados no editor. Defina um padrão no nível da página em page.json e substitua-o por elemento no modelo:

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>
Valor Descrição
"default" Edição completa. Os blocos podem ser selecionados, movidos e editados
"contentOnly" Somente edição de texto. O texto do bloco pode ser editado, mas as configurações e a estrutura ficam bloqueadas
"disabled" Sem edição. Os blocos são totalmente não interativos

As substituições por elemento são definidas como atributos HTML em qualquer elemento (<h1>, <p>, <div> etc.) ou em elementos <block>. Os blocos de contêiner ancestrais dos elementos substituídos são definidos automaticamente como contentOnly para que seus filhos continuem acessíveis. Essa propagação sobe do elemento substituído até a raiz da página, então basta definir blockEditingMode nos elementos que você quer tornar editáveis.

Bloqueio de modelo

A propriedade templateLock controla como os usuários podem editar a página no editor:

Valor Adicionar/Remover Mover Editar conteúdo
"all" Não Não Não
"insert" Não Sim Sim
"contentOnly" Não Não Sim
false Sim Sim Sim

Quando um templateLock é definido, Blockstudio desativa a possibilidade de desbloquear blocos por meio do UI do editor.

Rotas virtuais

Alguns documentos não têm um post associado: uma referência de componente gerada a partir de dados, um catálogo ou uma área de conta. Registre-os como rotas virtuais em vez de configurar template_redirect por conta própria:

PHP
add_action( 'init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function ( $component, string $rest ) {
            get_header();
            echo my_component_page( $component );
            get_footer();
        },
        [
            'prefix' => true,
            'match'  => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
            'title'  => fn ( $component ) => my_component_title( $component ),
            'urls'   => fn () => my_component_paths(),
        ]
    );
} );

O caminho é relativo à página inicial do site. Com prefix, a rota também atende todos os caminhos abaixo dela, e match recebe o restante (uma string vazia para a própria rota) e retorna o valor recebido pelo callback de renderização, ou null para deixar que URL chegue a WordPress, que responde a 404 normalmente. O callback de renderização imprime o documento ou o retorna como string; title é uma string ou uma closure que recebe o valor correspondente.

Para uma solicitação correspondente, Blockstudio impede que WordPress sinalize um 404 e que redirect_canonical a redirecione, limpa o estado singular informado pela consulta principal, envia o status (status, 200 por padrão) e renderiza na prioridade template_redirect Virtual_Routes::PRIORITY. Isso acontece logo depois que o buffer de saída de Blockstudio é aberto em Assets::BUFFER_PRIORITY, para que o documento final receba os recursos dos blocos, os recursos agrupados de UI e o Tailwind compilado como qualquer página, e antes de redirect_canonical na prioridade 10. Um manipulador que renderize um documento inteiro por conta própria também precisa ser executado depois de Assets::BUFFER_PRIORITY, ou esse processamento será ignorado. Os caminhos em urls (por padrão, o próprio caminho da rota quando ela não é uma rota de prefixo) são adicionados às compilações de pré-renderização estática, e Virtual_Routes::urls() os retorna como URLs absolutas para um mapa do site. Virtual_Routes::match( $path ) resolve um caminho da mesma forma que uma solicitação.

Comportamento da sincronização

Os posts de página só mudam por meio de uma operação explícita de sincronização:

Shell
wp bs pages sync

O comando descobre todo o inventário de origem, cria ou atualiza posts alterados, remove órfãos confirmados, atualiza o roteamento da coleção e a configuração compilada de templateFor, e informa o que mudou. Adicione --authoritative para substituir o conteúdo gerenciado em vez de preservar o conteúdo do editor associado a chaves, e --full para informar a sincronização como uma reconciliação completa, independentemente da identidade de origem armazenada:

Shell
wp bs pages sync --authoritative --full

Solicitações normais de inicialização do frontend, do painel administrativo, AJAX, REST, cron e WP-CLI genérico não fazem a descoberta completa de páginas, não consultam o inventário de reconciliação gerenciado nem gravam posts de página. Elas usam posts WordPress já sincronizados, além da configuração compacta de coleção e de modelos de tipos de post persistida pela última operação explícita. Uma instalação ou atualização sem dados prévios pode analisar os manifestos da coleção uma vez para restaurar os metadados de roteamento; essa inicialização somente de leitura nunca sincroniza conteúdo. O endpoint autenticado e opcional de atualização do Canvas é uma operação explícita de criação de conteúdo API: o Canvas o chama uma vez quando o espaço de trabalho é aberto para que as fontes novas ou alteradas apareçam no inventário inicial. O modo ao vivo chama o mesmo ponto de entrada ao detectar uma alteração na fonte da página.

Blockstudio\Pages::init() agora registra apenas hooks no momento da solicitação. Integrações que antes passavam um argumento force a esse método devem chamar Blockstudio\Pages::reconcile() ou executar wp bs pages sync.

Para impedir que uma página seja sobrescrita após edições manuais, defina "sync": false em page.json.

Locais de origem portáteis

Os arquivos de tema sincronizados são armazenados como locais relativos ao tema, em vez de caminhos absolutos de instalação. Os arquivos de temas filhos e pais mantêm identidades distintas, mesmo quando têm o mesmo nome de arquivo relativo. Os auxiliares de página ainda retornam valores template_path, content_path, layout_path e directory absolutos resolvidos para a solicitação atual.

Isso permite que a sincronização de CLI e as solicitações da Web usem raízes diferentes no sistema de arquivos, como em hospedagens com isolamento, sem interromper as respostas de Markdown, os layouts, a varredura do editor Tailwind nem o rastreamento da origem da pré-renderização. Os caminhos absolutos de temas existentes são ajustados na leitura quando o nome do diretório do tema não muda. Não é necessária nenhuma sincronização, migração de banco de dados ou gravação de metadados durante a solicitação para lê-los; a próxima sincronização explícita armazenará os locais portáteis.

Um diretório de tema que seja um link simbólico, por exemplo, para um checkout de desenvolvimento, armazena os mesmos locais de theme:, quer a origem seja lida pelo link simbólico ou pelo destino, e os resolve para o diretório de tema configurado.

Arquivos fora dos temas filho e pai ativos continuam sendo compatíveis nos caminhos absolutos configurados, sujeitos às restrições de PHP open_basedir. Eles não podem ser realocados automaticamente: depois de mover uma origem externa, atualize o caminho configurado e execute uma sincronização explícita.

Propriedade dos campos da publicação

postStatus define o status inicial. As sincronizações seguintes preservam os status de rascunho, pendente, privado, publicado e agendado já existentes, inclusive com --authoritative. Um rascunho não é republicado apenas porque seu arquivo contém postStatus: "publish". O comportamento existente de recuperação de itens órfãos permanece inalterado: uma sincronização explícita restaura uma publicação gerenciada que foi movida para a lixeira quando sua origem está presente. Bloqueie a página ou desative a sincronização para impedir essa restauração.

O arquivo continua sendo a fonte do título, slug, tipo de publicação, página pai e ordem configurada no menu. Editar esses valores em WordPress não altera a definição da origem. A próxima sincronização explícita reaplica os valores do arquivo e identifica os campos afetados em pages.<name>.overwritten, com um aviso na saída da tabela de CLI. As permissões nativas de WordPress continuam valendo, inclusive o slug vazio para publicações pendentes quando o usuário que sincroniza não pode publicá-las.

Use blockstudio/pages/update_post_data para uma integração que tenha explicitamente uma política de status diferente. Os blocos com chave preservam o conteúdo dos blocos controlado pelo editor; as chaves não alteram a propriedade do título ou do slug da publicação.

Para páginas de coleção, as impressões digitais abrangem o manifesto, o carregador, a fonte da página, o arquivo de layout, os metadados e os caminhos de origem relacionados. A próxima sincronização explícita aplica as alterações a essas entradas.

Quando uma fonte de coleção é removida, Blockstudio remove a página gerada para que as páginas antigas da coleção não permaneçam após a exclusão do arquivo de origem. Por padrão, as páginas órfãs da coleção são movidas para a lixeira. Use blockstudio/pages/orphan_action para retornar trash, delete ou keep.

Nas solicitações do frontend, Blockstudio hidrata o registro de páginas a partir dos posts publicados já sincronizados. Páginas em rascunho e privadas ficam disponíveis nos contextos do painel administrativo e de sincronização, mas os helpers do frontend só hidratam páginas publicadas.

Reconciliação de implantação

Blockstudio\Pages::reconcile() é o ponto de entrada de implantação PHP. Ele descobre todo o inventário desejado, compara as impressões digitais da origem e do mecanismo de sincronização e retorna um relatório legível por máquina:

PHP
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
  'renames' => [
    [
      'from' => 'pages/old/index.php',
      'to' => 'pages/new/index.php',
    ],
  ],
]);

O relatório contém discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, resultados por página, erros de descoberta e um sourceIdentity determinístico.

Páginas bloqueadas têm status: "locked" e são contabilizadas separadamente das páginas inalteradas. removedPages lista o name, key, postId e o action efetivo de cada página removida (trash ou delete); publicações mantidas ou que já estavam na lixeira não são contabilizadas como recém-removidas. A saída da tabela de CLI também identifica páginas criadas, atualizadas, bloqueadas, removidas e com conteúdo preservado, junto aos IDs das publicações.

Após a análise sintática e a mesclagem por chave, uma publicação final idêntica não chama wp_update_post(), não altera post_modified, não cria uma revisão nem aciona hooks de atualização de publicação. O resultado é unchanged. Quando o conteúdo da origem difere do conteúdo controlado pelo editor em blocos com chave, preserved: true identifica essa decisão, e a contagem de preserved no nível superior a inclui. A nova impressão digital da origem e os metadados gerenciados ainda são registrados para que a próxima sincronização inalterada não faça nada. preserved é um sinalizador adicional, não um status exclusivo: uma página pode preservar conteúdo de blocos com chave e ainda atualizar um título controlado pelo arquivo ou adicionar outro bloco.

authoritative: true pode limpar um bloqueio do Page Sync e substitui o conteúdo pela definição do arquivo em vez de preservar o conteúdo do editor associado a chaves. Mantenha-o false para uma sincronização explícita normal. plan_valid: false, full: true, broad: true, a ausência de uma identidade de origem anterior ou uma impressão digital alterada do mecanismo de sincronização marcam a operação como uma reconciliação completa (fullReconciliation no relatório). Em qualquer caso, cada operação compara o inventário completo. Os registros de renomeação de Git são apenas dicas de identidade. Eles nunca substituem a comparação do inventário completo.

Impressões digitais iguais com caminhos de execução inalterados não geram gravações de post ou postmeta nem disparam hooks de atualização. Quando uma origem inalterada é movida para um novo diretório de versão, a reconciliação atualiza apenas os caminhos persistidos de modelo, conteúdo, layout e diretório; ela não atualiza post_content nem o horário de modificação do post. Páginas gerenciadas ausentes só são removidas após a conclusão da reconciliação completa sem erros de descoberta ou gravação de páginas.

A reconciliação direta de API não marca uma implantação como bem-sucedida. Depois de ativar e verificar o artefato estático correspondente e as rotas, persista explicitamente a identidade retornada:

PHP
Blockstudio\Pages::store_successful_source_identity(
  $report['sourceIdentity']
);

wp bs pages sync armazena a identidade retornada após uma operação bem-sucedida. A inicialização comum de WP-CLI apenas registra os tipos de post e as regras de reescrita de coleções persistidos. Ela não descobre nem sincroniza páginas.

Fixação de ID de post

Por padrão, WordPress atribui IDs de post automaticamente. Se uma página for excluída e criada novamente, o ID mudará, quebrando referências externas como menus ou links fixos no código.

Use postId para fixar uma página a um ID específico:

JSON
{
  "name": "about",
  "title": "About Us",
  "postId": 42
}

Ao criar a página, Blockstudio passa o ID a WordPress por meio de import_id. Se o ID estiver disponível, WordPress o utiliza exatamente. Se o ID já pertencer a um post não relacionado, WordPress atribui silenciosamente um novo ID.

Ao procurar páginas existentes, Blockstudio verifica primeiro o ID fixado, antes dos metadados ou do slug. Assim, se uma página for excluída e sincronizada novamente, ela recuperará o mesmo ID.

Mesclagem de blocos por chave

Por padrão, quando um arquivo de modelo muda, Blockstudio substitui todo o conteúdo do post pelo novo modelo. Isso significa que todas as edições feitas no editor WordPress são perdidas.

Adicione um atributo key aos blocos para preservar as edições dos usuários durante as sincronizações do modelo. Quando um modelo contém blocos com chaves, Blockstudio mescla as alterações do modelo ao conteúdo existente do post, em vez de substituí-lo.

Adicionar chaves

Use o atributo key em qualquer elemento HTML ou elemento <block>:

HTML
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>

<div key="features">
  <p>First feature.</p>
  <p>Second feature.</p>
</div>

<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h2>Hero Title</h2>
  <p>Hero description.</p>
</block>

<block
  name="acme/testimonial"
  key="featured-quote"
  quote="Default quote"
/>

As chaves devem ser únicas globalmente em todo o modelo. Uma chave protege o bloco inteiro e todo o seu conteúdo. Não é preciso atribuir chaves a filhos individuais dentro de um bloco pai com chave. Os blocos com chave podem ser movidos para qualquer posição ou nível de aninhamento entre atualizações do modelo, e o conteúdo dos usuários continuará preservado.

As chaves funcionam da mesma forma para blocos personalizados Blockstudio. O key é metadado estrutural do Page Sync; os valores dos campos personalizados continuam sendo atributos Blockstudio normais. Quando um editor altera esses campos, uma sincronização posterior do modelo mantém os valores do editor e ainda aplica as alterações independentes do modelo. As páginas criadas por versões antigas, com a chave dentro dos dados do campo personalizado, são migradas automaticamente na próxima sincronização.

Como funciona a mesclagem

Quando um arquivo de modelo muda e a página é sincronizada novamente:

Bloco Comportamento
Bloco com chave O conteúdo do usuário e os valores do campo Blockstudio são preservados. Os atributos e a estrutura controlados pelo modelo são aplicados.
Bloco sem chave É substituído completamente pela versão do modelo (como ocorreria sem chaves)

Exemplos

As edições do usuário são preservadas nos blocos com chave:

  1. O modelo define <p key="intro">Default intro.</p>
  2. O usuário edita o parágrafo no editor para "Texto de introdução personalizado."
  3. O desenvolvedor atualiza o modelo, adiciona um novo bloco e altera o layout
  4. Na sincronização: o parágrafo mantém "Texto de introdução personalizado." e o novo layout é aplicado

Os atributos do modelo continuam sendo aplicados:

  1. O modelo tem um bloco de capa com key="hero" e um atributo url
  2. O desenvolvedor altera o atributo url da capa para uma nova imagem de fundo
  3. Na sincronização: a nova imagem de fundo é aplicada, mas as edições do usuário no conteúdo dentro da capa são preservadas

Casos extremos

Cenário Comportamento
Novo bloco com chave adicionado ao modelo Aparece com o conteúdo padrão do modelo
Bloco com chave removido do modelo Excluído do post
Tipo de bloco alterado (mesma chave) O modelo prevalece por completo, sem mesclagem de conteúdo
Chaves duplicadas A segunda ocorrência é tratada como sem chave
Modelo sem chaves Substituição completa (o mesmo comportamento de quando não há chaves)
Sincronização forçada Substituição completa; as chaves são ignoradas
Post bloqueado Nenhuma sincronização

Combinar com controles de edição

As chaves, templateLock e blockEditingMode se combinam para dar a você controle detalhado sobre o que os clientes podem ou não fazer. Veja alguns padrões de fluxo de trabalho comuns.

Página totalmente bloqueada

O desenvolvedor controla tudo. A página é um layout estático que os clientes não podem alterar. Útil para páginas jurídicas, termos de serviço ou qualquer página que só deva mudar por meio do código.

JSON
{
  "name": "terms",
  "title": "Terms of Service",
  "templateLock": "all"
}
HTML
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>

Não são necessárias chaves. O modelo é a única fonte de verdade. Cada sincronização sobrescreve a página inteira.

Layout bloqueado com conteúdo editável

O padrão mais comum. Bloqueie a estrutura da página para impedir que os clientes adicionem, removam ou reorganizem blocos, mas permita que editem o texto em locais específicos. As chaves garantem que as edições sejam mantidas nas atualizações do modelo.

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Title</h1>
  <p blockEditingMode="contentOnly">Edit this description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">Contact Us</block>
</block>

O cliente pode editar o título principal, a descrição e a introdução dos recursos. Nada mais. O texto do botão, URL e a imagem de fundo da capa são controlados pelo desenvolvedor. Quando o desenvolvedor atualiza o modelo (e.g., adiciona um segundo botão), as seções identificadas por chave preservam o texto do cliente.

Modelo em evolução com conteúdo preservado

Para páginas que crescem com o tempo. O desenvolvedor adiciona novas seções ao modelo, e cada sincronização acrescenta o novo conteúdo sem alterar o que o cliente já personalizou.

HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
<div key="testimonials">
  <h2>Testimonials</h2>
  <p>What our clients say.</p>
</div>
<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
</block>

A nova seção de depoimentos e o botão aparecem na sincronização. As edições do cliente no título, na introdução e nos serviços permanecem intactas.

Estrutura inicial criada uma única vez

Crie uma página com uma estrutura inicial e depois entregue-a por completo. Defina sync como false para que a sincronização normal nunca crie nem atualize a página, e crie-a uma única vez com Blockstudio\Pages::force_sync('blog'). Depois disso, o cliente será totalmente responsável pela página.

JSON
{
  "name": "blog",
  "title": "Blog",
  "sync": false
}
HTML
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>

wp bs pages sync ignora esta página, então force_sync() a cria uma única vez. Depois disso, o cliente pode adicionar, remover e reorganizar blocos livremente. As alterações no modelo são ignoradas.

Vinculações de blocos

Uma alternativa à mesclagem por chave é usar WordPress do núcleo e as Vinculações de blocos API para conectar blocos aos metadados da publicação. Esse recurso não é do Blockstudio; é uma funcionalidade nativa do WordPress API. Blockstudio simplesmente repassa o atributo metadata à marcação de bloco gerada. O conteúdo fica nos metadados da publicação, em vez de na marcação do bloco, então as sincronizações do modelo podem sobrescrever a marcação livremente, pois o editor lê os metadados, não o innerHTML.

Passe o atributo metadata a qualquer elemento HTML ou <block>:

HTML
<h1
  metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
  Default Title
</h1>

<p
  metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
  Default description text.
</p>

<img
  metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>

As chaves dos metadados devem ser registradas com show_in_rest ativado:

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest'  => true,
    'single'        => true,
    'type'          => 'string',
    'default'       => 'Default Title',
) );

Chaves vs. vinculações

Aspecto Chaves Vinculações
Conteúdo armazenado em Marcação do bloco (post_content) Metadados da publicação (wp_postmeta)
Sobrevive à sincronização do modelo Sim (mesclado por chave) Sim (os dados ficam nos metadados)
Consultável via WP_Query Não Sim (meta_query)
Disponível em REST API Não Sim
Requer registro Não Sim (register_post_meta)
Usuário pode mover blocos Não (o modelo reaplica a estrutura) Não (o modelo reaplica a estrutura)

As duas abordagens podem ser usadas no mesmo modelo. Use chaves nas seções em que a estrutura do bloco importa (e.g., um grupo com vários blocos filhos). Use vinculações para campos individuais quando também quiser que os dados fiquem acessíveis fora do editor de blocos.

Modelos de tipo de publicação

Use templateFor para definir uma página como modelo padrão de um tipo de publicação:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}

Novas publicações desse tipo começarão com a estrutura de blocos definida.

Caminhos personalizados

Por padrão, Blockstudio examina get_template_directory() . '/pages'. Adicione outros caminhos com o filtro:

PHP
add_filter( 'blockstudio/pages/paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/custom-pages';
    $paths[] = MY_PLUGIN_DIR . '/pages';
    return $paths;
} );

Integrações de execução que reúnem arquivos de várias raízes podem substituir a varredura do sistema de arquivos por uma fonte de descoberta lógica. Os manifestos de página, os layouts, os carregadores e os modelos de origem são resolvidos então pelo caminho lógico, mesmo quando os arquivos selecionados estão em raízes diferentes.

Filtros e ações

A descoberta de páginas, a sincronização e o roteamento de coleções expõem estes pontos de extensão:

Hook Tipo Descrição
blockstudio/pages/paths Filtro Adiciona diretórios que Blockstudio verifica em busca de origens de páginas.
blockstudio/pages/collection_post_type_args Filtro Ajusta os argumentos de register_post_type() para um CPT de coleção.
blockstudio/pages/template_candidates Filtro Ajusta os nomes de arquivo de modelo considerados para uma origem de página.
blockstudio/pages/serve_markdown Filtro Ativa ou desativa respostas brutas de Markdown.
blockstudio/pages/orphan_action Filtro Retorna trash, delete ou keep para a limpeza de itens órfãos.
blockstudio/pages/docs_allowed_html Filtro Ajusta HTML permitidos para o conteúdo gerado de documentos de Markdown.
blockstudio/pages/allow_external_loader_path Filtro Permite paths do carregador fora da raiz da coleção.
blockstudio/pages/manifest_scan_interval Filtro Define a idade máxima de um cache de manifesto legado anterior a 7.6.2 que pode inicializar a configuração persistente do ambiente de execução durante uma atualização.
blockstudio/pages/create_post_data Filtro Modifica os dados da publicação antes da criação de uma página sincronizada.
blockstudio/pages/update_post_data Filtro Modifica os dados da publicação antes da atualização de uma página sincronizada.
blockstudio/pages/sync_engine_inputs Filtro Adiciona uma versão de analisador, mapeamento ou migração que deve ampliar deliberadamente a reconciliação uma vez.
blockstudio/pages/post_created Ação É executada após a criação de uma publicação de página sincronizada.
blockstudio/pages/post_updated Ação É executada após a atualização de uma publicação de página sincronizada.
blockstudio/pages/synced Ação É executada após a conclusão da sincronização do registro de páginas.
blockstudio/pages/reconciled Ação É executada após uma reconciliação explícita, com seu relatório legível por máquina.
blockstudio/pages/renderers Ação Registra renderizadores de página com Blockstudio\Page_Renderers::register(). É acionada uma vez por solicitação.
blockstudio/pages/rendered Ação É executada após a renderização de uma página de componente, com a página, seu HTML e suas dependências.
blockstudio/pages/layout_error Ação É executada quando não é possível renderizar um layout, com o erro, o caminho do layout e a página.

PHP API

PHP
// Get all registered pages.
$pages = Blockstudio\Pages::pages();

// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');

// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');

// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');

// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');

// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');

// Get a specific page.
$page = Blockstudio\Pages::get_page('about');

// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');

// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');

// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();

// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);

// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);

// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');

// Unlock a page.
Blockstudio\Pages::unlock('about');

// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
  'extensions' => ['tsx'],
  'layouts' => ['layout.tsx'],
  'render' => 'my_theme_render_page',
]);

// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');

// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);

Consulte Reconciliação de implantação para entender a semântica dos argumentos, os campos do relatório e o limite de identidade verificada da origem.

As funções auxiliares globais estão disponíveis para modelos e layouts:

PHP
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();

Os arrays de páginas retornados por Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() e pelas funções auxiliares globais incluem a identidade da publicação sincronizada, os caminhos da origem e do modelo, os metadados da coleção e do caminho, o tipo de conteúdo, a política de sincronização, o tipo e o status da publicação, a política de edição, os metadados personalizados e uma chave permalink. Os metadados da coleção são carregados da última reconciliação explícita bem-sucedida. As solicitações normais reconstroem esses dados de execução a partir da configuração persistida e dos metadados da publicação sincronizada, sem ler as árvores de origem das páginas. A classe Pages não oferece um método separado para link permanente.

Criar páginas com base em arquivos

Bloqueio de modelos, modos de edição de blocos, mesclagem por chave e controle do que os clientes podem editar.