Aller au contenu

Recueil de modèles de champs

Le système de champs de Blockstudio est simple pris isolément : ajoutez un champ à blockstudio.attributes, puis accédez-y avec $a dans votre modèle. Mais les blocs réels comportent rarement un seul champ. Ils réunissent des groupes de réglages associés, des champs qui s’affichent ou se masquent selon d’autres champs, des répéteurs aux structures de lignes complexes et des données qui doivent pouvoir être interrogées en dehors de l’éditeur de blocs.

Ce guide rassemble des recettes pratiques pour les modèles de champs courants. Chaque recette présente la configuration block.json et le code de modèle correspondant. Copiez-les directement dans vos blocs et adaptez-les selon vos besoins.

Champs conditionnels

Le modèle le plus courant consiste à afficher ou masquer des champs selon la valeur d’un autre champ. L’éditeur reste ainsi épuré, car seules les options pertinentes sont présentées.

Afficher des options avec un bouton bascule

Un bloc d’appel à l’action où des réglages supplémentaires apparaissent lorsque l’utilisateur active un bouton :

JSON
{
  "name": "my-theme/cta",
  "title": "Call to Action",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "Ready to get started?" },
      { "id": "description", "type": "textarea", "label": "Description" },
      { "id": "showButton", "type": "toggle", "label": "Show Button", "default": true },
      {
        "id": "buttonText",
        "type": "text",
        "label": "Button Text",
        "default": "Get Started",
        "conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
      },
      {
        "id": "buttonUrl",
        "type": "link",
        "label": "Button Link",
        "conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
      }
    ]
  }
}

Les champs du texte et du lien du bouton n’apparaissent que lorsque le bouton bascule est activé. Dans le modèle, vérifiez l’état du bouton avant le rendu :

PHP
<div useBlockProps>
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <?php if ( $a['description'] ) : ?>
    <p><?php echo esc_html( $a['description'] ); ?></p>
  <?php endif; ?>
  <?php if ( $a['showButton'] && $a['buttonUrl'] ) : ?>
    <a href="<?php echo esc_url( $a['buttonUrl']['url'] ); ?>">
      <?php echo esc_html( $a['buttonText'] ); ?>
    </a>
  <?php endif; ?>
</div>

Sélectionner pour changer de groupe de champs

Un bloc de bannière principale où le type d’arrière-plan détermine les champs affichés :

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      {
        "id": "bgType",
        "type": "select",
        "label": "Background Type",
        "default": "color",
        "options": [
          { "value": "color", "label": "Solid Color" },
          { "value": "gradient", "label": "Gradient" },
          { "value": "image", "label": "Image" },
          { "value": "video", "label": "Video" }
        ]
      },
      {
        "id": "bgColor",
        "type": "color",
        "label": "Background Color",
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "color" }]]
      },
      {
        "id": "bgGradient",
        "type": "gradient",
        "label": "Background Gradient",
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "gradient" }]]
      },
      {
        "id": "bgImage",
        "type": "files",
        "label": "Background Image",
        "multiple": false,
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "image" }]]
      },
      {
        "id": "bgVideo",
        "type": "files",
        "label": "Background Video",
        "multiple": false,
        "allowedTypes": ["video"],
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "video" }]]
      },
      {
        "id": "overlay",
        "type": "range",
        "label": "Overlay Opacity",
        "default": 50,
        "min": 0,
        "max": 100,
        "conditions": [[{ "id": "bgType", "operator": "!=", "value": "color" }]]
      }
    ]
  }
}

Le champ d’opacité de la superposition utilise != pour s’afficher pour tous les types sauf la couleur unie. Un seul champ d’arrière-plan s’affiche à la fois. Un champ color renvoie un tableau contenant value, name et slug de la couleur ; le modèle lit donc ['value'] :

