Zum Inhalt springen

Erweiterungen

Mit Erweiterungen kannst du jeden registrierten Block in deiner WordPress-Installation mithilfe einer einfachen, auf .json basierenden API erweitern, ähnlich der block.json-Konfiguration. Das funktioniert mit Core-Blöcken, Blöcken von Drittanbietern und mit Blockstudio erstellten Blöcken.

Alle Feldtypen lassen sich zu jedem Block hinzufügen; die Daten werden in den Attributen des Blocks gespeichert. Für Erweiterungen stehen alle Funktionen von Attributen zur Verfügung, darunter Filtern, Deaktivieren, Bedingungslogik und Optionen befüllen.

Erweiterungstypen

Erweiterte Werte lassen sich vielseitig nutzen:

  • class: Füge dem Block eine Klasse hinzu, die den Attributwert verwendet
  • style: Füge dem Block Inline-Stile hinzu, die den Attributwert verwenden
  • attributes: Lege einen beliebigen Attributwert direkt am Block fest
  • data attributes: Verwende Erweiterungswerte, um bestimmte Datenattribute festzulegen

Einrichtung

Stell dir folgendes Szenario vor: Du möchtest jedem Core-Block ein Feld select für eine benutzerdefinierte Klasse hinzufügen. Lege dazu einfach diese Datei .json an beliebiger Stelle in deinem Blockordner ab. Sie wird dann automatisch als Erweiterung registriert.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "priority": 10,
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Custom color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

Dadurch erhält jeder Core-Block ein Feld customColor, mit dem du die Textfarbe des Blocks festlegen kannst.

Dateiname

Da keine Vorlage für das Rendering erforderlich ist, braucht eine Erweiterung keine entsprechende index-Datei und muss daher auch nicht block.json heißen. So kannst du alle Erweiterungen bequem in einem einzigen Ordner ablegen. Mehrere Dateien können dieselben Blöcke erweitern, beispielsweise zwei Dateien mit "name": "core/*", die jeweils eigene Felder registrieren.

Schema

Blockstudio stellt ein eigenes JSON-Schema für Erweiterungskonfigurationen bereit:

Erweiterungsschema anzeigen

Name

