Optionen befüllen
Anstatt verschiedene Feldtypen wie Beiträge, Benutzer oder Begriffe bereitzustellen, ermöglicht Blockstudio eine flexible Möglichkeit, Daten direkt aus dem block.json zu beziehen. Diese Funktion ist für die Feldtypen select, radio, checkbox, color und gradient verfügbar.
Daten können auf vier Arten befüllt werden:
- Abfrage – Ergebnisse aus einer Beitrags-, Benutzer- oder Begriffsabfrage zurückgeben
- Abruf – Ergebnisse aus einer externen Quelle zurückgeben
- Funktion – Ergebnisse aus einer benutzerdefinierten Funktion zurückgeben
- Benutzerdefiniert – Ergebnisse aus einem benutzerdefinierten Datensatz zurückgeben
Abfrage
Im Abfragemodus können Beiträge, Benutzer oder Begriffe befüllt werden.
{
"$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"
}
}
]
}
}
Verfügbare Abfragetypen verwenden intern diese WordPress-Funktionen:
Argumente
Benutzerdefinierte Argumente können über das Attribut arguments übergeben werden:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "jobs",
"numberposts": "20"
}
}
}
]
}
}
Rückgabeformat
Standardmäßig gibt Blockstudio Folgendes zurück:
| Abfrage | Wert | Bezeichnung |
|---|---|---|
posts |
Beitragsobjekt | post_title |
users |
Benutzerobjekt | display_name |
terms |
Begriffsobjekt | name |
Passe die Rückgabe mit returnFormat an:
{
"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"
}
}
}
]
}
}
Abrufmodus
Aktiviere die dynamische Suche mit der Option fetch:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"fetch": true,
"arguments": {
"post_type": "posts",
"numberposts": "20"
}
}
}
]
}
}
Dadurch werden stylisedUi aktiviert und zunächst die ersten 20 Beiträge abgerufen. Bei der Eingabe im Auswahlfeld werden Beiträge mit dem Argument s gesucht.
Funktion
Verwende eine benutzerdefinierte Funktion, um Optionen zu befüllen:
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types"
}
}
]
}
}
Argumente
Übergib Argumente als Array (intern wird call_user_func_array verwendet):
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"]
}
}
]
}
}
Rückgabeformat
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"],
"returnFormat": {
"value": "name",
"label": "label"
}
}
}
]
}
}
Optionen kombinieren
Kombiniere statische Optionen mit befüllten Daten:
{
"blockstudio": {
"attributes": [
{
"id": "users",
"type": "radio",
"label": "Users",
"options": [
{
"value": "administrators",
"label": "Administrators"
},
{
"value": "editors",
"label": "Editors"
}
],
"populate": {
"type": "query",
"query": "users",
"position": "before"
}
}
]
}
}
Die Option position (before oder after) legt fest, wo befüllte Optionen im Verhältnis zu statischen Optionen erscheinen.
Warnung
Das Kombinieren von Optionen mit befüllten Daten wird im Abrufmodus nicht unterstützt.
Benutzerdefinierte Daten
Erstelle wiederverwendbare Datensätze mit dem Filter blockstudio/blocks/attributes/populate. Der Filter erhält ein einzelnes Argument: ein Array aller benutzerdefinierten Datensätze, gruppiert nach Namen. Füge deinen Datensatz unter einem Schlüssel hinzu und gib das Array zurück:
add_filter('blockstudio/blocks/attributes/populate', function($options) {
$options['customData'] = [
['value' => '1', 'label' => 'Option 1'],
['value' => '2', 'label' => 'Option 2'],
];
return $options;
});
Verweise dann in deinem Block auf den Schlüssel:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "custom",
"custom": "customData"
}
}
]
}
}
Externe Daten
Rufe Daten aus einer externen Quelle ab:
{
"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"
}
}
}
]
}
}
Der Suchbegriff wird an urlSearch angehängt.
Dynamische Argumente
Befüllungsargumente können mithilfe der Syntax {attributes.*} auf andere Blockattribute verweisen. Wenn sich das referenzierte Attribut ändert, ruft das Feld seine Optionen automatisch erneut ab.
{
"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
}
}
}
]
}
}
Das funktioniert mit allen Befüllungstypen (query, function, custom). Jeder Wert in der Befüllungskonfiguration, der {attributes.*} enthält, wird clientseitig mit dem aktuellen Attributwert aufgelöst, bevor die Abfrage ausgeführt wird.
Referenzen verwenden die im Editor gespeicherten Werte. Verwende bei einer Auswahloption {attributes.post_type.value} für ihren Wert oder {attributes.post_type.label} für ihre Beschriftung; returnFormat steuert den Vorlagenwert, nicht die gespeicherte Form im Editor.
Verschachtelte Argumente werden aufgelöst, ohne sie in eine Vorlagenzeichenfolge zu serialisieren.
Ein Argument, das aus einem einzelnen Platzhalter besteht, behält seinen referenzierten Typ bei, einschließlich Zahlen, boolescher Werte, Arrays und Objekte. Ein Platzhalter, der in anderen Text eingebettet ist, ergibt eine Zeichenfolge. Nicht gefundene Referenzen bleiben unverändert, und zitierte oder mehrzeilige Werte werden intakt übergeben.
Funktions-Callbacks behalten ihre Positionsargumentlisten bei. Der Editor fügt WordPress-Suchargumente nur zu query-Populate-Aufrufen hinzu, nicht zu Funktionsaufrufen.
Rendern abhängiger Auswahlen
Abhängige Optionen werden beim Registrieren des Blocks nicht geladen, da jede Blockinstanz andere Argumente haben kann. Beim Rendern wird die gespeicherte Auswahl verwendet, statt sie anhand einer leeren Optionsliste zu verwerfen. Der Populate-Callback wird auf der Benutzeroberfläche nicht erneut ausgeführt.
returnFormat des Feldes gilt weiterhin:
returnFormat |
Einzelauswahl | Mehrfachauswahl |
|---|---|---|
value (Standard) |
Der gespeicherte Wert, zum Beispiel "a" |
Ein Array gespeicherter Werte, zum Beispiel ["a", "b"] |
label |
Das gespeicherte Label | Ein Array gespeicherter Labels |
both |
Die gespeicherte Option {value, label} |
Ein Array gespeicherter Optionen |
Bei Abfragen, die Auswahlen befüllen, werden Werte weiterhin dem entsprechenden WordPress-Beitrags-, Benutzer- oder Begriffsobjekt zugeordnet, sofern populate.returnFormat.value nicht "id" ist. Labels stammen aus der gespeicherten Auswahl. Hat eine importierte Auswahl kein Label, wird ihr Wert als Label verwendet. Eine passende statische Option, die in options definiert ist, hat Vorrang vor der gespeicherten Option, sodass ihr aktuelles Label gilt.
Leere Auswahlen bleiben false (oder der für das Feld konfigurierte Wert fallback). Das ändert nichts an der Validierung gewöhnlicher statischer Optionen: Ein gespeicherter Wert, der nicht mehr in einer statischen Optionsliste enthalten ist, gibt weiterhin false zurück.
Dynamische Auswahlfelder behalten ebenfalls default– und fallback-Auswahlen bei, während ihre Optionen zurückgestellt werden. Verwende für eine Mehrfachauswahl einen Skalarwert, eine Option {value, label} oder ein Array aus beiden. Bei einem Skalar wird sein Wert als Label verwendet, sofern er nicht mit einer deklarierten statischen Option übereinstimmt. Ein Optionsobjekt behält sein angegebenes Label bei; eine passende statische Option hat Vorrang. Serverseitig wird kein Populate-Callback ausgeführt, um diese Standardwerte nachzuschlagen.