Aller au contenu

Rendu des attributs

Dans les fichiers de modèle, tous les attributs sont accessibles à l’aide des variables $attributes ou $a et de l’identifiant du champ correspondant.

PHP

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>

Écriture programmatique des attributs

L’éditeur imbrique les valeurs enregistrées sous blockstudio.attributes. Tout outil qui écrit un bloc en dehors de l’éditeur, comme REST API, WP-CLI, une migration de contenu ou un serveur MCP, trouve le bloc à partir des attributs enregistrés par Blockstudio sur WP_Block_Type et les écrit au niveau supérieur. Les deux structures sont rendues :

PHP
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );

// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );

Seuls les identifiants déclarés par le bloc sont lus au niveau supérieur ; les attributs propres à WordPress, tels que anchor, className, lock, metadata et style, ne sont donc jamais adoptés comme valeurs de champ. Si le même identifiant apparaît aux deux emplacements, la valeur imbriquée prévaut.

Lecture programmatique des attributs

Le code exécuté en dehors du modèle, par exemple pour les données structurées sur save_post, les exports, l’indexation de recherche ou un filtre render_block, a souvent besoin des valeurs d’un bloc enregistré telles qu’elles apparaissent dans le modèle. bs_block_values() les renvoie sans afficher le bloc. Appelez-le après l’enregistrement du bloc (init ou ultérieurement) avec le tableau complet attrs de parse_blocks() :

PHP
foreach (parse_blocks($post->post_content) as $block) {
  if ($block['blockName'] === null) {
    continue;
  }

  $a = bs_block_values($block['blockName'], $block['attrs']);

  if ($a === null) {
    // Not a Blockstudio block, and no extension applies.
    continue;
  }

  echo esc_html($a['title'] ?? '');
}

Le résultat est le tableau $a du modèle, indexé par identifiant de champ :

  • Les valeurs par défaut des champs s’appliquent, et un répéteur avec min contient ses lignes initiales.
  • Les valeurs de premier niveau et blockstudio.attributes sont fusionnées, et la valeur imbriquée est prioritaire. Seuls les identifiants déclarés sont lus au premier niveau, et WordPress ignore une valeur de premier niveau qui ne correspond pas au type enregistré du champ, par exemple une chaîne de sélection, comme lors de l’affichage.
  • Les champs des extensions correspondantes sont inclus, avec leurs valeurs par défaut. Une extension d’un bloc principal ou tiers ne lit que blockstudio.attributes, comme lors de l’affichage.
  • Les formats de retour sont appliqués : une sélection avec returnFormat égal à label renvoie le libellé, et un champ de fichiers renvoie les données des pièces jointes.
  • Les champs désactivés et vides sont false, comme dans le modèle.

null signifie que ni le bloc ni une extension ne sont gérés par Blockstudio. Un bloc Blockstudio sans champ renvoie [].

La fonction exécute la même transformation que le rendu et a donc les mêmes effets secondaires : les champs de fichiers interrogent les pièces jointes, un champ de bloc qui ne renvoie pas data affiche le bloc référencé, et le filtre blockstudio/blocks/attributes/render s’exécute pour chaque valeur. Elle n’affiche pas le modèle du bloc lui-même et ne résout pas innerBlocks ; parcourez-les vous-même. Un champ de code conserve un identifiant %selector% généré qui diffère d’un appel à l’autre.

La résolution utilise le contexte WordPress actuel. Les métadonnées générées uniquement lors du rendu, comme les compteurs de blocs et innerBlocks, ne sont pas créées ; les filtres de rendu des attributs reçoivent le nom du bloc, et non les métadonnées d’un bloc entièrement rendu.

Il n’existe aucune option permettant d’obtenir les valeurs stockées sans transformation. Lisez directement le tableau attrs pour cela, ou utilisez bs_validate_block() pour les vérifier.

Valeurs vides

Les valeurs d’attribut renvoient false si le champ est vide ou si aucune option n’a été sélectionnée.

PHP

PHP
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

Twig
{% if a.message %}
  <h1>{{ a.message }}</h1>
{% endif %}

Types complexes

Fichiers

Par défaut (sans returnFormat, ou avec "returnFormat": "object"), le champ de fichiers renvoie un tableau contenant les données de la pièce jointe. Avec "multiple": true, il renvoie une liste de ces tableaux. Un fichier dont la pièce jointe n’existe plus est false.