PHP
<?php
$bg_style = match ( $a['bgType'] ) {
	'color'    => $a['bgColor'] ? "background-color: {$a['bgColor']['value']}" : '',
	'gradient' => $a['bgGradient'] ? "background: {$a['bgGradient']}" : '',
	'image'    => $a['bgImage'] ? "background-image: url({$a['bgImage']['url']})" : '',
	default    => '',
};
?>
<div useBlockProps style="<?php echo esc_attr( $bg_style ); ?>">
  <?php if ( $a['bgType'] === 'video' && $a['bgVideo'] ) : ?>
    <video autoplay muted loop playsinline>
      <source src="<?php echo esc_url( $a['bgVideo']['url'] ); ?>" />
    </video>
  <?php endif; ?>
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
</div>

Conditions OU

Affichez un champ si l’une de plusieurs conditions est vraie. Chaque tableau interne forme un groupe ET ; le tableau externe les combine avec OU :

JSON
{
  "id": "caption",
  "type": "text",
  "label": "Caption",
  "conditions": [
    [{ "id": "bgType", "operator": "==", "value": "image" }],
    [{ "id": "bgType", "operator": "==", "value": "video" }]
  ]
}

Cela affiche le champ de légende lorsque bgType vaut « image » OU « video ».

Conditions enchaînées

Plusieurs conditions dans un même tableau interne sont évaluées avec la logique ET :

JSON
{
  "id": "altText",
  "type": "text",
  "label": "Alt Text",
  "conditions": [[
    { "id": "bgType", "operator": "==", "value": "image" },
    { "id": "bgImage", "operator": "!empty" }
  ]]
}

Le champ de texte alternatif apparaît uniquement lorsque bgType vaut « image » ET qu’une image a été sélectionnée.

Conditions globales

Affichez des champs selon le type de publication, l’ID de publication ou le rôle de l’utilisateur, plutôt que selon les valeurs d’autres champs :

JSON
{
  "id": "seoTitle",
  "type": "text",
  "label": "SEO Title",
  "conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}

Types de conditions globales disponibles : postType, postId, userRole, userId.

Réglages organisés

À mesure que les blocs se complexifient, regrouper les champs par logique permet de garder l’inspecteur facile à gérer.

Groupes pour organiser visuellement

Les groupes créent des sections repliables dans l’inspecteur. Un groupe anonyme (sans id) sert uniquement à l’organisation visuelle ; ses champs s’utilisent avec leurs ID seuls :

JSON
{
  "name": "my-theme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "title": "Content",
        "attributes": [
          { "id": "title", "type": "text", "label": "Title" },
          { "id": "description", "type": "textarea", "label": "Description" },
          { "id": "image", "type": "files", "label": "Image", "multiple": false }
        ]
      },
      {
        "type": "group",
        "title": "Link",
        "attributes": [
          { "id": "url", "type": "link", "label": "URL" },
          { "id": "openInNewTab", "type": "toggle", "label": "Open in New Tab" }
        ]
      },
      {
        "type": "group",
        "title": "Appearance",
        "attributes": [
          {
            "id": "style",
            "type": "select",
            "label": "Style",
            "default": "elevated",
            "options": [
              { "value": "elevated", "label": "Elevated" },
              { "value": "outlined", "label": "Outlined" },
              { "value": "flat", "label": "Flat" }
            ]
          },
          { "id": "accentColor", "type": "color", "label": "Accent Color" }
        ]
      }
    ]
  }
}
PHP
<div useBlockProps>
  <h3><?php echo esc_html( $a['title'] ); ?></h3>
  <p><?php echo esc_html( $a['description'] ); ?></p>
</div>

Les champs s’utilisent directement : $a['title'], $a['style'], $a['accentColor']. Les groupes ne modifient que la mise en page de l’inspecteur.

Groupes nommés avec bs_get_group

Lorsqu’un groupe possède un id, l’ID de ses champs enfants est préfixé. Utilisez bs_get_group() pour retirer ce préfixe :

JSON
{
  "id": "author",
  "type": "group",
  "title": "Author",
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" },
    { "id": "avatar", "type": "files", "label": "Avatar", "multiple": false }
  ]
}

Sans l’aide, les champs s’utilisent ainsi : $a['author_name'], $a['author_role'], $a['author_avatar']. Avec l’aide :

