Zum Inhalt springen

Registrierung

Eigene Blöcke mit Blockstudio zu erstellen, ist ganz einfach. Das Plugin sucht im aktuell aktivierten Theme nach einem Ordner blockstudio. Darin werden alle Unterordner registriert, die eine Datei block.json mit einem Schlüssel blockstudio enthalten.

block.json

JSON
{
  "name": "blockstudio/native",
  "title": "Native Block",
  "category": "text",
  "icon": "star-filled",
  "description": "Native Blockstudio block.",
  "blockstudio": true
}

Vorlage

Der eigene Block wird bisher noch nicht registriert, da ihm eine Vorlage fehlt. Erstelle dazu im selben Ordner wie deine Datei block.json eine index.php. Ihr Inhalt wird automatisch gerendert, wenn dein Block verwendet wird.

PHP
<h1>My first native block.</h1>

Bedingte Logik

Blöcke lassen sich mit dem Schlüssel conditions bedingt registrieren. Er unterstützt alle globalen Variablen, die auch für Attribute verfügbar sind.

Alle Bedingungen anzeigen

Im folgenden Beispiel wird der Block nur registriert, wenn der aktuelle Beitragstyp eine Seite ist:

JSON
{
  "blockstudio": {
    "conditions": [
      [
        {
          "type": "postType",
          "operator": "==",
          "value": "page"
        }
      ]
    ]
  }
}

Plugin-Abhängigkeiten

Blöcke können mit dem Schlüssel pluginDependencies von aktiven WordPress-Plugins abhängen. Ist eines der aufgeführten Plugins inaktiv, wird der Block bei der Registrierung übersprungen.

Abhängigkeiten verwenden WordPress-Plugin-Slugs:

JSON
{
  "blockstudio": {
    "pluginDependencies": [
      "woocommerce",
      "advanced-custom-fields"
    ]
  }
}

Verwende die Objektform, um eine Plugin-Version vorauszusetzen. Für Versionsbeschränkungen gelten dieselben Operatoren wie bei PHP mit version_compare(). Eine Version ohne Operator wird als >= behandelt.

JSON
{
  "blockstudio": {
    "pluginDependencies": {
      "woocommerce": {
        "version": ">6"
      }
    }
  }
}

Eigenes Icon

Eigene SVG-Icons für Blöcke lassen sich wie folgt registrieren:

JSON
{
  "blockstudio": {
    "icon": "<svg></svg>"
  }
}

WordPress erlaubt in seinem eigenen Schlüssel block.json icon keine eigenen SVG-Icons; hier sind nur Dashicons-IDs zulässig.

Standard-WordPress-Blöcke

Blockstudio registriert auch automatisch Standardblöcke von WordPress, die in deinen Verzeichnissen Blockstudio gefunden werden. Jede block.json ohne Schlüssel blockstudio, aber mit einer gültigen Eigenschaft name wird über Gutenbergs native Funktion WordPress register_block_type() registriert.

Das bedeutet: Du kannst mit @wordpress/create-block erstellte Blöcke direkt in deinem Ordner blockstudio/ ablegen. Sie werden dann zusammen mit deinen Blockstudio-Blöcken automatisch registriert. Ein separater Plugin-Registrierungscode ist nicht nötig.

Code
blockstudio/
├── hero/
│   ├── block.json          ← Blockstudio block (has "blockstudio" key)
│   └── index.twig
├── my-js-block/
│   ├── block.json          ← Standard WP block (no "blockstudio" key)
│   ├── index.js            ← Compiled editor script
│   ├── index.css
│   ├── style-index.css
│   └── render.php

Erstelle deinen Block mit npx wp-scripts build und lege den Ausgabeordner in dein Verzeichnis Blockstudio. Der Block wird automatisch registriert.

Dasselbe gilt für die ausschließlich mit WordPress 7.0 erstellten PHP-Blöcke: Ein block.json mit Unterstützung für autoRegister und einem render.php benötigt weder Skript noch Build und wird hier wie jeder andere Standardblock registriert. Core beschränkt diesen Weg auf einfache Blöcke mit String-, Integer-, Boolean- und Enum-Attributen. Sobald ein Block innere Blöcke, Rich Text, Medien oder eigene Steuerelemente benötigt, musst du entweder einen clientseitigen Block erstellen oder ihm einen Schlüssel blockstudio geben und bei PHP bleiben.

HTML

Blockstudio verwendet zum Rendern des Icon-Elements einen React-Elementparser. Daher kannst du HTML innerhalb der Icon-Zeichenfolge verwenden.

JSON
{
  "blockstudio": {
    "icon": "<div>:-)</div>"
  }
}

Eigene Pfade

Standardmäßig durchsucht Blockstudio rekursiv den Ordner blockstudio in deinem aktuellen Theme oder Child-Theme nach Blöcken. Dieses Verhalten lässt sich auf zwei Arten ändern.

Filter

PHP
// Custom path within your theme.
add_filter('blockstudio/path', function () {
    return get_template_directory() . '/blocks';
});

// Custom path within a plugin.
add_filter('blockstudio/path', function () {
    return WP_PLUGIN_DIR . '/my-custom-plugin/blocks';
});

Bei zusammengesetzten oder virtuellen Dateisystemen solltest du eine logische Suchquelle verwenden, anstatt unabhängige Pfade für übergeordnete und Overlay-Verzeichnisse hinzuzufügen. Logische Quellen unterstützen die Überschattung einzelner Pfade, geerbte benachbarte Dateien, Löschungen, Cache-Identität und Herkunftsinformationen. Siehe Logische Suchquellen.

Instanzen

Wenn die obigen Optionen nicht ausreichen, kannst du die Klasse Blockstudio\Build für beliebige Ordner instanziieren:

PHP
add_action('init', function () {
  Blockstudio\Build::init([
    'dir' => get_template_directory() . '/client-blocks'
  ]);
});

Metadaten filtern

Metadaten lassen sich vor der Registrierung des Blocks mit dem Filter blockstudio/blocks/meta filtern:

PHP
add_filter('blockstudio/blocks/meta', function ($meta, $block) {
    if (str_starts_with($block['name'], 'marketing')) {
        $meta['icon'] = 'megaphone';
    }
    return $meta;
}, 10, 2);

Das obige Beispiel wird intern verwendet, damit alle Elemente der Bibliothek Blockstudio dasselbe Icon erhalten.