Aller au contenu

Filtrage des attributs

Blockstudio fournit deux méthodes pour filtrer les attributs des blocs.

Définitions des attributs

blockstudio/blocks/attributes filtre chaque définition de champ, tandis que Blockstudio construit et enregistre un bloc. Utilisez-le pour ajuster les contrôles de l’éditeur, les valeurs par défaut, les conditions, les options et la définition servant à valider les valeurs lors du rendu.

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (
    ($block['name'] ?? '') === 'my-theme/code-block' &&
    ($attribute['id'] ?? '') === 'lineNumbers'
  ) {
    $attribute['default'] = true;
    $attribute['conditions'] = [
      [
        [
          'id' => 'language',
          'operator' => '==',
          'value' => 'css'
        ]
      ]
    ];
  }

  return $attribute;
}, 10, 2);

Le code ci-dessus définit lineNumbers sur true par défaut et masque le champ, sauf si language est défini sur css.

À chaque appel, le rappel reçoit une définition de champ, y compris pour les champs de groupe et de répéteur imbriqués. Il s’exécute lors de l’enregistrement du bloc, et non à chaque rendu côté frontend.

Les définitions d’options filtrées sont également utilisées par la carte des attributs de rendu. Par exemple, une option ajoutée à un champ select, radio ou checkbox est disponible dans l’éditeur et reste valide lorsque Blockstudio résout la valeur enregistrée pour un modèle :

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (
    ($block['name'] ?? '') === 'bsui/button' &&
    ($attribute['id'] ?? '') === 'variant'
  ) {
    $attribute['options'][] = [
      'label' => 'Brand',
      'value' => 'brand',
    ];
  }

  return $attribute;
}, 10, 2);

Valeurs rendues

blockstudio/blocks/attributes/render filtre la valeur résolue d’un champ juste avant qu’elle soit transmise au modèle de bloc. Il s’exécute une fois par champ ; un rappel reçoit donc la valeur, la clé du champ et les données du bloc.

PHP
add_filter('blockstudio/blocks/attributes/render', function($value, $key, $block) {
  if (($block['name'] ?? '') === 'my-theme/code-block' && 'lineNumbers' === $key) {
    return true;
  }
  return $value;
}, 10, 3);

L’exemple ci-dessus remplace toute valeur enregistrée dans l’éditeur pour lineNumbers. Enregistrez le rappel avec trois arguments acceptés (le dernier argument de add_filter) ; sinon, WordPress ne transmet que la valeur.

  • $value : la valeur résolue du champ, sous la forme que reçoit le modèle sous forme de $a[$key]. Renvoyez la valeur que le modèle doit recevoir.
  • $key : la clé du champ, telle qu’elle est utilisée dans $a. Dans une ligne de répéteur, il s’agit de l’ID du champ dans la ligne.
  • $block : le tableau de données du bloc que les modèles reçoivent sous forme de $block ou de $b, avec id, name, postId, postType, index, indexTotal, context et les indicateurs d’îlot. Pour les extensions appliquées à un bloc qui n’est pas un bloc Blockstudio, $block ne contient que l’entrée blockstudio (attributes et disabled) et ne comporte pas de name.

Le filtre s’exécute aussi pour les attributs qui ne sont pas des champs Blockstudio, comme className et anchor, ainsi que pour l’élément associé <id>__size d’un champ de fichiers. Comparez donc $key avant de modifier une valeur. La valeur de retour remplace uniquement la valeur de $key ; le filtre ne peut pas ajouter de nouvelles clés à $a.

Utilisez le filtre de définition pour modifier la configuration des champs et le filtre de rendu pour calculer ou remplacer les valeurs de modèle pour une requête.

Lorsque les valeurs sont lues via bs_block_values() au lieu d’être rendues, ce filtre ne reçoit que le nom du bloc dans $block. Les compteurs de rendu et les autres métadonnées propres au rendu ne sont pas créés par cette fonction d’assistance.