Aller au contenu

InnerBlocks

Les blocs internes vous permettent d’ajouter des blocs à vos blocs. En coulisses, Blockstudio utilise le composant InnerBlocks. Un seul composant InnerBlocks peut être utilisé par bloc ; il s’agit d’une limite WordPress.

Utilisation de base

Pour utiliser InnerBlocks, ajoutez le composant <InnerBlocks /> au modèle de votre bloc :

PHP
<InnerBlocks />

La composition dépend de vous. Vous pouvez imbriquer le composant InnerBlocks aussi profondément que vous le souhaitez, ou l’utiliser seul.

Propriétés

allowedBlocks

La propriété allowedBlocks vous permet de définir les blocs qui peuvent être insérés dans le composant 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 accepte également des jetons développés côté serveur. Les jetons sont développés avant que l’éditeur ne reçoive le modèle, tandis que les noms littéraux des blocs restent inchangés.

Jeton Description
namespace/* Tous les blocs enregistrés dans cet espace de noms
category:<slug> Tous les blocs enregistrés dans cette catégorie de blocs WordPress
@theme Tous les blocs Blockstudio enregistrés depuis le thème actif

Les entrées développées sont dédupliquées selon l’ordre de l’auteur :

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

Les jetons qui ne correspondent à aucun bloc sont ignorés. La sortie de l’interface publique reste inchangée, car allowedBlocks est utilisé uniquement par l’éditeur.

tag

Par défaut, le composant InnerBlocks est rendu sous forme d’élément div. Vous pouvez modifier ce comportement à l’aide de la propriété tag.

PHP
<InnerBlocks tag="section" />

template

La propriété template vous permet de définir un modèle pour le composant 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 propriété templateLock vous permet de définir si le modèle peut être modifié ou non.

Valeur Description
contentOnly Empêche toutes les opérations. Les types de blocs sans contenu sont masqués dans la vue en liste. Les blocs enfants ne peuvent pas remplacer ce réglage.
all Empêche toutes les opérations. Impossible d’insérer, de déplacer ou de supprimer des blocs.
insert Empêche l’insertion ou la suppression de blocs, mais permet de déplacer ceux qui existent déjà.
false Empêche l’application du verrouillage, même si un bloc parent est verrouillé.

renderAppender

La propriété renderAppender vous permet de définir le type d’ajout de bloc.

Valeur Description
default Afficher l’ajouteur de bloc par défaut (l’ajouteur de style paragraphe si un bloc paragraphe est autorisé)
button Afficher un bouton avec une icône + comme ajouteur

useBlockProps

useBlockProps supprimera l’enveloppe externe du composant InnerBlocks dans l’éditeur. Consultez useBlockProps pour en savoir plus.

Contexte

Enregistrement

Blockstudio prend en charge le contexte pour le composant InnerBlocks. Cela vous permet de transmettre des données du bloc parent aux blocs enfants. Il utilise le mécanisme de contexte de base WordPress en interne, mais Blockstudio offre une API plus pratique.

Au lieu de devoir définir séparément tous les attributs à transmettre dans le contexte, vous pouvez simplement vous abonner à tous les attributs d’un bloc parent.

Chaque enfant reçoit les valeurs de son propre parent, y compris lors du premier rendu préchargé de l’éditeur. La mise à jour des champs d’un fournisseur actualise ses enfants dans l’éditeur, même si un rendu précédent est encore en cours de chargement. Les blocs enfants identiques placés sous différents fournisseurs conservent des rendus mis en cache distincts, tenant compte de leur contexte.

Imaginons que vous ayez configuré un bloc conteneur comme suit :

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

Dans votre bloc enfant, utilisez simplement la propriété usesContext avec le nom du bloc parent pour accéder à tous les attributs du parent dans le modèle de votre bloc.

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
}

Modèles

Les variables $context et $c sont disponibles dans vos modèles de bloc pour accéder à tous les attributs du parent. Les blocs enfants sont automatiquement rechargés dans l’éditeur si les données du parent changent.

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>

Enveloppe côté frontend

InnerBlocks doit afficher un élément enveloppe autour de ses enfants dans l’éditeur. Toutefois, vous pouvez le supprimer du frontend à l’aide du filtre 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);

Retour anticipé

Pour effectuer un retour anticipé depuis la méthode render de votre bloc, vous pouvez vérifier si la variable $innerBlocks est vide. C’est utile si vous ne voulez rien afficher en l’absence de blocs internes.

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

Comme <InnerBlocks/> affiche toujours une balise de paragraphe vide, vous pouvez utiliser la fonction strip_tags pour vérifier si le contenu est vide.

Modèles dynamiques

Les types de champ Select et Radio permettent de générer dynamiquement le modèle InnerBlocks en fonction de la valeur du champ. Cela est utile si vous souhaitez permettre à l’utilisateur de choisir un autre modèle pour le composant InnerBlocks.

Pour cela, ajoutez simplement une clé innerBlocks au tableau d’options avec le modèle :

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

Contexte et communication entre blocs

Découvrez comment les blocs parent et enfant partagent des données à l’aide du contexte.