Pular para o conteúdo

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_template e wp_template_part baseadas 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

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

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1>Welcome</h1>
  <p>Content inside the cover block.</p>
</block>

Blocos principais

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

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

HTML
<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="[&amp;>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:

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

HTML
<block name="acf/hero" background="dark">
  <h1>Welcome</h1>
</block>

Você também pode substituir a forma como os blocos principais são renderizados:

PHP
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

PHP
/**
 * @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:

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

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

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