Zum Inhalt springen

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.

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

Verfügbare Abfragetypen verwenden intern diese WordPress-Funktionen:

Abfrage Funktion
posts get_posts
users get_users
terms get_terms

Argumente

Benutzerdefinierte Argumente können über das Attribut arguments übergeben werden:

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

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

Abrufmodus

Aktiviere die dynamische Suche mit der Option fetch:

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

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

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

Rückgabeformat

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

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

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:

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

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

Externe Daten

Rufe Daten aus einer externen Quelle ab:

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

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.

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

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.