Pular para o conteúdo

Criação de páginas baseadas em arquivos

A criação tradicional de páginas WordPress acontece no editor de blocos: arrastar blocos, configurar opções e clicar em salvar. Isso funciona para clientes que criam as próprias páginas, mas gera problemas para desenvolvedores que criam páginas estruturadas e com controle de versão. O layout da página fica no banco de dados, não no código. Você não pode revisá-lo em uma pull request, revertê-lo com git nem reproduzi-lo em uma instalação nova.

As páginas baseadas em arquivos de Blockstudio resolvem esse problema. Você define páginas em arquivos no seu tema, escreve modelos HTML que se convertem em blocos WordPress e controla exatamente o que os clientes podem ou não editar. Um comando explícito sincroniza esses arquivos com publicações WordPress normais, e seus modelos continuam sendo a fonte da verdade.

Este guia explica como criar páginas do zero, com foco detalhado nos controles de bloqueio e edição que tornam as páginas baseadas em arquivos práticas para projetos de clientes.

Sua primeira página

Crie uma pasta pages no seu tema e adicione uma subpasta com dois arquivos:

Código
theme/
└── pages/
    └── about/
        ├── page.json
        └── index.php
JSON
{
  "name": "about",
  "title": "About Us",
  "postStatus": "publish"
}
HTML
<h1>About Us</h1>
<p>We build things for the web.</p>

Execute o comando de sincronização de páginas:

Shell
wp bs pages sync

Blockstudio analisa o HTML em blocos WordPress e cria uma página chamada “About Us” com o slug about. Abra-a no editor e você verá um cabeçalho e um parágrafo, exatamente como se os tivesse adicionado manualmente.

Edite index.php, altere o texto e execute o comando novamente. Recarregue o editor para ver a atualização. Esse é o ciclo principal: escrever HTML, sincronizar intencionalmente e obter blocos.

A linguagem de modelos

O analisador HTML de Blockstudio converte elementos HTML padrão em blocos WordPress. Escreva um <p> e você terá um bloco de parágrafo. Escreva um <h2> e você terá um bloco de cabeçalho. O mapeamento é intuitivo:

HTML Bloco
<p> Parágrafo
<h1> até <h6> Cabeçalho (o nível corresponde à tag)
<ul>, <ol> Lista
<blockquote> Citação
<img> Imagem
<div>, <section> Grupo
<hr> Separador
<details> Detalhes
<table> Tabela

Para blocos sem um equivalente direto em HTML, use o elemento <block> com um atributo name:

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h2>Hero Title</h2>
  <p>Content over the background image.</p>
</block>

<block name="core/spacer" height="80px" />

<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
  <block name="core/button" url="/work">See Our Work</block>
</block>

Os atributos nos elementos <block> são passados como atributos de bloco. Os valores são convertidos automaticamente: "true" se torna booleano, "3" se torna inteiro e strings JSON como '{"type":"flex"}' são decodificadas em objetos.

Layouts

Os grupos permitem diferentes modos de layout por meio do atributo layout:

HTML
<!-- Default group (stacked) -->
<div>
  <p>Stacked by default.</p>
</div>

<!-- Row (horizontal flex) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
  <p>Side</p>
  <p>by side</p>
</block>

<!-- Stack (vertical flex) -->
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
  <p>Stacked</p>
  <p>with flex</p>
</block>

<!-- Columns -->
<block name="core/columns">
  <block name="core/column">
    <p>Left column.</p>
  </block>
  <block name="core/column">
    <p>Right column.</p>
  </block>
</block>

Blocos personalizados

A sintaxe <block> funciona com qualquer bloco registrado, inclusive seus próprios blocos Blockstudio:

HTML
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />

Os atributos são mapeados automaticamente para os valores dos campos Blockstudio do bloco.

Criar uma página de destino

