Zum Inhalt springen

InnerBlocks

Mit inneren Blöcken kannst du weitere Blöcke in deine Blöcke einfügen. Im Hintergrund verwendet Blockstudio die Komponente InnerBlocks. Beachte, dass pro Block nur eine InnerBlocks-Komponente verwendet werden kann. Das ist eine Einschränkung von WordPress.

Grundlegende Verwendung

Um InnerBlocks zu verwenden, füge die Komponente <InnerBlocks /> zu deiner Blockvorlage hinzu:

PHP
<InnerBlocks />

Wie du sie zusammensetzt, bleibt dir überlassen. Du kannst die Komponente InnerBlocks beliebig tief verschachteln oder sie einfach allein verwenden.

Eigenschaften

allowedBlocks

Mit der Prop allowedBlocks legst du fest, welche Blöcke in die Komponente InnerBlocks eingefügt werden können.

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 akzeptiert auch serverseitig erweiterte Tokens. Diese werden erweitert, bevor der Editor die Vorlage erhält; wörtliche Blocknamen bleiben unverändert.

Token Beschreibung
namespace/* Jeder registrierte Block in diesem Namespace
category:<slug> Jeder registrierte Block in dieser WordPress-Blockkategorie
@theme Jeder Blockstudio-Block, der im aktiven Theme registriert ist

Erweiterte Einträge werden in der Reihenfolge des Autors dedupliziert:

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

Tokens, die keinem Block entsprechen, werden ignoriert. Die Frontend-Ausgabe bleibt unverändert, da allowedBlocks nur im Editor verwendet wird.

tag

Standardmäßig wird die Komponente InnerBlocks als Element div gerendert. Mit der Prop tag kannst du das ändern.

PHP
<InnerBlocks tag="section" />

template

Mit der Prop template kannst du eine Vorlage für die Komponente InnerBlocks festlegen.

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

Mit der Prop templateLock kannst du festlegen, ob die Vorlage geändert werden kann.

Wert Beschreibung
contentOnly Verhindert alle Vorgänge. Blocktypen ohne Inhalt sind in der Listenansicht ausgeblendet. Für untergeordnete Blöcke nicht überschreibbar.
all Verhindert alle Vorgänge. Blöcke können nicht eingefügt, verschoben oder gelöscht werden.
insert Verhindert das Einfügen oder Entfernen von Blöcken, erlaubt aber das Verschieben vorhandener Blöcke.
false Verhindert die Anwendung einer Sperre, selbst wenn ein übergeordneter Block eine Sperre enthält.

renderAppender

Mit der Prop renderAppender kannst du den Typ des Block-Appenders festlegen.

Wert Beschreibung
default Zeigt den Standard-Block-Appender an (einen Appender im Absatzstil, wenn der Absatzblock zulässig ist)
button Zeigt ein Plus-Symbol als Appender-Schaltfläche an

useBlockProps

useBlockProps entfernt den äußeren Wrapper der Komponente InnerBlocks im Editor. Weitere Informationen findest du unter useBlockProps.

Kontext

Registrieren

Blockstudio unterstützt Kontext für die Komponente InnerBlocks. Damit kannst du Daten vom übergeordneten Block an untergeordnete Blöcke weitergeben. Im Hintergrund wird der WordPress-Kernmechanismus für Kontext verwendet; Blockstudio bietet jedoch eine bequemere API.

Anstatt alle Attribute, die im Kontext übergeben werden sollen, einzeln festzulegen, kannst du einfach alle Attribute eines übergeordneten Blocks abonnieren.

Jeder untergeordnete Block erhält die Werte seines eigenen übergeordneten Blocks, auch beim ersten vorab geladenen Rendering des Editors. Änderungen an den Feldern eines Anbieters aktualisieren seine untergeordneten Blöcke im Editor, selbst wenn ein vorheriges Rendering noch geladen wird. Identische untergeordnete Blöcke unter verschiedenen Anbietern behalten separate, kontextabhängige gecachte Renderings.

Angenommen, du hast einen Container-Block wie diesen eingerichtet:

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"
      }
    ]
  }
}

Verwende in deinem untergeordneten Block einfach die Eigenschaft usesContext mit dem Namen des übergeordneten Blocks, um in deiner Blockvorlage auf alle Attribute des übergeordneten Blocks zuzugreifen.

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
}

Vorlagen

Die Variablen $context und $c sind in deinen Blockvorlagen verfügbar, um auf alle Attribute des übergeordneten Blocks zuzugreifen. Ändern sich die Daten des übergeordneten Blocks, werden untergeordnete Blöcke im Editor automatisch neu geladen.

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>

Frontend-Wrapper

InnerBlocks muss im Editor ein Wrapper-Element um seine untergeordneten Elemente rendern. Im Frontend kannst du es jedoch mit dem Filter blockstudio/blocks/components/inner_blocks/frontend/wrap entfernen.

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

Vorzeitig zurückkehren

Wenn du vorzeitig aus der Methode render deines Blocks zurückkehren möchtest, kannst du prüfen, ob die Variable $innerBlocks leer ist. Das ist hilfreich, wenn du nichts rendern möchtest, sofern keine inneren Blöcke vorhanden sind.

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

Da <InnerBlocks/> immer ein leeres Absatz-Tag rendert, kannst du mit der Funktion strip_tags prüfen, ob der Inhalt leer ist.

Dynamische Vorlagen

Die Feldtypen Select und Radio unterstützen die dynamische Generierung der Vorlage InnerBlocks abhängig vom Feldwert. Das ist nützlich, wenn du Nutzern die Auswahl einer anderen Vorlage für die Komponente InnerBlocks ermöglichen möchtest.

Füge dazu einfach den Schlüssel innerBlocks mit der Vorlage zum Options-Array hinzu:

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"
      }
    ]
  }
}

Blockkontext und Kommunikation

Erfahre, wie übergeordnete und untergeordnete Blöcke mithilfe von Kontext Daten austauschen.