Pular para o conteúdo

InnerBlocks

Os blocos internos permitem inserir blocos adicionais nos seus blocos. Nos bastidores, Blockstudio usa o componente InnerBlocks. Observe que só é possível usar um componente InnerBlocks por bloco; essa é uma limitação do WordPress.

Uso básico

Para usar InnerBlocks, adicione o componente <InnerBlocks /> ao template do seu bloco:

PHP
<InnerBlocks />

A composição fica a seu critério. Você pode aninhar o componente InnerBlocks em quantos níveis quiser ou usá-lo sozinho.

Propriedades

allowedBlocks

A propriedade allowedBlocks permite definir quais blocos podem ser inseridos no componente InnerBlocks.

PHP

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode(['core/heading', 'core/paragraph'])); ?>" />

Twig

Twig
<InnerBlocks allowedBlocks="{{ ['core/heading', 'core/paragraph']|json_encode|escape('html_attr') }}" />

allowedBlocks também aceita tokens expandidos no servidor. Os tokens são expandidos antes que o editor receba o template, enquanto os nomes literais dos blocos permanecem inalterados.

Token Descrição
namespace/* Todos os blocos registrados nesse namespace
category:<slug> Todos os blocos registrados nessa categoria de blocos WordPress
@theme Todos os blocos Blockstudio registrados pelo tema ativo

As entradas expandidas são deduplicadas na ordem do autor:

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
  'core/paragraph',
  'category:content',
  'bsui/field',
])); ?>" />

Tokens que não correspondem a nenhum bloco são ignorados. A saída do frontend não muda, porque allowedBlocks só é usado pelo editor.

tag

Por padrão, o componente InnerBlocks é renderizado como um elemento div. Você pode alterar isso usando a propriedade tag.

PHP
<InnerBlocks tag="section" />

template

A propriedade template permite definir um template para o componente InnerBlocks.

PHP

PHP
<InnerBlocks template="<?php echo esc_attr(wp_json_encode([
  ['core/heading', ['placeholder' => 'Book Title']],
  ['core/paragraph', ['placeholder' => 'Summary']]
])); ?>" />

Twig

Twig
<InnerBlocks template="{{ [
  ['core/heading', { placeholder: 'Book Title' }],
  ['core/paragraph', { placeholder: 'Summary' }]
]|json_encode|escape('html_attr') }}" />

templateLock

A propriedade templateLock permite definir se o template pode ou não ser modificado.

Valor Descrição
contentOnly Impede todas as operações. Tipos de bloco sem conteúdo ficam ocultos na visualização em lista. Não pode ser substituído por blocos filhos.
all Impede todas as operações. Não é possível inserir, mover ou excluir blocos.
insert Impede a inserção ou remoção de blocos, mas permite mover os existentes.
false Impede a aplicação de bloqueios, mesmo que um bloco pai contenha um bloqueio.

renderAppender

A propriedade renderAppender permite definir o tipo de adicionador de blocos.

Valor Descrição
default Exibe o inseridor padrão de blocos (inseridor no estilo de parágrafo quando o bloco de parágrafo é permitido)
button Exibe um botão com ícone de + como inseridor

useBlockProps

useBlockProps removerá o wrapper externo do componente InnerBlocks dentro do editor. Consulte useBlockProps para mais informações.

Contexto

Registro

Blockstudio oferece suporte a context para o componente InnerBlocks. Isso permite passar dados do bloco pai para os blocos filhos. Embora use o mecanismo de contexto principal WordPress nos bastidores, Blockstudio oferece um API mais conveniente.

Em vez de definir separadamente todos os atributos que devem ser passados no contexto, você pode simplesmente assinar todos os atributos de um bloco pai.

Cada filho recebe os valores de seu próprio pai, inclusive na primeira renderização pré-carregada do editor. Atualizar os campos de um provedor atualiza seus filhos no editor, mesmo enquanto uma renderização anterior ainda está sendo carregada. Blocos filhos idênticos sob provedores diferentes mantêm renderizações em cache separadas e cientes do contexto.

Digamos que você tenha uma configuração de bloco contêiner como esta:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/container",
  "title": "Container",
  "category": "design",
  "icon": "star-filled",
  "description": "Container block.",
  "blockstudio": {
    "attributes": [
      {
        "id": "full-width",
        "type": "toggle",
        "label": "Makes section full width"
      }
    ]
  }
}

Dentro do bloco filho, basta usar a propriedade usesContext com o nome do bloco pai para acessar todos os atributos do pai no modelo do seu bloco.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/element",
  "title": "Element",
  "category": "design",
  "icon": "star-filled",
  "description": "Element block.",
  "usesContext": ["blockstudio/container"],
  "parent": ["blockstudio/container"],
  "blockstudio": true
}

Modelos

As variáveis $context e $c estão disponíveis nos modelos dos seus blocos para acessar todos os atributos do pai. Os blocos filhos serão recarregados automaticamente no editor se os dados do pai mudarem.

PHP

PHP
<?php $container = $context['blockstudio/container']; ?>

<h1>
  <?php echo $container['full-width']
      ? 'is full width'
      : 'no full width'; ?>
</h1>

Twig

Twig
{% set container = context['blockstudio/container'] %}

<h1>
  {{ container['full-width']
      ? 'is full width'
      : 'no full width' }}
</h1>

Wrapper do frontend

InnerBlocks precisa renderizar um elemento wrapper em torno dos filhos dentro do editor; no entanto, ele pode ser removido do frontend usando o filtro blockstudio/blocks/components/inner_blocks/frontend/wrap.

PHP
add_filter('blockstudio/blocks/components/inner_blocks/frontend/wrap', function($wrap, $block) {
  return false; // Remove wrapper
}, 10, 2);

Retorno antecipado

Se quiser retornar antecipadamente do método render do seu bloco, você pode verificar se a variável $innerBlocks está vazia. Isso é útil se você não quiser renderizar nada quando não houver blocos internos.

PHP
<?php if (strip_tags($innerBlocks) === '') {
  return;
} ?>
<InnerBlocks tag="section" />

Como <InnerBlocks/> sempre renderiza uma tag de parágrafo vazia, você pode usar a função strip_tags para verificar se o conteúdo está vazio.

Modelos dinâmicos

Os tipos de campo Seleção e Botão de opção permitem gerar dinamicamente o modelo InnerBlocks dependendo do valor do campo. Isso é útil se você quiser permitir que o usuário selecione um modelo diferente para o componente InnerBlocks.

Para isso, basta adicionar uma chave innerBlocks ao array de opções com o modelo:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/dynamic-layout",
  "title": "Dynamic Layout",
  "blockstudio": {
    "attributes": [
      {
        "id": "layout",
        "type": "select",
        "label": "Layout",
        "options": [
          {
            "value": "1",
            "label": "Two Columns",
            "innerBlocks": [
              {
                "name": "core/columns",
                "innerBlocks": [
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "Left Heading",
                          "level": 1
                        }
                      }
                    ]
                  },
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "Right Heading",
                          "level": 1
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "value": "2",
            "label": "Single Column",
            "innerBlocks": [
              {
                "name": "core/heading",
                "attributes": {
                  "content": "Main Heading",
                  "level": 1
                }
              },
              {
                "name": "core/paragraph",
                "attributes": {
                  "content": "Main content goes here."
                }
              }
            ]
          }
        ],
        "allowNull": "Select a layout"
      }
    ]
  }
}

Contexto e comunicação entre blocos

Saiba como os blocos pai e filho compartilham dados usando contexto.