Vai al contenuto

Popolare le opzioni

Invece di fornire diversi tipi di campo come Post, Utenti o Termini, Blockstudio consente di popolare i dati in modo modulare direttamente da block.json. Questa funzionalità è compatibile con i tipi di campo select, radio, checkbox, color e gradient.

I dati possono essere popolati in quattro modi:

  • Query – Restituisce risultati da una query di post, utenti o termini
  • Fetch – Restituisce risultati da una fonte esterna
  • Funzione – Restituisce risultati da una funzione personalizzata
  • Personalizzato – Restituisce risultati da un set di dati personalizzato

Query

Scegliendo la modalità query, è possibile popolare Post, Utenti o Termini.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/native",
  "title": "Native Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts"
        }
      }
    ]
  }
}

I tipi di query disponibili usano internamente queste funzioni WordPress:

Query Funzione
posts get_posts
users get_users
terms get_terms

Argomenti

Gli argomenti personalizzati si possono passare usando l’attributo arguments:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "jobs",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

Formato di restituzione

Per impostazione predefinita, Blockstudio restituisce:

Query Valore Etichetta
posts oggetto post post_title
users oggetto utente display_name
terms oggetto termine name

Personalizzate la risposta con returnFormat:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          },
          "returnFormat": {
            "value": "id",
            "label": "post_name"
          }
        }
      }
    ]
  }
}

Modalità Fetch

Attivate la ricerca dinamica con l’opzione fetch:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "fetch": true,
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

Questo attiva stylisedUi e recupera inizialmente i primi 20 post. Digitando nel campo di selezione si cercano post usando l’argomento s.

Funzione

Usate una funzione personalizzata per popolare le opzioni:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types"
        }
      }
    ]
  }
}

Argomenti

Passate gli argomenti come array (usa internamente call_user_func_array):

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"]
        }
      }
    ]
  }
}

Formato di restituzione

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"],
          "returnFormat": {
            "value": "name",
            "label": "label"
          }
        }
      }
    ]
  }
}

Combinare le opzioni

Combinate le opzioni statiche con i dati popolati dinamicamente:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "users",
        "type": "radio",
        "label": "Users",
        "options": [
          {
            "value": "administrators",
            "label": "Administrators"
          },
          {
            "value": "editors",
            "label": "Editors"
          }
        ],
        "populate": {
          "type": "query",
          "query": "users",
          "position": "before"
        }
      }
    ]
  }
}

L’opzione position (before o after) determina dove compaiono le opzioni popolate rispetto a quelle statiche.

Avviso

La combinazione di opzioni e dati popolati non è supportata in modalità fetch.

Dati personalizzati

Create set di dati riutilizzabili con il filtro blockstudio/blocks/attributes/populate. Il filtro riceve un solo argomento: un array di tutti i set di dati personalizzati, indicizzati per nome. Aggiungete il vostro set di dati sotto una chiave e restituite l’array:

PHP
add_filter('blockstudio/blocks/attributes/populate', function($options) {
  $options['customData'] = [
    ['value' => '1', 'label' => 'Option 1'],
    ['value' => '2', 'label' => 'Option 2'],
  ];
  return $options;
});

Quindi fate riferimento alla chiave nel vostro blocco:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "custom",
          "custom": "customData"
        }
      }
    ]
  }
}

Dati esterni

Recuperate dati da una fonte esterna:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "select",
        "type": "select",
        "label": "Select",
        "multiple": true,
        "populate": {
          "type": "fetch",
          "arguments": {
            "urlSearch": "https://example.com/wp-json/wp/v2/posts?search="
          },
          "returnFormat": {
            "value": "id",
            "label": "title.rendered"
          }
        }
      }
    ]
  }
}

Il termine di ricerca viene aggiunto a urlSearch.

Argomenti dinamici

Gli argomenti di popolamento possono fare riferimento ad altri attributi del blocco usando la sintassi {attributes.*}. Quando l’attributo referenziato cambia, il campo recupera automaticamente le opzioni.

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post Type",
        "options": [
          { "label": "Pages", "value": "page" },
          { "label": "Posts", "value": "post" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Select Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "{attributes.post_type.value}",
            "numberposts": 10
          }
        }
      }
    ]
  }
}

Funziona con tutti i tipi di popolamento (query, function, custom). Qualsiasi valore nella configurazione di popolamento che contiene {attributes.*} viene risolto lato client con il valore corrente dell’attributo prima dell’esecuzione della query.

I riferimenti usano i valori memorizzati nell’editor. Per un’opzione di selezione, usate {attributes.post_type.value} per il suo valore oppure {attributes.post_type.label} per la sua etichetta; returnFormat controlla il valore del template, non la forma dei dati memorizzati nell’editor.

Gli argomenti nidificati vengono risolti senza serializzarli in una stringa di template. Un argomento costituito da un solo segnaposto mantiene il tipo a cui fa riferimento, inclusi numeri, valori booleani, array e oggetti. Un segnaposto incorporato in altro testo produce una stringa. I riferimenti mancanti restano invariati e i valori tra virgolette o su più righe vengono inviati intatti. Le callback di funzione mantengono i propri elenchi di argomenti posizionali. L’editor aggiunge gli argomenti di ricerca WordPress solo ai populate query, non alle chiamate di funzione.

Rendering delle selezioni dipendenti

Le opzioni dipendenti non vengono caricate quando si registra il blocco, perché ogni istanza del blocco può avere argomenti diversi. Il rendering usa la selezione salvata invece di scartarla a causa di un elenco di opzioni vuoto. La callback di popolamento non viene eseguita di nuovo sul frontend.

Il campo returnFormat continua ad applicarsi:

returnFormat Selezione singola Selezione multipla
value (predefinito) Il valore salvato, ad esempio "a" Un array di valori salvati, ad esempio ["a", "b"]
label L’etichetta salvata Un array di etichette salvate
both L’opzione {value, label} salvata Un array di opzioni salvate

Per le selezioni popolate tramite query, i valori vengono comunque risolti nell’oggetto post, utente o termine corrispondente WordPress, a meno che populate.returnFormat.value non sia "id". Le etichette provengono dalla selezione salvata. Se una selezione importata non ha un’etichetta, il suo valore viene usato come etichetta. Un’opzione statica corrispondente dichiarata in options ha la precedenza sull’opzione salvata, quindi viene applicata la sua etichetta corrente.

Le selezioni vuote restano false (o assumono il valore fallback configurato per il campo). Questo non modifica la convalida delle normali opzioni statiche: un valore salvato che non è più presente in un elenco di opzioni statiche restituisce comunque false.

Le selezioni dinamiche mantengono anche le selezioni default e fallback quando le opzioni sono rinviate. Per una selezione multipla, usate un valore scalare, un’opzione {value, label} o un array di entrambi. Un valore scalare usa il proprio valore come etichetta, a meno che non corrisponda a un’opzione statica dichiarata. Un oggetto opzione conserva l’etichetta fornita; un’opzione statica corrispondente ha la precedenza. Sul server non viene eseguito alcun callback di popolamento per cercare questi valori predefiniti.