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.
{
"$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:
Argomenti
Gli argomenti personalizzati si possono passare usando l’attributo arguments:
{
"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:
{
"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:
{
"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:
{
"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):
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"]
}
}
]
}
}
Formato di restituzione
{
"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:
{
"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:
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:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "custom",
"custom": "customData"
}
}
]
}
}
Dati esterni
Recuperate dati da una fonte esterna:
{
"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.
{
"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.