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:
{
"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:
{
"name": "intro",
"title": "Intro",
"markdown": "# Intro\n\nThis page is generated from inline markdown."
}
{
"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:
<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:
<!-- 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.
---
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.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
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:
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:
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.
pages/legal-notice/
page.json
page.tsx
data.php
{
"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:
<!-- 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.
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:
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.
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
loader.php
{
"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' ).
{
"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.jsonaninhados 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
renderpadrã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
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:
'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
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 $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:
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:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<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:
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:
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:
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:
$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:
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:
{
"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>:
<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:
- O modelo define
<p key="intro">Default intro.</p> - O usuário edita o parágrafo no editor para "Texto de introdução personalizado."
- O desenvolvedor atualiza o modelo, adiciona um novo bloco e altera o layout
- 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:
- O modelo tem um bloco de capa com
key="hero"e um atributourl - O desenvolvedor altera o atributo
urlda capa para uma nova imagem de fundo - 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.
{
"name": "terms",
"title": "Terms of Service",
"templateLock": "all"
}
<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.
{
"name": "landing",
"title": "Landing Page",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<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.
<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>
<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.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<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>:
<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:
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:
{
"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:
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
// 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:
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.