PHP
<?php $author = bs_get_group( $a, 'author' ); ?>
<div class="author">
  <?php if ( $author['avatar'] ) : ?>
    <img src="<?php echo esc_url( $author['avatar']['url'] ); ?>" alt="" />
  <?php endif; ?>
  <p><?php echo esc_html( $author['name'] ); ?></p>
  <p><?php echo esc_html( $author['role'] ); ?></p>
</div>

Les groupes nommés sont utiles lorsque les mêmes noms de champs apparaissent dans plusieurs groupes (e.g, author_name et company_name), ou lorsque vous voulez transmettre le groupe en tant qu’unité à un modèle partiel.

Mise en page en grille dans les groupes

Utilisez la propriété style pour disposer côte à côte les champs enfants du groupe :

JSON
{
  "type": "group",
  "title": "Dimensions",
  "style": {
    "display": "grid",
    "grid-template-columns": "1fr 1fr",
    "grid-gap": "16px"
  },
  "attributes": [
    { "id": "width", "type": "unit", "label": "Width", "default": "100%", "switch": false },
    { "id": "height", "type": "unit", "label": "Height", "default": "auto", "switch": false }
  ]
}

Les deux champs d’unité s’affichent côte à côte dans l’inspecteur au lieu d’être empilés. Cette disposition convient aux paires de dimensions, aux valeurs de marge et de remplissage, ou à toute paire de champs ayant un lien logique.

Onglets pour les grandes sections

Lorsqu’un bloc comporte de nombreux réglages, les onglets offrent une organisation plus claire qu’une longue liste de groupes :

JSON
{
  "type": "tabs",
  "tabs": [
    {
      "title": "Content",
      "attributes": [
        { "id": "title", "type": "text", "label": "Title" },
        { "id": "body", "type": "wysiwyg", "label": "Body" }
      ]
    },
    {
      "title": "Media",
      "attributes": [
        { "id": "image", "type": "files", "label": "Image", "multiple": false },
        { "id": "video", "type": "files", "label": "Video", "multiple": false, "allowedTypes": ["video"] }
      ]
    },
    {
      "title": "Settings",
      "attributes": [
        { "id": "layout", "type": "select", "label": "Layout", "options": [
          { "value": "left", "label": "Media Left" },
          { "value": "right", "label": "Media Right" }
        ]},
        { "id": "fullWidth", "type": "toggle", "label": "Full Width" }
      ]
    }
  ]
}

Les champs de chaque onglet sont accessibles comme des champs de premier niveau : $a['title'], $a['image'], $a['layout']. Les onglets servent uniquement de conteneur UI.

Modèles de répéteurs

Les répéteurs permettent aux utilisateurs d’ajouter plusieurs lignes de champs. Ils sont essentiels pour les listes, les grilles, les chronologies et tout composant comportant un nombre variable d’éléments.

Répéteur de base avec contraintes

Une liste de fonctionnalités contenant de 1 à 6 éléments :

JSON
{
  "id": "features",
  "type": "repeater",
  "label": "Features",
  "min": 1,
  "max": 6,
  "textButton": "Add Feature",
  "attributes": [
    { "id": "icon", "type": "icon", "label": "Icon" },
    { "id": "title", "type": "text", "label": "Title", "default": "Feature" },
    { "id": "description", "type": "textarea", "label": "Description" }
  ]
}
PHP
<div useBlockProps class="grid grid-cols-3 gap-8">
  <?php foreach ( $a['features'] as $feature ) : ?>
    <div>
      <?php if ( $feature['icon'] ) : ?>
        <?php bs_render_icon( $feature['icon'] ); ?>
      <?php endif; ?>
      <h3><?php echo esc_html( $feature['title'] ); ?></h3>
      <p><?php echo esc_html( $feature['description'] ); ?></p>
    </div>
  <?php endforeach; ?>
</div>

Libellés personnalisés pour les lignes

Par défaut, les lignes réduites d’un répéteur affichent un libellé générique. Utilisez textMinimized pour afficher à la place la valeur d’un champ :

