Wypełnianie opcji
Zamiast podawać różne typy pól, takie jak wpisy, użytkownicy lub taksonomie, Blockstudio umożliwia modułowe wypełnianie danych bezpośrednio z block.json. Ta funkcja obsługuje pola typów select, radio, checkbox, color i gradient.
Dane można wypełniać na cztery sposoby:
- Zapytanie – Zwraca wyniki zapytania o wpisy, użytkowników lub taksonomie
- Pobieranie – Zwraca wyniki ze źródła zewnętrznego
- Funkcja – Zwraca wyniki z funkcji niestandardowej
- Niestandardowe – Zwraca wyniki z niestandardowego zbioru danych
Zapytanie
W trybie zapytania można wypełniać pola Wpisy, Użytkownicy lub Taksonomie.
{
"$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"
}
}
]
}
}
Dostępne typy zapytań korzystają wewnętrznie z tych funkcji WordPress:
Argumenty
Niestandardowe argumenty można przekazać za pomocą atrybutu arguments:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "jobs",
"numberposts": "20"
}
}
}
]
}
}
Format zwracanych danych
Domyślnie Blockstudio zwraca:
| Zapytanie | Wartość | Etykieta |
|---|---|---|
posts |
obiekt wpisu | post_title |
users |
obiekt użytkownika | display_name |
terms |
obiekt taksonomii | name |
Dostosuj odpowiedź za pomocą 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"
}
}
}
]
}
}
Tryb pobierania
Włącz dynamiczne wyszukiwanie za pomocą opcji fetch:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"fetch": true,
"arguments": {
"post_type": "posts",
"numberposts": "20"
}
}
}
]
}
}
Włącza to stylisedUi i początkowo pobiera pierwszych 20 wpisów. Wpisywanie w polu wyboru wyszukuje wpisy z użyciem argumentu s.
Funkcja
Użyj niestandardowej funkcji, aby wypełnić opcje:
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types"
}
}
]
}
}
Argumenty
Przekaż argumenty jako tablicę (wewnętrznie używana jest funkcja call_user_func_array):
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"]
}
}
]
}
}
Format zwracanych danych
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"],
"returnFormat": {
"value": "name",
"label": "label"
}
}
}
]
}
}
Łączenie opcji
Połącz opcje statyczne z danymi wypełnianymi dynamicznie:
{
"blockstudio": {
"attributes": [
{
"id": "users",
"type": "radio",
"label": "Users",
"options": [
{
"value": "administrators",
"label": "Administrators"
},
{
"value": "editors",
"label": "Editors"
}
],
"populate": {
"type": "query",
"query": "users",
"position": "before"
}
}
]
}
}
Opcja position (before lub after) określa, gdzie względem opcji statycznych pojawią się opcje wypełniane dynamicznie.
Ostrzeżenie
Łączenie opcji i danych wypełnianych dynamicznie nie jest obsługiwane w trybie fetch.
Dane niestandardowe
Twórz wielokrotnego użytku zbiory danych za pomocą filtra blockstudio/blocks/attributes/populate. Filtr otrzymuje jeden argument: tablicę wszystkich niestandardowych zbiorów danych, uporządkowanych według klucza nazwy. Dodaj zbiór pod wybranym kluczem i zwróć tablicę:
add_filter('blockstudio/blocks/attributes/populate', function($options) {
$options['customData'] = [
['value' => '1', 'label' => 'Option 1'],
['value' => '2', 'label' => 'Option 2'],
];
return $options;
});
Następnie odwołaj się do klucza w bloku:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "custom",
"custom": "customData"
}
}
]
}
}
Dane zewnętrzne
Pobierz dane ze źródła zewnętrznego:
{
"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"
}
}
}
]
}
}
Do urlSearch jest dołączany wyszukiwany termin.
Argumenty dynamiczne
Argumenty wypełniania mogą odwoływać się do innych atrybutów bloku za pomocą składni {attributes.*}. Gdy wskazany atrybut się zmieni, pole automatycznie ponownie pobiera dostępne opcje.
{
"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
}
}
}
]
}
}
Działa to ze wszystkimi typami wypełniania (query, function, custom). Każda wartość konfiguracji wypełniania zawierająca {attributes.*} jest rozwiązywana po stronie klienta na podstawie bieżącej wartości atrybutu przed uruchomieniem zapytania.
Odwołania korzystają z wartości zapisanych w edytorze. W przypadku opcji wyboru użyj {attributes.post_type.value}, aby uzyskać jej wartość, lub {attributes.post_type.label}, aby uzyskać etykietę; returnFormat steruje wartością szablonu, a nie zapisaną postacią danych edytora.
Zagnieżdżone argumenty są rozwiązywane bez serializowania ich do ciągu szablonu.
Argument składający się z jednego symbolu zastępczego zachowuje swój typ, w tym liczby, wartości logiczne, tablice i obiekty. Symbol zastępczy osadzony w innym tekście daje ciąg znaków. Brakujące odwołania pozostają niezmienione, a wartości w cudzysłowach lub wielowierszowe są przekazywane w całości.
Wywołania zwrotne funkcji zachowują swoje pozycyjne listy argumentów. Edytor dodaje argumenty wyszukiwania WordPress tylko do funkcji populate query, a nie do wywołań funkcji.
Renderowanie zależnych opcji wyboru
Opcje zależne nie są ładowane podczas rejestrowania bloku, ponieważ każda instancja bloku może mieć inne argumenty. Renderowanie korzysta z zapisanej opcji zamiast odrzucać ją z powodu pustej listy opcji. Wywołanie zwrotne populate nie jest ponownie wykonywane na stronie.
Nadal obowiązuje ustawienie pola returnFormat:
returnFormat |
Pojedynczy wybór | Wielokrotny wybór |
|---|---|---|
value (domyślnie) |
Zapisana wartość, na przykład "a" |
Tablica zapisanych wartości, na przykład ["a", "b"] |
label |
Zapisana etykieta | Tablica zapisanych etykiet |
both |
Zapisana opcja {value, label} |
Tablica zapisanych opcji |
W przypadku wyborów wypełnianych przez zapytanie wartości nadal są rozwiązywane do odpowiadającego im obiektu wpisu, użytkownika lub terminu WordPress, chyba że populate.returnFormat.value ma wartość "id". Etykiety pochodzą z zapisanego wyboru. Jeśli zaimportowany wybór nie ma etykiety, jego wartość jest używana jako etykieta. Pasująca opcja statyczna zadeklarowana w options ma pierwszeństwo przed zapisaną opcją, więc obowiązuje jej bieżąca etykieta.
Puste wybory pozostają false (lub przyjmują skonfigurowaną dla pola wartość fallback). Nie zmienia to walidacji zwykłych opcji statycznych: zapisana wartość, której nie ma już na statycznej liście opcji, nadal zwraca false.
Wybory dynamiczne również zachowują wybory default i fallback, gdy ich opcje są odroczone. W przypadku wyboru pojedynczego użyj wartości skalarnej, opcji {value, label} lub tablicy zawierającej jedną z nich. Wartość skalarna jest używana jako etykieta, chyba że pasuje do zadeklarowanej opcji statycznej. Obiekt opcji zachowuje podaną etykietę; pasująca opcja statyczna ma pierwszeństwo. Na serwerze nie jest uruchamiane żadne wywołanie zwrotne w celu wypełnienia, by wyszukać te wartości domyślne.