Vai al contenuto

Ricettario dei modelli di campo

Il sistema di campi di Blockstudio è semplice se considerato da solo: aggiungi un campo a blockstudio.attributes e accedivi tramite $a nel template. Ma i blocchi reali raramente hanno un solo campo. Contengono gruppi di impostazioni correlate, campi che vengono mostrati o nascosti in base ad altri campi, repeater con strutture di riga complesse e dati che devono poter essere interrogati al di fuori dell’editor dei blocchi.

Questa guida raccoglie ricette pratiche per i modelli di campo più comuni. Ogni ricetta mostra la configurazione block.json e il codice del template corrispondente. Copiale direttamente nei tuoi blocchi e adattale secondo necessità.

Campi condizionali

Il modello più comune: mostrare o nascondere campi in base al valore di un altro campo. In questo modo l’editor resta ordinato e presenta solo le opzioni pertinenti.

Attiva un interruttore per mostrare le opzioni

Un blocco CTA in cui compaiono impostazioni aggiuntive quando l’utente attiva un pulsante:

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

I campi per il testo e il link del pulsante compaiono solo quando l’interruttore è attivo. Nel template, controlla l’interruttore prima del rendering:

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>

Usa una selezione per cambiare i gruppi di campi

Un blocco hero in cui il tipo di sfondo determina quali campi vengono visualizzati:

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

Il campo per l’opacità della sovrapposizione usa != per comparire con tutti i tipi di sfondo, tranne il colore uniforme. Viene visualizzato un solo campo per lo sfondo alla volta. Un campo color restituisce un array con value, name e slug del colore, quindi il template legge ['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>

Condizioni OR

Mostra un campo quando è vera una qualsiasi tra più condizioni. Ogni array interno è un gruppo AND; l’array esterno li combina con OR:

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

Il campo della didascalia viene mostrato quando bgType è “image” OR “video”.

Condizioni concatenate

Più condizioni nello stesso array interno usano la logica AND:

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

Il campo del testo alternativo compare solo quando bgType è “image” AND è stata selezionata un’immagine.

Condizioni globali

Mostra i campi in base al tipo di post, all’ID del post o al ruolo dell’utente anziché ai valori di altri campi:

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

Tipi di condizioni globali disponibili: postType, postId, userRole, userId.

Impostazioni organizzate

Man mano che i blocchi diventano più complessi, organizzare i campi in gruppi logici aiuta a mantenere gestibile il pannello di ispezione.

Gruppi per organizzare visivamente

I gruppi creano sezioni comprimibili nel pannello di ispezione. Un gruppo anonimo (senza id) è puramente visivo; i suoi campi si richiamano usando i rispettivi ID senza prefisso:

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>

I campi si richiamano direttamente: $a['title'], $a['style'], $a['accentColor']. I gruppi influiscono solo sul layout del pannello di ispezione.

Gruppi con nome e bs_get_group

Quando un gruppo ha un id, gli ID dei campi figlio ricevono un prefisso. Usa bs_get_group() per rimuoverlo:

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

Senza l’helper, i campi si richiamano come $a['author_name'], $a['author_role'], $a['author_avatar']. Con l’helper:

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>

I gruppi con nome sono utili quando gli stessi nomi di campo compaiono in più gruppi (e.g, author_name e company_name) o quando vuoi passare il gruppo come unità a un template parziale.

Layout a griglia nei gruppi

Usa la proprietà style per disporre affiancati i campi figli del gruppo:

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

Nel pannello di ispezione i due campi delle unità vengono visualizzati affiancati anziché impilati. È una soluzione adatta per coppie di dimensioni, valori di margine/padding o qualsiasi coppia di campi concettualmente collegati.

Schede per le sezioni principali

Quando un blocco ha molte impostazioni, le schede organizzano i contenuti meglio di un lungo elenco di gruppi:

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

Si accede ai campi di ogni scheda come ai campi di primo livello: $a['title'], $a['image'], $a['layout']. Le schede sono solo un contenitore UI.

Modelli per repeater

I repeater permettono agli utenti di aggiungere più righe di campi. Sono indispensabili per elenchi, griglie, sequenze temporali e qualsiasi componente con un numero variabile di elementi.

Repeater di base con limiti

Un elenco di funzionalità da 1 a 6 elementi:

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>

Etichette personalizzate per le righe

Per impostazione predefinita, le righe compresse del repeater mostrano un’etichetta generica. Usa textMinimized per mostrare invece il valore di un campo:

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

Quando una riga viene compressa, mostra il nome della persona anziché “Row 1”. fallback viene usato se il campo del nome è vuoto. Puoi anche aggiungere stringhe prefix e suffix.

Condizioni nei repeater

I campi all’interno di un repeater possono fare riferimento ad altri campi della stessa riga usando i rispettivi id senza prefisso:

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

Fare riferimento ai campi esterni da un repeater

Quando una condizione all’interno di un repeater deve verificare un campo esterno al repeater, aggiungi "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"
      }]]
    }
  ]
}

Senza "context": "main", la condizione cercherebbe un campo showDescriptions all’interno della riga del repeater. Con questo prefisso, la condizione verifica l’interruttore a livello principale.

Schede nei ripetitori

Le schede non sono disponibili nei ripetitori: un campo tabs all’interno di una riga del ripetitore mostra una notifica nell’editor invece dei suoi campi, e l’estensione PHPStan lo segnala. Mantenete piatti i campi di una riga. Per le righe lunghe, un’etichetta personalizzata (textMinimized) rende leggibili le righe compresse; inoltre, le condizioni all’interno della riga possono nascondere i campi necessari solo per alcune righe, come mostrato negli esempi precedenti.

