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
{
"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.
<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.
Im folgenden Beispiel wird der Block nur registriert, wenn der aktuelle Beitragstyp eine Seite ist:
{
"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:
{
"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.
{
"blockstudio": {
"pluginDependencies": {
"woocommerce": {
"version": ">6"
}
}
}
}
Eigenes Icon
Eigene SVG-Icons für Blöcke lassen sich wie folgt registrieren:
{
"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.
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.
{
"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
// 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:
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:
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.