JSON
{
  "id": "team",
  "type": "repeater",
  "label": "Team Members",
  "textMinimized": { "id": "name", "fallback": "Team Member" },
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" },
    { "id": "photo", "type": "files", "label": "Photo", "multiple": false }
  ]
}

Lorsqu’une ligne est repliée, elle affiche le nom de la personne au lieu de « Ligne 1 ». fallback est utilisé si le champ du nom est vide. Vous pouvez aussi ajouter les chaînes prefix et suffix.

Conditions dans les répéteurs

Les champs d’un répéteur peuvent faire référence aux autres champs de la même ligne avec leur id seul (aucun préfixe n’est nécessaire) :

JSON
{
  "id": "links",
  "type": "repeater",
  "label": "Links",
  "attributes": [
    { "id": "label", "type": "text", "label": "Label" },
    { "id": "url", "type": "link", "label": "URL" },
    {
      "id": "isExternal",
      "type": "toggle",
      "label": "External Link"
    },
    {
      "id": "externalNote",
      "type": "message",
      "label": "Note",
      "description": "External links open in a new tab with rel=\"noopener\".",
      "conditions": [[{ "id": "isExternal", "operator": "==", "value": true }]]
    }
  ]
}

Référencer des champs externes depuis un répéteur

Lorsqu’une condition dans un répéteur doit vérifier un champ situé en dehors de celui-ci, ajoutez "context": "main" :

JSON
{
  "id": "showDescriptions",
  "type": "toggle",
  "label": "Show Descriptions",
  "default": true
},
{
  "id": "items",
  "type": "repeater",
  "label": "Items",
  "attributes": [
    { "id": "title", "type": "text", "label": "Title" },
    {
      "id": "description",
      "type": "textarea",
      "label": "Description",
      "conditions": [[{
        "id": "showDescriptions",
        "operator": "==",
        "value": true,
        "context": "main"
      }]]
    }
  ]
}

Sans "context": "main", la condition rechercherait un champ showDescriptions dans la ligne du répéteur. Avec ce préfixe, elle vérifie le bouton bascule à la racine.

Onglets dans les répétiteurs

Les onglets ne sont pas disponibles dans les répétiteurs : un champ tabs dans une ligne de répétiteur affiche une notification dans l’éditeur au lieu de ses champs, et l’extension PHPStan le signale. Gardez plutôt les champs d’une ligne à plat. Pour les lignes longues, un libellé personnalisé (textMinimized) permet de lire les lignes réduites ; les conditions dans une ligne peuvent masquer les champs nécessaires à certaines lignes seulement, comme dans les exemples précédents.

Définissez "minimized": true sur un répétiteur pour que les lignes existantes soient réduites par défaut. Les nouvelles lignes s’ouvrent immédiatement. Les exceptions développées sont mémorisées dans ce navigateur entre les rechargements de l’éditeur ; il s’agit d’une préférence de modification, et non d’un contenu enregistré dans l’article. Les répétiteurs sans minimized conservent leur comportement actuel, avec les lignes développées par défaut.

Modèles de médias

Image unique avec solution de repli

JSON
{
  "id": "image",
  "type": "files",
  "label": "Image",
  "multiple": false
}
PHP
<?php if ( $a['image'] ) : ?>
  <img
    src="<?php echo esc_url( $a['image']['url'] ); ?>"
    alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
    <?php if ( isset( $a['image']['sizes']['full-width'], $a['image']['sizes']['full-height'] ) ) : ?>
      width="<?php echo esc_attr( $a['image']['sizes']['full-width'] ); ?>"
      height="<?php echo esc_attr( $a['image']['sizes']['full-height'] ); ?>"
    <?php endif; ?>
  />
<?php endif; ?>

La valeur returnFormat par défaut est "object", qui fournit ID, title, alt, caption, description, href, url et sizes. sizes contient le URL de chaque taille d’image enregistrée (sizes['large']), ainsi que ses dimensions (sizes['large-width'], sizes['large-height']). Consultez Attributs de rendu pour la liste complète.