Veja uma página de destino completa que usa blocos básicos para estrutura e layout:

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "slug": "landing",
  "postStatus": "publish",
  "templateLock": "all"
}
HTML
<block name="core/cover" url="https://images.unsplash.com/photo-1497366216548-37526070297c?w=1600">
  <h1>Build faster with Blockstudio</h1>
  <p>File-based blocks. Zero build step. Full editor integration.</p>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Get Started</block>
    <block name="core/button" url="/docs">Documentation</block>
  </block>
</block>

<div>
  <h2>Why developers love it</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3>No build step</h3>
      <p>Write PHP, CSS, and JavaScript. No webpack, no bundler, no transpiler.</p>
    </block>
    <block name="core/column">
      <h3>File-based</h3>
      <p>Every block is a folder. Every page is a template. Version control everything.</p>
    </block>
    <block name="core/column">
      <h3>Full editor support</h3>
      <p>Fields, previews, and InnerBlocks work in the block editor out of the box.</p>
    </block>
  </block>
</div>

<block name="core/media-text" mediaurl="https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=800" mediatype="image">
  <h2>Ship entire sites from your IDE</h2>
  <p>Define pages, blocks, and patterns as files. Blockstudio handles the rest.</p>
</block>

<div>
  <h2>Frequently asked questions</h2>
  <details>
    <summary>Do I need to learn React?</summary>
    <p>No. Templates are PHP. Fields are JSON. Interactivity is optional.</p>
  </details>
  <details>
    <summary>Does it work with my existing theme?</summary>
    <p>Yes. Drop a blockstudio folder into any theme and start creating blocks.</p>
  </details>
</div>

<div>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Start Building</block>
  </block>
</div>

Esta página tem uma seção principal de capa, uma grade de recursos com três colunas, uma seção de mídia e texto, acordeões de perguntas frequentes e uma CTA. Tudo em um único arquivo HTML. O templateLock: "all" em page.json significa que o cliente não pode alterar nada. A próxima seção explica como flexibilizar isso.

Controlar o editor

É aqui que as páginas baseadas em arquivos se tornam realmente poderosas. Blockstudio oferece dois controles independentes: bloqueio do modelo e modo de edição de blocos. Juntos, eles permitem definir exatamente quais partes de uma página os clientes podem modificar. Bloqueie a estrutura, mas permita que editem o texto. Congele algumas seções e deixe outras totalmente abertas. Crie uma página em que a única coisa que o cliente possa fazer seja digitar em três títulos específicos.

Bloqueio do modelo

A propriedade templateLock em page.json controla a edição estrutural: se blocos podem ser adicionados, removidos ou reorganizados.

"all" (padrão)

JSON
{
  "name": "terms",
  "templateLock": "all"
}

O bloqueio mais restritivo. Os clientes não podem adicionar, remover ou mover blocos. Também não podem editar o conteúdo dos blocos (a menos que combinado com blockEditingMode). Esse é o padrão quando nenhum valor é especificado.

Quando usar: páginas legais, termos de serviço e políticas de privacidade. Qualquer página cujo conteúdo só deva mudar por meio de código.

"insert"

JSON
{
  "name": "about",
  "templateLock": "insert"
}

Os clientes não podem adicionar nem remover blocos, mas podem mover os blocos existentes e editar seu conteúdo. A quantidade de blocos permanece fixa, mas a ordem é flexível.

Quando usar: páginas em que você quer um conjunto fixo de seções, mas o cliente deve poder reordená-las. Uma página de portfólio com um número predeterminado de seções, cuja ordem fica a critério do cliente.

"contentOnly"

JSON
{
  "name": "homepage",
  "templateLock": "contentOnly"
}

Os clientes podem editar o conteúdo textual, mas não podem adicionar, remover nem mover blocos. A diferença em relação a "all" é que "all" também impede a edição do conteúdo, enquanto "contentOnly" permite explicitamente essa edição.

Quando usar: a opção mais comum para páginas voltadas aos clientes. O desenvolvedor controla o layout. O cliente preenche o texto.

false

JSON
{
  "name": "blog",
  "templateLock": false
}

Sem nenhum bloqueio. Os clientes têm controle total: podem adicionar, remover, mover e editar qualquer bloco. O modelo oferece uma estrutura inicial, mas, a partir daí, a página fica a cargo do cliente.

