Treci la conținut

Popularea opțiunilor

În loc să furnizați tipuri diferite de câmpuri, precum Posts, Users sau Terms, Blockstudio oferă o modalitate modulară de a popula datele direct din block.json. Această funcționalitate este disponibilă pentru tipurile de câmpuri select, radio, checkbox, color și gradient.

Datele pot fi populate în patru moduri:

  • Interogare – Returnează rezultate dintr-o interogare de articole, utilizatori sau termeni
  • Preluare – Returnează rezultate dintr-o sursă externă
  • Funcție – Returnează rezultate dintr-o funcție personalizată
  • Personalizat – Returnează rezultate dintr-un set de date personalizat

Interogare

Când alegeți modul de interogare, pot fi populate Posts, Users sau Terms.

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

Tipurile de interogări disponibile folosesc intern aceste funcții WordPress:

Interogare Funcție
posts get_posts
users get_users
terms get_terms

Argumente

Argumentele personalizate pot fi transmise folosind atributul arguments:

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

Formatul rezultatului

În mod implicit, Blockstudio returnează:

Interogare Valoare Etichetă
posts obiect articol post_title
users obiect utilizator display_name
terms obiect termen name

Personalizați răspunsul cu 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"
          }
        }
      }
    ]
  }
}

Modul de preluare

Activați căutarea dinamică cu opțiunea fetch:

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

Aceasta activează stylisedUi și preia inițial primele 20 de articole. Când scrieți în câmpul de selectare, articolele sunt căutate folosind argumentul s.

Funcție

Folosiți o funcție personalizată pentru a popula opțiunile:

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

Argumente

Transmiteți argumentele ca tablou (folosește intern call_user_func_array):

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

Formatul rezultatului

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

Combinarea opțiunilor

Combinați opțiunile statice cu datele populate:

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

Opțiunea position (before sau after) stabilește unde apar opțiunile populate în raport cu cele statice.

Avertisment

Combinarea opțiunilor cu date populate nu este acceptată în modul fetch.

Date personalizate

Creați seturi de date reutilizabile cu filtrul blockstudio/blocks/attributes/populate. Filtrul primește un singur argument: un tablou cu toate seturile de date personalizate, indexate după nume. Adăugați setul de date sub o cheie și returnați tabloul:

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

Apoi faceți referire la cheie în blocul dvs.:

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

Date externe

Preluați date dintr-o sursă externă:

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

Termenul de căutare este adăugat la urlSearch.

Argumente dinamice

Argumentele de populare pot face referire la alte atribute ale blocului folosind sintaxa {attributes.*}. Când atributul referențiat se schimbă, câmpul își preia automat din nou opțiunile.

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

Funcționează cu toate tipurile de populare (query, function, custom). Orice valoare din configurația de populare care conține {attributes.*} este rezolvată în partea clientului cu valoarea actuală a atributului înainte de rularea interogării.

Referințele folosesc valorile stocate în editor. Pentru o opțiune de selectare, folosiți {attributes.post_type.value} pentru valoarea sa sau {attributes.post_type.label} pentru eticheta sa; returnFormat controlează valoarea șablonului, nu forma stocată în editor.

Argumentele imbricate sunt rezolvate fără a fi serializate într-un șir de șablon. Un argument format dintr-un singur substituent își păstrează tipul referit, inclusiv numerele, valorile booleene, tablourile și obiectele. Un substituent inclus în alt text produce un șir. Referințele lipsă rămân neschimbate, iar valorile între ghilimele sau pe mai multe linii sunt transmise intacte. Funcțiile callback își păstrează listele de argumente poziționale. Editorul adaugă argumente de căutare WordPress doar la funcțiile populate query, nu și la apelurile de funcții.

Randarea selecțiilor dependente

Opțiunile dependente nu sunt încărcate la înregistrarea blocului, deoarece fiecare instanță de bloc poate avea argumente diferite. La randare se folosește selecția salvată în loc să fie eliminată din cauza unei liste goale de opțiuni. Funcția callback de populare nu este executată din nou în partea frontală.

Valoarea returnFormat a câmpului se aplică în continuare:

returnFormat Selecție unică Selecție multiplă
value (implicit) Valoarea salvată, de exemplu "a" O matrice cu valorile salvate, de exemplu ["a", "b"]
label Eticheta salvată O matrice cu etichetele salvate
both Opțiunea {value, label} salvată O matrice cu opțiunile salvate

Pentru selecțiile populate din interogări, valorile se rezolvă în continuare la obiectul postării, utilizatorului sau termenului corespunzător WordPress, cu excepția cazului în care populate.returnFormat.value este "id". Etichetele provin din selecția salvată. Dacă o selecție importată nu are etichetă, valoarea ei este folosită drept etichetă. O opțiune statică declarată în options, care corespunde, are prioritate față de opțiunea salvată, așadar se aplică eticheta ei curentă.

Selecțiile goale rămân false (sau fallback configurat pentru câmp). Acest lucru nu schimbă validarea opțiunilor statice obișnuite: o valoare salvată care nu mai există într-o listă de opțiuni statice returnează în continuare false.

Selecțiile dinamice păstrează, de asemenea, selecțiile default și fallback în timp ce opțiunile lor sunt amânate. Folosiți o valoare scalară, o opțiune {value, label} sau o matrice cu oricare dintre acestea pentru o selecție multiplă. O valoare scalară folosește valoarea sa drept etichetă, cu excepția cazului în care corespunde unei opțiuni statice declarate. Un obiect de tip opțiune păstrează eticheta furnizată; o opțiune statică corespunzătoare are prioritate. Pe server nu se execută nicio funcție de populare pentru a căuta aceste valori implicite.