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:
<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
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode(['core/heading', 'core/paragraph'])); ?>" />
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:
<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.
<InnerBlocks tag="section" />
template
A propriedade template permite definir um template para o componente InnerBlocks.
PHP
<InnerBlocks template="<?php echo esc_attr(wp_json_encode([
['core/heading', ['placeholder' => 'Book Title']],
['core/paragraph', ['placeholder' => 'Summary']]
])); ?>" />
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:
{
"$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.
{
"$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 $container = $context['blockstudio/container']; ?>
<h1>
<?php echo $container['full-width']
? 'is full width'
: 'no full width'; ?>
</h1>
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.
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 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:
{
"$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.