Quando usar: páginas de índice do blog, páginas de conteúdo livre ou qualquer página em que o cliente deva ter plena liberdade editorial.

Modo de edição de blocos

Enquanto templateLock controla a estrutura (adicionar, remover, mover), blockEditingMode controla a interação em cada bloco: se os blocos podem ser selecionados, configurados ou editados.

Defina um padrão para a página em page.json:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

"default"

Edição completa. Os blocos podem ser selecionados, suas configurações podem ser alteradas e o conteúdo pode ser editado. Essa é a experiência normal do editor.

"contentOnly"

Os blocos podem ser editados, mas somente quanto ao conteúdo textual. Não é possível abrir as configurações do bloco, mudar cores, ajustar o preenchimento nem modificar atributos que não sejam de conteúdo. A barra de ferramentas do bloco mostra apenas opções de formatação de texto.

"disabled"

Os blocos são completamente não interativos. Eles aparecem no editor, mas não podem ser clicados, selecionados nem modificados de nenhuma forma. O cliente vê o conteúdo, mas não pode interagir com ele.

Substituições por elemento

É aqui que as coisas ficam interessantes. O blockEditingMode da página define um padrão para todos os blocos da página, mas você pode substituí-lo em elementos individuais do modelo:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Heading</h1>
  <p blockEditingMode="contentOnly">Edit this paragraph too.</p>
</block>

<div>
  <h2>Features</h2>
  <p>This paragraph cannot be edited (inherits "disabled").</p>
  <p blockEditingMode="contentOnly">But this one can.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">This button is frozen</block>
</block>

O padrão da página é "disabled", então todos os blocos começam como não interativos. Depois, elementos específicos optam por "contentOnly", tornando editável apenas o texto deles. O resultado: uma página em que o cliente pode digitar exatamente em dois campos de texto (o título principal e o parágrafo) e em um parágrafo de recurso. Todo o resto fica bloqueado.

Isso funciona com qualquer elemento HTML (<h1>, <p>, <div> etc.) e com elementos <block>. Você também pode definir blockEditingMode="default" em elementos específicos para dar acesso à edição completa:

HTML
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>

Agora o cliente pode alterar o texto do botão, URL, os estilos e qualquer outra configuração. Todo o restante da página continua congelado.

Cascata de ancestrais

Há um detalhe importante sobre como as substituições por elemento interagem com blocos contêineres. Se o padrão da página for "disabled" e você definir blockEditingMode="contentOnly" em um título dentro de um grupo, será necessário conseguir acessar esse título. Mas o grupo pai está em "disabled", o que significa que não é possível acessá-lo.

Blockstudio trata disso automaticamente. Quando um bloco filho tem uma substituição do modo de edição, todos os blocos ancestrais dele são definidos como "contentOnly" para que o filho continue acessível. Não é necessário definir manualmente os modos nos contêineres pai. Basta definir a substituição no bloco que você quer tornar editável; o caminho até ele será aberto.

HTML
<!-- page default: "disabled" -->
<div>
  <!-- this group is auto-set to "contentOnly" because it contains an override -->
  <div>
    <!-- this group is also auto-set to "contentOnly" -->
    <p blockEditingMode="contentOnly">Deeply nested but still editable.</p>
  </div>
</div>

A cascata de ancestrais só eleva os contêineres para "contentOnly", nunca para "default". Isso significa que os grupos ancestrais ficam navegáveis (é possível acessá-los), mas não totalmente editáveis (não é possível alterar suas configurações).

Matriz de decisões

A combinação de templateLock e blockEditingMode oferece diferentes níveis de controle. Veja algumas das combinações mais úteis:

O desenvolvedor controla tudo

JSON
{ "templateLock": "all" }

Não é necessário usar blockEditingMode. O padrão templateLock: "all" impede todas as alterações. Use essa opção para páginas gerenciadas inteiramente por código.

O cliente edita todo o texto

JSON
{ "templateLock": "contentOnly" }

