Páginas e padrões
Blockstudio permite definir páginas WordPress, padrões de blocos e modelos do Editor do site como arquivos no seu tema. Escreva modelos no estilo HTML, e o analisador de Blockstudio os converte em blocos nativos de WordPress.
- Páginas são sincronizadas com o banco de dados como publicações WordPress, mantendo os modelos de arquivo e o conteúdo das páginas sincronizados.
- Padrões são registrados na memória por meio de
register_block_pattern()e ficam disponíveis no inseridor de blocos para que os usuários os coloquem onde quiserem. - Modelos do site fornecem fontes
wp_templateewp_template_partbaseadas em arquivos para o Editor do site WordPress.
Os três recursos compartilham o mesmo analisador HTML e a mesma sintaxe de blocos.
Criação de páginas baseadas em arquivos
Um guia prático sobre modelos de páginas baseados em arquivos, sincronização e bloqueio.
Estrutura de pastas
theme/
├── pages/
│ ├── about/
│ │ ├── page.json
│ │ └── index.php
│ └── contact/
│ ├── page.json
│ └── index.twig
├── patterns/
├── hero/
│ ├── pattern.json
│ └── index.php
└── cta/
├── pattern.json
└── index.blade.php
├── templates/
└── front-page/
├── template.json
└── index.php
└── parts/
└── header/
├── part.json
└── index.php
Cada subpasta contém um arquivo de configuração JSON (page.json, pattern.json, template.json ou part.json) e um arquivo de modelo.
Mecanismos de modelo
Os modelos podem ser escritos como marcação simples em index.php ou em Twig ou Blade:
| Arquivo | Mecanismo | Requisito |
|---|---|---|
index.php |
Nenhum (lido como está; o código PHP não é executado) | Nenhum |
index.twig |
Twig | Timber |
index.blade.php |
Blade | illuminate/view |
Se houver vários arquivos de modelo, a ordem de prioridade é: index.php > index.blade.php > index.twig.
Como os modelos são compilados no momento da inicialização (antes de qualquer contexto de solicitação), os modelos Twig e Blade não têm acesso a variáveis dinâmicas. Eles são úteis para funções e filtros integrados, como {{ "text"|upper }} ou {{ strtoupper("text") }}.
Mapeamento de HTML para blocos
Elementos padrão de HTML são convertidos automaticamente nos blocos WordPress correspondentes.
Texto
| HTML | Bloco |
|---|---|
<p> |
core/paragraph |
<h1> – <h6> |
core/heading |
<ul> |
core/list (não ordenada) |
<ol> |
core/list (ordenada) |
<li> |
core/list-item |
<blockquote> |
core/quote |
<code> |
core/code |
<pre> |
core/preformatted |
As listas mantêm sua estrutura. Um <ul> ou <ol> dentro de um <li> se torna um bloco interno core/list desse core/list-item, que é a estrutura salva pelo editor; assim, as listas podem ser aninhadas em qualquer profundidade. Um class em uma lista ou item se torna seu className, que é como um estilo de bloco, como is-style-checks, é definido a partir de um arquivo de página; <block name="core/list" className="..."> faz o mesmo.
Mídia
| HTML | Bloco |
|---|---|
<img> |
core/image |
<figure> |
core/image (com legenda) |
<audio> |
core/audio |
<video> |
core/video |
Layout
| HTML | Bloco |
|---|---|
<div>, <section> |
core/group |
<main>, <header>, <footer>, <article>, <aside> |
core/group que mantém o elemento como seu tagName |
<hr> |
core/separator |
<details> |
core/details |
<table> |
core/table |
Sintaxe dos blocos
Para blocos sem um equivalente direto em HTML, use o elemento <block>:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
Blocos principais
<!-- Pullquote -->
<block name="core/pullquote">
<p>An important quote.</p>
</block>
<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>
<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
<h2>Cover Title</h2>
</block>
<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />
<!-- Spacer -->
<block name="core/spacer" height="50px" />
<!-- Gallery -->
<block name="core/gallery">
<img src="https://example.com/1.jpg" alt="Image 1" />
<img src="https://example.com/2.jpg" alt="Image 2" />
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<h3>Column 1</h3>
</block>
<block name="core/column">
<h3>Column 2</h3>
</block>
</block>
<!-- Buttons -->
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
</block>
<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Item 1</p>
<p>Item 2</p>
</block>
Blocos personalizados
A mesma sintaxe funciona com qualquer bloco registrado:
<block name="blockstudio/section">
<h1>Welcome</h1>
</block>
<block name="acf/hero" title="Hero Title" background="dark">
<p>Inner content becomes InnerBlocks.</p>
</block>
Atributos
Os atributos HTML em elementos <block> são passados como atributos do bloco. Valores JSON são compatíveis:
<block name="core/heading" level="3">Custom Heading</block>
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked content.</p>
</block>
<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />
Os valores dos atributos são decodificados uma vez, como um navegador os lê, então
data-animate="[&>span]:fade" e data-animate="[&>span]:fade" armazenam o
mesmo valor.
Em um elemento mapeado para um bloco Blockstudio, todos os atributos são armazenados com o bloco. Os campos declarados chegam ao template; os atributos globais que o bloco não declara (id, style, role, title, lang, dir, hidden, tabindex, aria-* e data-*) são colocados no elemento raiz do bloco ao renderizar, exatamente como nas tags de bloco. Em fontes de páginas e padrões, um prefixo html- só pode indicar um desses atributos globais: html-role="note" é encaminhado como role, enquanto manipuladores de eventos como html-onclick nunca são renderizados. Todo o restante, incluindo uma class não declarada, permanece no conteúdo do post sem chegar à página, e wp bs pages sync informa isso para cada página que analisa.
Renderizadores de blocos personalizados
O analisador HTML usa uma arquitetura baseada em registros. Adicione um construtor para um bloco personalizado com blockstudio/block_tags/builders:
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
$builders['acf/hero'] = function( array $attrs, string $inner_content ) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );
return array(
'blockName' => 'acf/hero',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '',
'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
);
};
return $builders;
}, 10, 2 );
Depois, use-o em qualquer modelo:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
Você também pode substituir a forma como os blocos principais são renderizados:
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
$renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
$content = trim( $inner_content );
$attrs['align'] = $attrs['align'] ?? 'center';
return array(
'blockName' => 'core/paragraph',
'attrs' => $attrs,
'innerBlocks' => array(),
'innerHTML' => '<p class="has-text-align-center">' . $content . '</p>',
'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
);
};
return $renderers;
}, 10, 2 );
Os callbacks do construtor recebem os atributos analisados e o conteúdo interno bruto. Eles devem retornar um array de blocos WordPress. Consulte Renderizadores personalizados para ver a ordem completa dos filtros e um exemplo de contêiner.
Assinatura da função construtora
/**
* @param array $attrs Parsed element or block-tag attributes.
* @param string $inner_content Raw inner content.
* @return array WordPress block array.
*/
function my_builder( array $attrs, string $inner_content ): array {}
Mapeamento de elementos
Por padrão, elementos HTML comuns, como <h1>, <p> e <img>, são mapeados para blocos principais de WordPress. Você pode substituir esse mapeamento para direcionar qualquer elemento HTML a um bloco diferente usando o filtro blockstudio/parser/element_mapping:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['h1'] = 'custom/heading';
$mapping['h2'] = 'custom/heading';
$mapping['p'] = 'custom/paragraph';
$mapping['img'] = 'custom/image';
return $mapping;
}, 10, 2 );
Com esse filtro ativo, cada <h1> nos seus modelos produzirá um bloco custom/heading em vez de core/heading. Os atributos do elemento são passados ao bloco de destino. Se houver um renderizador registrado para o nome do bloco de destino, ele será usado. Caso contrário, será criada uma estrutura genérica de bloco.
Isso é útil quando seu tema ou plugin fornece tipos de bloco personalizados que devem substituir os padrões em todos os modelos de páginas e padrões.
Para mapeamentos simples de <p>, Blockstudio pode encaminhar o conteúdo interno de HTML diretamente para o atributo richtext content de um bloco Blockstudio registrado que não pertença ao núcleo. O bloco de destino deve declarar um atributo com id: "content" e type: "richtext".
A formatação em linha (a, b, br, code, del, em, i, img, ins,
mark, s, small, span, strong, sub, sup, u) permanece no valor encaminhado mesmo quando a mesma tag é mapeada como elemento, como ocorre por padrão com code e img. Um parágrafo cujo único filho é uma imagem se torna o bloco para o qual <img> mapeia, que é o que Markdown produz para uma imagem independente. Tags de blocos aninhadas e HTML em nível de bloco continuam sendo analisadas como blocos internos.
Os valores de mapeamento também podem ser funções quando o bloco de destino depende dos atributos do elemento:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['div'] = function( array $attrs ) {
if ( isset( $attrs['width'] ) ) {
return 'theme/row';
}
if ( isset( $attrs['gap'] ) ) {
return 'theme/flow';
}
return 'theme/div';
};
return $mapping;
} );
Blocos personalizados mapeados a partir de elementos contêiner, como <section> e <div>, analisam recursivamente os elementos HTML aninhados, de modo que títulos, imagens, tags de bloco e parágrafos internos se tornam blocos filhos nativos.
Exemplo completo
Um modelo completo de página que combina vários tipos de bloco:
<div>
<h1>Welcome to Our Site</h1>
<p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>
<block name="core/columns">
<block name="core/column">
<h3>Feature One</h3>
<p>First feature description.</p>
</block>
<block name="core/column">
<h3>Feature Two</h3>
<p>Second feature description.</p>
</block>
</block>
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Our Mission</h2>
<p>Building amazing things together.</p>
</block>
<details>
<summary>FAQ</summary>
<p>Answers to common questions.</p>
</details>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
<block name="core/button" url="/learn-more">Learn More</block>
</block>
</div>