JSON
{
  "id": "gallery",
  "type": "files",
  "label": "Gallery",
  "multiple": true,
  "max": 6,
  "allowedTypes": ["image"]
}
PHP
<?php if ( $a['gallery'] ) : ?>
  <div class="grid grid-cols-3 gap-4">
    <?php foreach ( $a['gallery'] as $image ) : ?>
      <img
        src="<?php echo esc_url( $image['url'] ); ?>"
        alt="<?php echo esc_attr( $image['alt'] ); ?>" />
    <?php endforeach; ?>
  </div>
<?php endif; ?>

Image désactivable avec interrupteur

La propriété switch ajoute une icône en forme d’œil qui permet aux utilisateurs de désactiver le champ sans supprimer sa valeur :

JSON
{
  "id": "logo",
  "type": "files",
  "label": "Logo",
  "multiple": false,
  "switch": true
}
PHP
<?php
$is_disabled = ! empty( $a['_disabled'] ) && in_array( 'logo', $a['_disabled'], true );
if ( $a['logo'] && ! $is_disabled ) : ?>
  <img src="<?php echo esc_url( $a['logo']['url'] ); ?>" alt="" />
<?php endif; ?>

L’utilisateur peut désactiver le logo sans supprimer le fichier importé. En le réactivant, le même fichier réapparaît.

Variantes du format de retour

Contrôlez ce que renvoie le champ de fichiers :

JSON
// Full object (default)
{ "id": "photo", "type": "files", "returnFormat": "object", "multiple": false }
// $a['photo']['url'], $a['photo']['alt'], $a['photo']['sizes']['full-width'], etc.

// Just the ID
{ "id": "photo", "type": "files", "returnFormat": "id", "multiple": false }
// $a['photo'] = 42

// Just the URL
{ "id": "photo", "type": "files", "returnFormat": "url", "multiple": false }
// $a['photo'] = "https://example.com/photo.jpg"

Utilisez "id" si vous devez appeler vous-même wp_get_attachment_image(). Utilisez "url" pour les images d’arrière-plan simples. Utilisez "object" (la valeur par défaut) pour tout le reste.

Avec "returnFormat": "id", une référence de chaîne importée telle que "buckshair-home" est transmise sans modification. L’éditeur affiche une carte de remplacement sans miniature, y compris dans les lignes de répétiteur. Ouvrir ou enregistrer la page ne convertit pas une référence scalaire en tableau. Les listes mixtes d’identifiants de pièces jointes et de références de chaîne fonctionnent également ; seules les pièces jointes dont l’identifiant est positif sont recherchées dans la médiathèque.

Blockstudio ne résout pas les références de chaîne personnalisées en pièces jointes. Résolvez-les dans votre propre filtre de rendu ou modèle si vous utilisez des noms portables entre sites. Le choix d’un remplacement dans la médiathèque enregistre son identifiant de pièce jointe comme d’habitude.

Options dynamiques

Remplir à partir des publications

Un champ de sélection qui répertorie toutes les pages publiées :

JSON
{
  "id": "linkedPage",
  "type": "select",
  "label": "Linked Page",
  "stylisedUi": true,
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": {
      "post_type": "page",
      "post_status": "publish",
      "posts_per_page": -1
    }
  }
}

Le champ se remplit automatiquement avec les titres des pages comme libellés et les ID des publications comme valeurs. Utilisez returnFormat dans la configuration de remplissage pour personnaliser la correspondance :

JSON
"populate": {
  "type": "query",
  "query": "posts",
  "arguments": { "post_type": "page" },
  "returnFormat": { "value": "ID", "label": "post_title" }
}

Remplir à partir des termes de taxonomie

JSON
{
  "id": "category",
  "type": "select",
  "label": "Category",
  "stylisedUi": true,
  "populate": {
    "type": "query",
    "query": "terms",
    "arguments": {
      "taxonomy": "category",
      "hide_empty": true
    }
  }
}

Remplir à partir d’une fonction PHP