O cliente pode editar o texto de qualquer bloco, mas não pode alterar a estrutura da página. Simples e permissivo.

O cliente edita apenas textos específicos

JSON
{
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

Combinado com blockEditingMode="contentOnly" em elementos específicos do modelo. Essa é a opção mais precisa: o cliente só pode editar exatamente os blocos que você marcar.

O cliente reordena seções fixas

JSON
{ "templateLock": "insert" }

O cliente pode reorganizar as seções e editar o conteúdo, mas não pode adicionar nem excluir blocos. Uma boa opção para páginas com um conjunto fixo de seções em uma ordem flexível.

O cliente tem controle total

JSON
{ "templateLock": false }

O modelo é um ponto de partida. A partir daí, o cliente pode fazer qualquer coisa.

Preservação das edições do cliente

Por padrão, quando você atualiza um arquivo de modelo, Blockstudio substitui todo o conteúdo da página. Se o cliente editou um título no editor, essa edição desaparece na próxima sincronização. Isso funciona bem para páginas controladas pelo desenvolvedor, mas, nas páginas com conteúdo fornecido pelos clientes, é preciso preservar o trabalho deles.

Chaves

Adicione um atributo key a qualquer elemento para mesclá-lo em vez de substituí-lo:

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

<div key="features">
  <h2>Features</h2>
  <p>Feature introduction text.</p>
</div>

<div>
  <h2>Unkeyed Section</h2>
  <p>This gets replaced on every sync.</p>
</div>

Quando o modelo mudar e a página for sincronizada novamente:

  • Blocos com chave preservam o conteúdo do cliente (texto, blocos internos, formatação). Os atributos estruturais do modelo (como o url da capa) continuam sendo atualizados.
  • Blocos sem chave são substituídos integralmente pela versão do modelo.

Uma chave protege o bloco inteiro e todos os seus filhos. Não é necessário atribuir chaves a parágrafos individuais dentro de um grupo com chave. A chave do grupo protege tudo o que está dentro dele.

As chaves devem ser exclusivas

As chaves devem ser exclusivas em todo o modelo. Se dois elementos compartilharem a mesma chave, o segundo será tratado como se não tivesse chave (e será emitido um aviso PHP). Use nomes descritivos: "hero", "features", "cta", "testimonial-section".

Evolução dos modelos

As chaves permitem adicionar novas seções a um modelo sem afetar o conteúdo existente do cliente:

HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
<div key="testimonials">
  <h2>What Clients Say</h2>
  <p>Default testimonial text.</p>
</div>

Na sincronização, o título e os serviços preservam as edições do cliente. A nova seção de depoimentos aparece com o conteúdo padrão do modelo. Se mais tarde você remover do modelo um bloco com chave, ele será excluído da página.

Fluxo de trabalho completo do cliente

Veja como reunir tudo isso em um projeto real:

JSON
{
  "name": "homepage",
  "title": "Home",
  "slug": "home",
  "postStatus": "publish",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Your Company Name</h1>
  <p blockEditingMode="contentOnly">Your tagline goes here.</p>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Contact Us</block>
  </block>
</block>

<div key="features">
  <h2 blockEditingMode="contentOnly">What We Do</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service One</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Two</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Three</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
  </block>
</div>

<block name="core/media-text" key="about" mediaurl="https://example.com/team.jpg" mediatype="image">
  <h2 blockEditingMode="contentOnly">About Us</h2>
  <p blockEditingMode="contentOnly">Tell your story here.</p>
</block>

<div key="cta">
  <h2 blockEditingMode="contentOnly">Ready to get started?</h2>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Get in Touch</block>
  </block>
</div>

Esta página tem quatro seções com chave. O cliente pode editar títulos e parágrafos marcados com blockEditingMode="contentOnly", e essas edições são preservadas nas atualizações do modelo. O desenvolvedor controla o layout, as imagens, os URLs dos botões e a estrutura geral. Se mais tarde o desenvolvedor adicionar uma seção de depoimentos entre “about” e “cta”, ela aparecerá na próxima sincronização sem afetar nenhum dos textos do cliente.

Vinculações de blocos: uma alternativa às chaves

WordPress 6.5 introduziu o Vinculações de blocos API, que conecta atributos de blocos aos metadados do post. Em vez de armazenar o conteúdo editável na marcação do bloco (onde as chaves o protegem), o conteúdo fica em wp_postmeta (onde a sincronização do modelo não pode alterá-lo).

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.
</p>

As chaves de metadados devem ser registradas em PHP:

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

As vinculações de blocos têm duas vantagens em relação às chaves: os dados podem ser consultados com WP_Query por meio de meta_query e ficam disponíveis no REST API. A desvantagem é que é preciso registrar cada chave de metadados em PHP, e as vinculações só funcionam com atributos individuais de blocos (não com conteúdo aninhado complexo).

Use chaves para seções de conteúdo rico em que a estrutura dos blocos seja importante (um grupo com títulos, parágrafos e imagens). Use vinculações para valores de texto individuais que você também precise consultar ou exibir em outro lugar.

Modelos de tipo de publicação

Use templateFor para definir uma estrutura padrão de blocos para todos os novos posts de um determinado tipo:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}
HTML
<h1>Product Name</h1>

<block name="core/columns">
  <block name="core/column">
    <img src="" alt="Product image" />
  </block>
  <block name="core/column">
    <p>Product description goes here.</p>
    <block name="core/buttons">
      <block name="core/button" url="#">Buy Now</block>
    </block>
  </block>
</block>

<div>
  <h2>Specifications</h2>
  <table>
    <thead>
      <tr><th>Feature</th><th>Value</th></tr>
    </thead>
    <tbody>
      <tr><td>Weight</td><td>1.2 kg</td></tr>
    </tbody>
  </table>
</div>

Todo novo post do tipo “product” começa com essa estrutura. O templateLock: "insert" permite que os editores reorganizem as seções e editem o conteúdo, mas não adicionem nem removam blocos.

Dicas

Sincronize em um limite de implantação definido intencionalmente. Execute wp bs pages sync depois de alterar ou implantar as fontes das páginas. As visitas ao frontend e ao painel de administração nunca sincronizam páginas. As ferramentas de implantação PHP podem chamar Blockstudio\Pages::reconcile() e inspecionar o relatório legível por máquina.

Fixe os IDs de posts importantes. Use postId em page.json para páginas referenciadas por menus, links codificados diretamente ou sistemas externos. Sem fixar o ID, uma página excluída e recriada recebe um novo ID, quebrando essas referências.

Use sync: false para estruturas iniciais. Se quiser criar uma página uma vez e depois entregá-la inteiramente ao cliente, defina "sync": false e crie-a com Blockstudio\Pages::force_sync(). A reconciliação normal passará a ignorá-la.

Bloqueie e desbloqueie por meio de PHP. Chame Blockstudio\Pages::lock('about') para impedir a sincronização de uma página específica (útil durante períodos intensivos de edição do cliente). Chame Blockstudio\Pages::unlock('about') para reativar a sincronização.

Mecanismos de modelos. Além de PHP, os modelos podem ser escritos em Twig (requer Timber) ou Blade (requer illuminate/view). Isso é útil para loops e filtros, mas os modelos de página são compilados durante a sincronização explícita, não durante a solicitação do frontend. Use PHP se a compilação da fonte precisar de auxiliares exclusivos do PHP.

A sincronização forçada ignora as chaves. Chamar Pages::force_sync('about') substitui todo o conteúdo da página, ignorando as chaves e as verificações do horário de modificação. Use essa opção quando quiser intencionalmente restaurar a página ao estado do modelo.

Próximas etapas

  • Referência de páginas: todas as propriedades page.json, o PHP API e o algoritmo de mesclagem por chave em detalhes.
  • Visão geral de páginas e padrões: o analisador HTML, a referência de sintaxe de blocos, os renderizadores personalizados e o mapeamento de elementos.
  • Padrões: a mesma sintaxe de modelo para padrões de blocos reutilizáveis em vez de páginas.