Die Eigenschaft name des Konfigurationsobjekts legt fest, welche Blöcke erweitert werden sollen. Je nach Bedarf gibt es drei Möglichkeiten:

  • blockName: Ein einzelner Blockname, e.g. core/paragraph
  • [blockNameA, blockNameB]: Ein Array mit Blocknamen, e.g. ["core/paragraph", "core/heading"]
  • core/*: Ein Platzhalter zum Erweitern aller Blöcke eines bestimmten Typs

Jeder Name, der mit einem Sternchen endet, ist ein Präfix-Wildcard, nicht nur core/*. Die folgende Erweiterung gilt für jeden Block, dessen Name mit my-plugin/ beginnt, einschließlich mit Blockstudio erstellter Blöcke:

JSON
{
  "name": "my-plugin/*",
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

Blöcke ausschließen

Verwende ein Array auf oberster Ebene exclude, um Blöcke zu überspringen, die andernfalls auf name passen würden:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "exclude": ["core/button", "core/image"],
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

Ausschlüsse verwenden dieselbe Übereinstimmung mit exakten Namen und Präfixen mit abschließendem * wie name. Sie haben Vorrang vor einzelnen Namen, Namenslisten und Wildcards. Ein ausgeschlossener Block erhält weder die Editor-Felder der Erweiterung noch deren Frontend-Attribute oder Assets. Andere passende Erweiterungen sind davon nicht betroffen. Lass exclude weg oder verwende ein leeres Array, um das bestehende Verhalten beizubehalten.

Schlüssel Blockstudio

Wie bei der Verwendung von block.json für benutzerdefinierte Blöcke muss die Eigenschaft blockstudio im Konfigurationsobjekt vorhanden und auf true gesetzt sein, wobei extend gilt.

Position

Standardmäßig werden Erweiterungen in einem eigenen Tab der Block-Inspektor-Seitenleiste angezeigt. Mit der Eigenschaft group kannst du sie an eine andere Position verschieben:

  • settings: Die Standardposition
  • styles: Der Tab „Stile“
  • advanced: Der Tab „Erweitert“
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

Priorität

Mit der Eigenschaft priority legst du die Reihenfolge fest, in der Erweiterungen gerendert werden. Erweiterungen mit höherer Priorität werden später gerendert. Lege sie wie im Einrichtungsbeispiel auf der obersten Ebene der Datei oder innerhalb von extend fest:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": { "priority": 10 },
    "attributes": []
  }
}

Wenn beide festgelegt sind, hat blockstudio.extend.priority Vorrang.

Attribute

Weitere Informationen zur Funktionsweise von Attributen findest du im Abschnitt zu Attributen.

Wichtig ist bei Attributen in Erweiterungen nur die Eigenschaft set. Mit ihr wird der Attributwert einem der Erweiterungstypen zugewiesen.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Heading color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

Werte abrufen

Mit der Punktnotation in geschweiften Klammern rufst du den Wert eines Attributs ab.

Verschachtelte Werte lassen sich ebenfalls abrufen, wenn Attribute nicht nur einen einzelnen Wert zurückgeben, zum Beispiel wenn du bei Feldtypen mit Optionen das Rückgabeformat auf both setzt.

JSON
{
  "attributes": [
    {
      "id": "customColor",
      "type": "select",
      "label": "Heading color",
      "options": [
        {
          "value": "#f00",
          "label": "Red"
        },
        {
          "value": "#00f",
          "label": "Blue"
        }
      ],
      "returnFormat": "both",
      "set": [
        {
          "attribute": "style",
          "value": "color: {attributes.customColor.value}"
        },
        {
          "attribute": "data-color",
          "value": "{attributes.customColor.label}"
        }
      ]
    }
  ]
}

Das obige Beispiel setzt das Attribut style abhängig vom Wert auf color: #f00 oder color: #00f und das Attribut data-color auf Red oder Blue.

Derzeit lassen sich in Definitionen von set nur Werte des aktuellen Attributs verwenden. Möglicherweise kommt später die Möglichkeit hinzu, Werte anderer Attribute zu nutzen.

Arrays

Bei Arrays wird die Eigenschaft set auf jedes Element des Arrays angewendet.

Jeder Eintrag fügt seine eigene Klasse oder Stildefinition hinzu. Jedes andere Attribut enthält einen einzelnen Wert, daher überschreibt jeder Eintrag den vorherigen und der letzte gewinnt. Setze join auf true, damit stattdessen die Ergebnisse aller Einträge geschrieben werden, durch Leerzeichen getrennt und ohne leere oder doppelte Werte, sodass ein Selektor wie [data-langs~="en"] auf jedes ausgewählte Element zutrifft. join wirkt sich weder auf class und style noch auf Felder aus, die einen einzelnen Wert zurückgeben.

JSON
{
  "id": "langs",
  "type": "checkbox",
  "label": "Languages",
  "options": [
    {
      "value": "en",
      "label": "English"
    },
    {
      "value": "de",
      "label": "German"
    }
  ],
  "set": [
    {
      "attribute": "data-langs",
      "value": "{attributes.langs}",
      "join": true
    }
  ]
}

Wenn du beide Optionen auswählst, wird data-langs="en de" ausgegeben. Ohne join wird data-langs="de" ausgegeben.

Attributfeld

Wenn du das Feld attributes verwendest, ist keine Eigenschaft set erforderlich, da das Feld die Werte automatisch den Attributnamen und -werten zuordnet.

Erweiterungsfelder untersuchen

bs_block_extension_fields('core/paragraph') gibt die Felddefinitionen jeder Erweiterung zurück, die auf einen Block zutrifft. Unter Blöcke untersuchen findest du den Rückgabewert und seine Beziehung zu bs_block_fields().