JSON
{
  "id": "postType",
  "type": "select",
  "label": "Post Type",
  "populate": {
    "type": "function",
    "function": "get_post_types",
    "arguments": { "public": true }
  }
}

Options statiques complétées par des options dynamiques

Combinez des options codées en dur avec des options dynamiques. Utilisez position pour définir l’emplacement des options ajoutées automatiquement :

JSON
{
  "id": "source",
  "type": "select",
  "label": "Source",
  "options": [
    { "value": "manual", "label": "Manual Entry" },
    { "value": "latest", "label": "Latest Posts" }
  ],
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": { "post_type": "page" },
    "position": "after"
  }
}

Les options statiques apparaissent d’abord, suivies des pages ajoutées dynamiquement.

Stocker des données pour les requêtes

Par défaut, les valeurs des champs sont enregistrées dans les attributs de bloc de post_content. Elles ne peuvent pas être interrogées avec WP_Query. Pour filtrer ou trier les publications selon la valeur d’un champ, utilisez le stockage.

Métadonnées de publication pour les champs interrogeables

JSON
{
  "id": "featured",
  "type": "toggle",
  "label": "Featured",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "is_featured"
  }
},
{
  "id": "priority",
  "type": "number",
  "label": "Priority",
  "default": 0,
  "min": 0,
  "max": 100,
  "storage": {
    "type": "postMeta",
    "postMetaKey": "priority_score"
  }
}

Vous pouvez maintenant interroger les publications mises en avant :

PHP
$featured = new WP_Query( array(
    'meta_query' => array(
        array(
            'key'   => 'is_featured',
            'value' => '1',
        ),
    ),
    'orderby'  => 'meta_value_num',
    'meta_key' => 'priority_score',
    'order'    => 'DESC',
) );

Les clés de métadonnées sont automatiquement enregistrées avec show_in_rest et sont donc aussi disponibles dans REST API.

Stockage double

Enregistrez les données à la fois dans les attributs de bloc et dans les métadonnées de publication. L’attribut de bloc conserve la valeur disponible dans les modèles via $a, tandis que les métadonnées de publication permettent de l’interroger :

JSON
{
  "id": "eventDate",
  "type": "date",
  "label": "Event Date",
  "storage": {
    "type": ["block", "postMeta"],
    "postMetaKey": "event_date"
  }
}

Stockage d’options pour les valeurs globales

Pour les réglages à l’échelle du site qui doivent être identiques partout, utilisez le stockage d’options :

JSON
{
  "id": "companyName",
  "type": "text",
  "label": "Company Name",
  "storage": {
    "type": "option",
    "optionKey": "site_company_name"
  }
}

La valeur est stockée dans wp_options et accessible partout avec get_option('site_company_name'). Lorsque l’utilisateur modifie ce champ dans une instance de bloc, la valeur est mise à jour globalement.

Définitions de champs réutilisables

Lorsque plusieurs blocs partagent la même structure de champs, définissez-la une seule fois comme champ personnalisé et réutilisez-la partout.

Créer un champ personnalisé

Créez un field.json dans le répertoire blockstudio/fields/ de votre thème :

Code
theme/
└── blockstudio/
    └── fields/
        └── cta/
            └── field.json
JSON
{
  "name": "cta",
  "title": "Call to Action",
  "attributes": [
    { "id": "label", "type": "text", "label": "Button Label", "default": "Learn More" },
    { "id": "url", "type": "link", "label": "Button URL" },
    { "id": "style", "type": "select", "label": "Button Style", "default": "primary", "options": [
      { "value": "primary", "label": "Primary" },
      { "value": "secondary", "label": "Secondary" },
      { "value": "outline", "label": "Outline" }
    ]}
  ]
}

Utiliser le champ personnalisé

Référencez-le dans n’importe quel bloc avec "type": "custom/cta" :

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "type": "custom/cta" }
    ]
  }
}

Les champs de l’appel à l’action sont intégrés au bloc. Accédez-y directement : $a['label'], $a['url'], $a['style'].

