Saltar al contenido

InnerBlocks

Los bloques internos te permiten insertar bloques adicionales dentro de tus bloques. En segundo plano, Blockstudio usa el componente InnerBlocks. Ten en cuenta que solo se puede usar un componente InnerBlocks por bloque; se trata de una limitación de WordPress.

Uso básico

Para usar InnerBlocks, añade el componente <InnerBlocks /> a la plantilla del bloque:

PHP
<InnerBlocks />

La composición depende de ti. Puedes anidar el componente InnerBlocks tanto como quieras o usarlo por sí solo.

Propiedades

allowedBlocks

La propiedad allowedBlocks permite definir qué bloques se pueden insertar en el 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 también acepta tokens expandidos en el servidor. Los tokens se expanden antes de que el editor reciba la plantilla, mientras que los nombres literales de bloques no cambian.

Token Descripción
namespace/* Todos los bloques registrados en ese espacio de nombres
category:<slug> Todos los bloques registrados de esa categoría de bloques WordPress
@theme Todos los bloques Blockstudio registrados desde el tema activo

Las entradas expandidas se deduplican en el orden del autor:

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

Se ignoran los tokens que no corresponden a ningún bloque. El resultado de la interfaz pública no cambia, porque allowedBlocks solo se usa en el editor.

Etiqueta

De forma predeterminada, el componente InnerBlocks se renderiza como un elemento div. Puedes cambiarlo mediante la propiedad tag.

PHP
<InnerBlocks tag="section" />

Plantilla

La propiedad template permite definir una plantilla para el 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

La propiedad templateLock permite definir si se puede modificar la plantilla o no.

Valor Descripción
contentOnly Impide todas las operaciones. Los tipos de bloque sin contenido se ocultan de la vista de lista. Los bloques secundarios no pueden anularlo.
all Impide todas las operaciones. No se pueden insertar, mover ni eliminar bloques.
insert Impide insertar o eliminar bloques, pero permite mover los existentes.
false Impide aplicar el bloqueo, aunque un bloque principal lo incluya.

renderAppender

La propiedad renderAppender permite definir el tipo de insertador de bloques.

Valor Descripción
default Mostrar el insertador de bloques predeterminado (insertador con estilo de párrafo cuando se permite el bloque de párrafo)
button Mostrar un botón con el icono + como insertador

useBlockProps

useBlockProps eliminará el contenedor externo del componente InnerBlocks dentro del editor. Consulta useBlockProps para obtener más información.

Contexto

Registro

Blockstudio admite contexto para el componente InnerBlocks. Esto permite pasar datos del bloque principal a los bloques secundarios. Aunque utiliza internamente el mecanismo de contexto principal de WordPress, Blockstudio ofrece una API más cómoda.

En lugar de tener que definir por separado todos los atributos que deben pasarse en el contexto, puedes suscribirte simplemente a todos los atributos de un bloque principal.

Cada bloque secundario recibe los valores de su propio bloque principal, incluso en la primera renderización precargada del editor. Al actualizar los campos de un proveedor, se actualizan sus bloques secundarios en el editor, aunque siga cargándose una renderización anterior. Los bloques secundarios idénticos bajo distintos proveedores mantienen renderizaciones en caché independientes y sensibles al contexto.

Supongamos que tienes un bloque contenedor configurado así:

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 del bloque secundario, usa simplemente la propiedad usesContext con el nombre del bloque principal para acceder a todos los atributos del bloque principal en la plantilla de tu bloque.

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
}

Plantillas

Las variables $context y $c están disponibles dentro de las plantillas de bloque para acceder a todos los atributos del bloque principal. Los bloques secundarios se volverán a cargar automáticamente en el editor si cambian los datos del bloque principal.

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>

Contenedor del frontend

InnerBlocks debe renderizar un elemento contenedor alrededor de sus bloques secundarios dentro del editor; sin embargo, puede eliminarse del frontend mediante el 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 anticipado

Si quieres salir antes del método render de tu bloque, puedes comprobar si la variable $innerBlocks está vacía. Esto resulta útil si no quieres renderizar nada cuando no hay bloques internos.

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

Como <InnerBlocks/> siempre renderiza una etiqueta de párrafo vacía, puedes usar la función strip_tags para comprobar si el contenido está vacío.

Plantillas dinámicas

Los tipos de campo Select y Radio permiten generar dinámicamente la plantilla InnerBlocks según el valor del campo. Esto resulta útil si quieres permitir que el usuario seleccione una plantilla distinta para el componente InnerBlocks.

Para hacerlo, añade simplemente una clave innerBlocks a la matriz de opciones con la plantilla:

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 y comunicación entre bloques

Descubre cómo comparten datos los bloques principales y secundarios mediante el contexto.