Przejdź do treści

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.

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

Dostępne typy zapytań korzystają wewnętrznie z tych funkcji WordPress:

Zapytanie Funkcja
posts get_posts
users get_users
terms get_terms

Argumenty

Niestandardowe argumenty można przekazać za pomocą atrybutu arguments:

JSON
{
  "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:

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

Tryb pobierania

Włącz dynamiczne wyszukiwanie za pomocą opcji fetch:

JSON
{
  "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:

JSON
{
  "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):

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

Format zwracanych danych

JSON
{
  "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:

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

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ę:

PHP
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:

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

Dane zewnętrzne

Pobierz dane ze źródła zewnętrznego:

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

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.

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

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.