Champs personnalisés préfixés avec idStructure

Lorsque vous utilisez plusieurs fois le même champ personnalisé, ajoutez idStructure pour préfixer les ID :

JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/cta", "idStructure": "primary_{id}" },
      { "type": "custom/cta", "idStructure": "secondary_{id}" }
    ]
  }
}

Les champs du premier appel à l’action deviennent primary_label, primary_url, primary_style. Ceux du deuxième deviennent secondary_label, etc.

Remplacer les valeurs par défaut

Personnalisez certains champs lorsque vous référencez un champ personnalisé :

JSON
{
  "type": "custom/cta",
  "idStructure": "hero_{id}",
  "overrides": {
    "label": { "default": "Get Started", "label": "CTA Label" },
    "style": { "default": "primary" }
  }
}

Les remplacements se superposent à la définition d’origine. Vous pouvez modifier les valeurs par défaut, les libellés, les conditions ou toute autre propriété.

Modèles de rendu

Vérifier les valeurs vides

La plupart des types de champs renvoient false lorsqu’ils sont vides. Vérifiez toujours avant le rendu :

PHP
<?php if ( $a['title'] ) : ?>
  <h2><?php echo esc_html( $a['title'] ); ?></h2>
<?php endif; ?>

Pour les nombres, 0 est une valeur valide. Utilisez une comparaison stricte si vous devez distinguer « vide » de « zéro » :

PHP
<?php if ( $a['count'] !== 0 || $a['count'] !== false ) : ?>
  <span><?php echo esc_html( $a['count'] ); ?></span>
<?php endif; ?>

Sélection avec returnFormat: both

Lorsque vous avez besoin à la fois de la valeur (pour la logique) et du libellé (pour l’affichage) :

JSON
{
  "id": "status",
  "type": "select",
  "label": "Status",
  "returnFormat": "both",
  "options": [
    { "value": "active", "label": "Active" },
    { "value": "paused", "label": "On Hold" },
    { "value": "closed", "label": "Closed" }
  ]
}
PHP
<?php if ( $a['status'] ) : ?>
  <span class="badge badge--<?php echo esc_attr( $a['status']['value'] ); ?>">
    <?php echo esc_html( $a['status']['label'] ); ?>
  </span>
<?php endif; ?>

Attributs de données à partir du champ attributes

Le type de champ attributes permet aux utilisateurs d’ajouter des attributs de données personnalisés :

JSON
{
  "id": "dataAttrs",
  "type": "attributes",
  "label": "Data Attributes",
  "link": true,
  "media": true
}
PHP
<div useBlockProps <?php bs_render_data_attributes( $a['dataAttrs'] ); ?>>
  Content here.
</div>

Variables CSS à partir des valeurs de champs

Générez des propriétés personnalisées CSS à partir des champs sélectionnés :

JSON
{
  "id": "textColor", "type": "color", "label": "Text Color"
},
{
  "id": "fontSize", "type": "unit", "label": "Font Size", "default": "1rem"
}
PHP
<div useBlockProps style="<?php bs_render_variables( $a, array( 'textColor', 'fontSize' ) ); ?>">
  <p>Styled content.</p>
</div>

Cela produit style="--text-color: #333; --font-size: 1rem;" (les ID des champs sont convertis en casse-kebab). Utilisez les variables dans votre CSS :

CSS
p {
  color: var(--text-color);
  font-size: var(--font-size);
}

Étapes suivantes

  • Enregistrer des attributs : les propriétés id, type, label, default, help, position et conditions.
  • Référence des types de champs : référence générée automatiquement avec toutes les propriétés de chaque type de champ.
  • Logique conditionnelle : opérateurs, conditions globales, filtres de conditions personnalisés et contexte des répéteurs.
  • Remplissage des options : modes de requête, fonction, personnalisé et récupération pour les champs d’options dynamiques.
  • Champs personnalisés : field.json, chemins de découverte, filtre blockstudio/fields et modèles idStructure avancés.
  • Rendu : $a, $b, $c, valeurs vides et fonctions d’aide.