Impostate "minimized": true su un ripetitore per visualizzare inizialmente compresse le righe esistenti. Le righe appena aggiunte si aprono subito. Le eccezioni espanse vengono ricordate in questo browser anche dopo aver ricaricato l’editor; è una preferenza di modifica, non un contenuto salvato nel post. I ripetitori senza minimized mantengono il comportamento esistente, con le righe espanse per impostazione predefinita.

Modelli per i media

Immagine singola con alternativa

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; ?>

L’impostazione predefinita di returnFormat è "object", che fornisce ID, title, alt, caption, description, href, url e sizes. sizes contiene URL di ogni dimensione immagine registrata (sizes['large']), insieme alle relative dimensioni (sizes['large-width'], sizes['large-height']). Consultate Attributi di rendering per l’elenco completo.

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; ?>

Immagine disattivabile con interruttore

La proprietà switch aggiunge un’icona a forma di occhio che consente agli utenti di disattivare il campo senza eliminare il valore:

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’utente può disattivare il logo senza rimuovere il file caricato. Riattivandolo, lo stesso file torna visibile.

Varianti del formato restituito

Controlla cosa restituisce il campo files:

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"

Usa "id" quando devi richiamare wp_get_attachment_image() autonomamente. Usa "url" per immagini di sfondo semplici. Usa "object" (il valore predefinito) per tutto il resto.

Con "returnFormat": "id", un riferimento a stringa importato come "buckshair-home" viene passato senza modifiche. Nell’editor viene mostrata una scheda segnaposto senza miniatura, anche nelle righe dei ripetitori. Aprire o salvare la pagina non converte un riferimento scalare in un array. Sono supportati anche elenchi misti di ID di allegati e riferimenti a stringa; solo gli ID di allegati positivi vengono cercati nella libreria dei media.

Blockstudio non risolve i riferimenti a stringa personalizzati in allegati. Per usare nomi portabili tra siti, risolveteli nel vostro filtro di rendering o template. Se scegliete un elemento sostitutivo nella libreria dei media, viene memorizzato il relativo ID di allegato, come di consueto.

Opzioni dinamiche

Popolare dai post

Un campo di selezione che elenca tutte le pagine pubblicate:

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

Il campo si popola automaticamente con i titoli delle pagine come etichette e gli ID dei post come valori. Usa returnFormat nella configurazione di popolamento per personalizzare la mappatura:

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

Popolare dai termini di tassonomia

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

Popolare da una funzione PHP

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

Opzioni statiche con aggiunte dinamiche

Combina opzioni definite nel codice con opzioni dinamiche. Usa position per controllare dove compaiono le opzioni popolate:

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

Le opzioni statiche compaiono per prime, seguite dalle pagine popolate dinamicamente.

Archiviare dati per le query

Per impostazione predefinita, i valori dei campi risiedono negli attributi dei blocchi in post_content. Non sono interrogabili con WP_Query. Se devi filtrare o ordinare i post in base al valore di un campo, usa l’archiviazione.

Meta del post per campi interrogabili

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

Ora puoi eseguire query per trovare i post in evidenza:

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',
) );

Le chiavi meta vengono registrate automaticamente con show_in_rest, quindi sono disponibili anche nell’REST API.

Archiviazione doppia

Archivia i dati sia negli attributi del blocco sia nei meta del post. L’attributo del blocco mantiene il valore disponibile nei template tramite $a, mentre il meta del post lo rende interrogabile:

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

Archiviazione nelle opzioni per i valori globali

Per le impostazioni valide per tutto il sito e uguali ovunque, usa l’archiviazione nelle opzioni:

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

Il valore viene archiviato in wp_options ed è accessibile ovunque con get_option('site_company_name'). Quando l’utente modifica questo campo in qualsiasi istanza di blocco, il valore si aggiorna globalmente.

Definizioni di campi riutilizzabili

Quando più blocchi condividono la stessa struttura di campi, definiscila una volta come campo personalizzato e richiamala ovunque.

Creare un campo personalizzato

Crea un field.json nella directory blockstudio/fields/ del tema:

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

Usare il campo personalizzato

Richiamalo in qualsiasi blocco con "type": "custom/cta":

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

I campi CTA vengono incorporati nel blocco. Accedivi direttamente: $a['label'], $a['url'], $a['style'].

Campi personalizzati con prefisso tramite idStructure

Quando usi più volte lo stesso campo personalizzato, aggiungi idStructure per assegnare un prefisso agli ID:

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

I campi della prima CTA diventano primary_label, primary_url, primary_style. Quelli della seconda diventano secondary_label e così via.

Sostituire i valori predefiniti

Personalizza campi specifici quando richiami un campo personalizzato:

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

Le sostituzioni si applicano alla definizione originale. Puoi modificare i valori predefiniti, le etichette, le condizioni o qualsiasi altra proprietà.

Modelli di rendering

Controllare i valori vuoti

La maggior parte dei tipi di campo restituisce false quando è vuota. Verifica sempre prima del rendering:

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

Per i numeri, 0 è un valore valido. Usa un confronto rigoroso se devi distinguere tra “vuoto” e “zero”:

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

Selezione con returnFormat: both

Quando ti servono sia il valore (per la logica) sia l’etichetta (per la visualizzazione):

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; ?>

Attributi data dal campo attributes

Il tipo di campo attributes consente agli utenti di aggiungere attributi data personalizzati:

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>

Variabili CSS dai valori dei campi

Genera proprietà personalizzate CSS dai campi selezionati:

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>

L’output è style="--text-color: #333; --font-size: 1rem;" (gli ID dei campi vengono convertiti in kebab-case). Usa le variabili nel tuo CSS:

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

Passaggi successivi