Clé Description
ID L’identifiant de la pièce jointe.
title Le titre de la pièce jointe.
alt Le texte alternatif. Si celui-ci est vide, le titre de la pièce jointe est utilisé.
caption La légende.
description La description.
href Le permalien de la page de la pièce jointe.
url Le URL du fichier. Avec le menu déroulant des tailles ("size": true), le URL de la taille sélectionnée.
sizes Le URL et les dimensions de chaque taille d’image enregistrée, voir ci-dessous.

PHP

PHP
<?php if ($a['image']) :
  $image = $a['image'];
  $sizes = $image['sizes'] ?? [];
?>
  <img
    src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
    alt="<?php echo esc_attr($image['alt']); ?>"
    <?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
      width="<?php echo esc_attr($sizes['large-width']); ?>"
      height="<?php echo esc_attr($sizes['large-height']); ?>"
    <?php endif; ?>
  />
<?php endif; ?>

Twig

Twig
{% if a.image %}
  <img
    src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
    alt="{{ a.image.alt|e('html_attr') }}"
    {% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
      width="{{ a.image.sizes['large-width']|e('html_attr') }}"
      height="{{ a.image.sizes['large-height']|e('html_attr') }}"
    {% endif %}
  />
{% endif %}

sizes contient une entrée pour chaque taille d’image enregistrée, ainsi que full : le URL sous le nom de la taille, et les dimensions sous <size>-width et <size>-height. Si une taille WordPress n’a pas été générée pour une pièce jointe, le fichier d’origine et ses dimensions sont renvoyés. Si WordPress ne peut pas trouver une image ou un aperçu, la clé sizes est absente. Par exemple, un PDF sans aperçu généré ne contient pas de sizes, mais un PDF avec des métadonnées d’aperçu peut avoir des tailles d’image. sizes vaut null lorsqu’aucune taille d’image n’est enregistrée ou lorsque le filtre correspondantfiles/sizes est désactivé. Ce filtre peut également raccourcir la liste ; vérifiez donc qu’une taille existe avant d’en lire les dimensions, comme dans les exemples ci-dessus.

L’objet ne contient aucune clé width, height, mime, type ou size. Lisez les dimensions dans sizes, ou utilisez ID avec des fonctions telles que wp_get_attachment_image() et get_post_mime_type().

Formats de retour

returnFormat modifie la valeur renvoyée par le champ :

returnFormat Valeur
"object" (par défaut) Le tableau décrit ci-dessus.
"id" L’identifiant de la pièce jointe tel qu’il est stocké, ou une liste d’identifiants avec "multiple": true.
"url" Le URL sous forme de chaîne, ou une liste d’URL avec "multiple": true. Les images utilisent la taille définie avec returnSize (par défaut full), les autres fichiers leur URL de fichier.

Le champ de lien renvoie un objet avec URL et des attributs :

PHP

PHP
<?php if ($a['link']) : ?>
  <a
    href="<?php echo $a['link']['url']; ?>"
    target="<?php echo $a['link']['target']; ?>"
  >
    <?php echo $a['link']['title']; ?>
  </a>
<?php endif; ?>

Twig

Twig
{% if a.link %}
  <a href="{{ a.link.url }}" target="{{ a.link.target }}">
    {{ a.link.title }}
  </a>
{% endif %}

Icône

Le champ d’icône renvoie un objet avec les clés set, subSet et icon. Utilisez les fonctions d’assistance bs_render_icon() et bs_icon() pour afficher le SVG :

PHP

PHP
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

Twig
{% if a.icon %}
  <div class="icon">
    {{ bs_icon(a.icon) }}
  </div>
{% endif %}

bs_render_icon() affiche directement le SVG. bs_icon() le renvoie sous forme de chaîne.

Attributs

Le type de champ des attributs renvoie un tableau de paires {attribute, value} à afficher sous forme d’attributs HTML. Utilisez bs_render_data_attributes() pour les afficher :

PHP

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
  Content
</div>

bs_render_data_attributes() affiche directement les attributs. bs_data_attributes() renvoie la chaîne.

Groupe

Les champs de groupe préfixent les identifiants de leurs attributs enfants avec le nom du groupe. Utilisez bs_get_group() pour extraire les champs du groupe dans un tableau épuré :

PHP

PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>

Cela supprime le préfixe du groupe des clés d’attribut. Par exemple, $a['settings_title'] devient $group['title'].

Cette fonction d’assistance fonctionne également lorsque le groupe provient d’un champ personnalisé réutilisé :

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>

Répéteur

Parcourez les éléments du répéteur :

PHP

PHP
<?php foreach ($a['items'] as $item) : ?>
  <div class="item">
    <h3><?php echo $item['title']; ?></h3>
    <p><?php echo $item['description']; ?></p>
  </div>
<?php endforeach; ?>

Twig

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

Recueil de motifs de champs