Viele beschweren sich über die Hürden, die der Einstieg in die Erstellung von Gutenberg-Blöcken und -Apps mit sich bringt. Die Lernkurve ist steil, was vor allem an der Schwierigkeit liegt, die Entwicklungsumgebung zu installieren und zu konfigurieren. Außerdem sind solide Kenntnisse in JavaScript, Node.js, React und Redux ein Muss für dieses komplexe Rezept.

Das offizielle WordPress-Handbuch für Block-Editoren bietet Entwicklern eine enorme Menge an Informationen, aber es kann sein, dass du dich in diesem Meer von Details verlierst.

Und es ist erwähnenswert, was Matías Ventura, leitender Architekt des Gutenberg-Projekts, in seinem Interview mit WP Tavern berichtet hat:

Auch wenn es Leute gibt, die es schnell lernen können, ist es immer noch eine große Hürde für viele. Ich denke, dass es mehrere Ebenen gibt; die Dokumentation könnte sowohl in der Organisation als auch in der Präsentation um Größenordnungen besser sein. Ich hoffe, wir können da noch viel mehr tun.

Deshalb haben wir beschlossen, ein Schritt-für-Schritt-Tutorial zu erstellen, das unseren Lesern den Einstieg in die Gutenberg-Blockentwicklung erleichtern soll.

Klingt interessant? Dann nichts wie los!

Gutenberg-Block-Entwicklung Voraussetzungen

Für dieses Tutorial brauchst du nur gute Kenntnisse in der Entwicklung von WordPress Plugins und zumindest ein Grundverständnis von HTML, CSS, JavaScript und React.

Wird dies ein ehrgeiziges Projekt sein? Und ob es das ist!

Es war nicht einfach, den richtigen Kompromiss zwischen Vollständigkeit und Einfachheit zu finden und zu entscheiden, welche Themen wir aufnehmen und welche wir weglassen.

Wir hoffen, dass fortgeschrittene Leserinnen und Leser uns verzeihen werden, wenn wir auf bestimmte Konzepte wie React State, Redux Store, High Order Components usw. nicht näher eingehen. Diese Themen benötigen mehr Platz und Aufmerksamkeit und sind für Anfänger in der Blockentwicklung wahrscheinlich zu fortgeschritten (es sei denn, du bist ein React-Entwickler).

Aus demselben Grund werden wir einige der fortgeschritteneren Themen im Zusammenhang mit der Entwicklung von Gutenberg-Blöcken, wie dynamische Blöcke und Metaboxen, nicht behandeln.

Mit dem Wissen, das du am Ende dieses Artikels erworben hast, kannst du sofort loslegen und produktiv sein.

Wenn du erst einmal mit der Blockerstellung angefangen hast, kannst du deine Fähigkeiten weiter ausbauen und noch fortgeschrittenere Gutenberg-Blöcke selbst erstellen.

Der Einstieg in die Gutenberg-Blockentwicklung kann anfangs einschüchternd sein... 😵‍💫 Aber keine Angst! Dieser komplette Leitfaden für Anfänger bringt dich auf den richtigen Weg 🙏Click to Tweet

 

Was ist ein Gutenberg-Block?

Seit seiner ersten Veröffentlichung im Dezember 2018 wurde der Block-Editor in jeder Hinsicht stark verbessert: leistungsfähigere APIs, eine fortschrittlichere Benutzeroberfläche, verbesserte Benutzerfreundlichkeit, jede Menge neue Blöcke, die ersten Implementierungen von Full Site Editing und vieles mehr.

Kurz gesagt: Auch wenn Gutenberg immer noch intensiv weiterentwickelt wird, hat es einen weiten Weg zurückgelegt – und heute ist der Block-Editor ein vollwertiger Kandidat für einen zuverlässigen, funktionalen Seiten- und Website-Builder.

Aus der Sicht eines Entwicklers ist Gutenberg eine React-basierte Single Page Application (SPA), mit der WordPress-Nutzer Inhalte in WordPress erstellen, bearbeiten und löschen können. Das sollte dich jedoch nicht an eine verbesserte Version des traditionellen Inhaltseditors denken lassen.

Das wollen wir klarstellen:

In Gutenberg sind die Inhalte in Blöcke unterteilt, die „Bausteine“, mit denen die Nutzer/innen Beiträge und Seiten oder ihre gesamten Webseiten erstellen können.

Aber was ist eigentlich ein Block?

Uns gefällt die Definition von WordPress:

„Block“ ist ein abstrakter Begriff, der Markup-Einheiten beschreibt, die zusammengesetzt den Inhalt oder das Layout einer Webseite bilden. Die Idee kombiniert Konzepte, die wir heute in WordPress mit Shortcodes, benutzerdefiniertem HTML und Embed Discovery erreichen, zu einer einheitlichen API und einem einheitlichen Nutzererlebnis.

Überschriften, Absätze, Spalten, Bilder, Galerien und alle Elemente, die die Benutzeroberfläche des Editors ausmachen, von Sidebar-Panels bis hin zu den Steuerelementen der Blocksymbolleiste, sind React-Komponenten.

Was sind also React-Komponenten? W3Schools liefert die folgende Definition:

Komponenten sind unabhängige und wiederverwendbare Codebausteine. Sie dienen demselben Zweck wie JavaScript-Funktionen, arbeiten aber isoliert und geben HTML über eine render()-Funktion zurück.

Arbeiten mit Gutenberg-Blöcken in WordPress 5.8.
Arbeiten mit Gutenberg-Blöcken in WordPress 5.8.

Auch wenn Gutenberg ein neues Bearbeitungserlebnis im Vergleich zum klassischen WordPress-Editor bietet, ändert sich die Art und Weise, wie WordPress deine Inhalte in der Datenbank speichert, überhaupt nicht. Das liegt daran, dass Gutenberg eine Anwendung ist, die innerhalb von WordPress arbeitet, aber nicht die Art und Weise verändert, wie das CMS in seinem Kern funktioniert.

Mit Gutenberg erstellte Beiträge (und dazu gehören Beiträge, Seiten und benutzerdefinierte Beitragstypen) werden nach wie vor in der Tabelle wp_posts gespeichert, genau wie im klassischen Editor.

Aber in einem mit Gutenberg erstellten Beitrag findest du zusätzliche Informationen in der Tabelle, die einen grundlegenden Unterschied zwischen Beiträgen, die mit dem klassischen Editor und Gutenberg erstellt wurden, darstellen.

Diese Informationen sehen aus wie HTML-Kommentare und haben eine bestimmte Funktion: Sie grenzen Blöcke ab:

Ein Blogbeitrag in der Code-Editor-Ansicht.
Ein Blogbeitrag in der Code-Editor-Ansicht.

Blockbegrenzer teilen WordPress mit, welcher Block auf dem Bildschirm dargestellt werden soll. Außerdem liefern sie Werte für Blockeigenschaften in einem JSON-Objekt. Diese Props bestimmen, wie der Block auf dem Bildschirm dargestellt werden soll:

Ein Blogbeitrag, der in der Tabelle wp_posts gespeichert ist.
Ein Blogbeitrag, der in der Tabelle wp_posts gespeichert ist.

Einrichten deiner WordPress-Entwicklungsumgebung

Die Einrichtung einer modernen JavaScript-Entwicklungsumgebung erfordert ein solides Wissen über fortschrittliche Technologien wie Webpack, React und JSX, Babel, ESLint usw.

Eingeschüchtert? Das muss nicht sein! Die WordPress-Gemeinde hat bereits leistungsstarke Tools zur Verfügung gestellt, mit denen du die umständliche manuelle Konfiguration vermeiden kannst.

Um die Dinge einfach zu halten, gehen wir in diesem Artikel nicht auf die Transpilierung ein (mit der du dich allerdings vertraut machen solltest, sobald du die Grundlagen der Blockentwicklung gelernt hast). Stattdessen stellen wir dir zwei alternative Tools vor, mit denen du in wenigen Minuten schnell und einfach eine moderne JavaScript-Entwicklungsumgebung einrichten kannst. Es liegt an dir, das Tool zu wählen, das du für dein Projekt am geeignetsten findest.

Das Einrichten einer JavaScript-Entwicklungsumgebung für die Erstellung von Gutenberg-Blöcken erfolgt in drei Schritten:

  1. Node.js und npm installieren
  2. Richte die Entwicklungsumgebung ein
  3. Das Block Plugin einrichten

Lass uns loslegen.

1. Node.js und npm installieren

Bevor du deine Entwicklungsumgebung installierst und deinen ersten Block registrierst, musst du Node.js und den Node-Paketmanager (npm) installieren.

Du kannst Node.js und npm auf verschiedene Arten installieren. Aber zuerst solltest du prüfen, ob die Software bereits auf deinem Rechner installiert ist.

Starte dazu das Terminal und führe den folgenden Befehl aus:

node -v

Wenn das Ergebnis command not found ist, ist Node.js nicht auf deinem Computer installiert und du kannst mit der Installation fortfahren.

Für diesen Artikel haben wir uns für die einfachste Installationsoption entschieden: den Node Installer. Du musst nur die für dein Betriebssystem passende Version herunterladen und den Installationsassistenten starten:

Node.js Downloads Seite.
Node.js Downloads Seite.

Wenn du Node.js installiert hast, führe den Befehl node -v erneut in deinem Terminal aus. Du kannst auch den Befehl npm -v ausführen, um sicherzustellen, dass das npm-Paket verfügbar ist.

Du bist jetzt mit den folgenden Tools ausgestattet:

Im nächsten Schritt installierst du die Entwicklungsumgebung.

2. Einrichten deiner Entwicklungsumgebung

Sobald du die neuesten Versionen von Node.js und npm auf deinem lokalen Rechner hast, brauchst du eine Entwicklungsumgebung für WordPress.

Du kannst entweder eine lokale Entwicklungsumgebung wie DevKinsta verwenden oder das offizielle WordPress Tool nutzen. Werfen wir einen Blick auf beide Optionen.

Option 1: Lokale Entwicklungsumgebung (DevKinsta)

Mit nur wenigen Klicks kannst du WordPress mit DevKinsta, unserem modernen lokalen WordPress Tool, lokal installieren. Oder du entscheidest dich für ein anderes lokales Entwicklungstool, wie MAMP oder XAMPP:

Erstelle eine neue WordPress Webseite in DevKinsta.
Erstelle eine neue WordPress Webseite in DevKinsta.

Option 2: wp-env

Du kannst dich auch für das offizielle Tool wp-env entscheiden, das eine lokale WordPress-Entwicklungsumgebung bereitstellt, die du direkt über die Kommandozeile starten kannst. Noah Alen definiert es wie folgt:

Lokale WordPress-Umgebungen sind jetzt so einfach wie das Ausführen eines einzigen Befehls. wp-env ist ein Zero-Config-Tool für mühelose lokale WordPress-Umgebungen. Es bietet Entscheidungen über Optionen, damit Nutzer/innen WordPress schnell und ohne Zeitverlust einrichten können. Das Ziel ist es, diese Umgebungen für alle leicht zugänglich zu machen – egal ob du Entwickler, Designer, Manager oder sonst jemand bist.

Wenn du dich entscheidest, es auszuprobieren, erfordert die Installation von wp-env nur wenig Aufwand. Folge einfach diesen Schritten:

Schritt 1: Bestätige die Installation von Docker und Node.js

Um die technischen Voraussetzungen zu erfüllen, musst du zunächst sowohl Docker als auch Node.js auf deinem Computer installiert haben. Denn wp-env erstellt eine Docker-Instanz, auf der eine WordPress Webseite läuft. Alle Änderungen, die du am Code vornimmst, werden sofort auf die WordPress-Instanz übertragen.

Schritt 2: Installiere @wordpress/env über die Kommandozeile

Wenn Docker und Node.js auf deinem Computer laufen, kannst du fortfahren und die WordPress-Entwicklungsumgebung installieren.

Du kannst wp-env entweder global oder lokal installieren. Um es global zu installieren, musst du den folgenden Befehl aus dem Plugins-Verzeichnis ausführen (mehr dazu im Kasten „Wichtig“ weiter unten):

npm install -g @wordpress/env

Lass uns das mal aufschlüsseln:

Um zu bestätigen, dass wp-env erfolgreich installiert wurde, führe den folgenden Befehl aus:

wp-env --version

Du solltest die aktuelle wp-env Version sehen. Das bedeutet, dass du die Umgebung jetzt mit dem folgenden Befehl aus dem Ordner deines Plugins starten kannst:

wp-env start

Du kannst das WordPress Dashboard über die folgende Adresse aufrufen:

Die Standardanmeldedaten lauten wie folgt:

Richte dein Block Plugin ein

Jetzt brauchst du ein Block Plugin, auf dem du aufbauen kannst. Anstatt ein Block Plugin mit allen notwendigen Dateien und Ordnern manuell zu erstellen, kannst du einfach ein Dev-Tool ausführen, das alle Dateien und Konfigurationen enthält, die du für die Blockentwicklung brauchst.

Auch hier hast du mehrere Optionen zur Auswahl. Schauen wir uns beide an.

Option 1: Einrichten eines Block Plugins mit @wordpress/create-block

@wordpress/create-block ist das offizielle Zero Configuration Tool zur Erstellung von Gutenberg-Blöcken:

Block erstellen ist eine offiziell unterstützte Möglichkeit, Blöcke für die Registrierung eines Blocks für ein WordPress Plugin zu erstellen. Es bietet ein modernes Build-Setup ohne Konfiguration. Es generiert PHP-, JS- und CSS-Code und alles andere, was du brauchst, um das Projekt zu starten.

Es ist weitgehend von create-react-app inspiriert. Ein großes Lob an @gaearon, das gesamte Facebook-Team und die React-Community.

Sobald deine lokale Umgebung einsatzbereit ist, kannst du einen Startblock einrichten, indem du einfach den Befehl npx @wordpress/create-block ausführst. Er stellt dir alle Dateien und Ordner zur Verfügung, die du brauchst, um das Plugin-Gerüst zu erstellen und einen neuen Block zu registrieren.

Lass uns einen Test machen, um zu sehen, wie es funktioniert.

Navigiere in deinem Command Line Tool zum Verzeichnis /wp-content/plugins/ und führe den folgenden Befehl aus:

npx @wordpress/create-block my-first-block

Wenn du zur Bestätigung aufgefordert wirst, gib y ein, um fortzufahren:

Erstelle einen Block mit @wordpress/create-block.
Erstelle einen Block mit @wordpress/create-block.

Der Vorgang dauert nur wenige Augenblicke. Wenn er abgeschlossen ist, solltest du die folgende Antwort erhalten:

Das Plugin für den Block wurde erstellt.
Das Plugin für den Block wurde erstellt.

Und das war’s schon!

Starte nun deine WordPress-Entwicklungsumgebung und rufe den Bildschirm Plugins im WordPress-Dashboard auf. Ein neues Plugin mit dem Namen „My First Block“ sollte zu deiner Plugin-Liste hinzugefügt worden sein:

Das Block Plugin wurde erfolgreich installiert.
Das Block Plugin wurde erfolgreich installiert.

Aktiviere das Plugin bei Bedarf, erstelle einen neuen Blogbeitrag, scrolle im Block-Inserter nach unten zum Abschnitt Widgets und wähle deinen neuen Block aus:

Ein Beispielblock, der mit @wordpress/create-block erstellt wurde.
Ein Beispielblock, der mit @wordpress/create-block erstellt wurde.

Gehe nun zurück zum Terminal und ändere das aktuelle Verzeichnis in my-first-block:

cd my-first-block

Dann führe den folgenden Befehl aus:

npm start

So kannst du das Plugin im Entwicklungsmodus ausführen. Um den Produktionscode zu erstellen, solltest du den folgenden Befehl verwenden:

npm run build

Option 2: Einrichten eines Block Plugins mit create-guten-block

create-guten-block ist ein Tool eines Drittanbieters für die Erstellung von Gutenberg-Blöcken:

create-guten-block ist ein Zero-Configuration Dev-Toolkit (#0CJS), mit dem du in wenigen Minuten WordPress Gutenberg-Blöcke entwickeln kannst, ohne React, Webpack, ES6/7/8/Next, ESLint, Babel usw. konfigurieren zu müssen.

Genau wie das offizielle create-block Tool basiert create-guten-block auf create-react-app und hilft dir dabei, dein erstes Block Plugin zu erstellen, ohne dass du dich anstrengen musst.

Das Toolkit enthält alles, was du brauchst, um ein modernes WordPress Plugin zu erstellen, darunter Folgendes:

 

  • Support für React, JSX und ES6-Syntax.
  • webpack Dev/Production Build-Prozess hinter der Szene.
  • Sprachliche Extras, die über ES6 hinausgehen, wie z. B. der Objekt-Spread-Operator.
  • Automatische CSS-Präfixe, sodass du weder -webkit noch andere Präfixe benötigst.
  • Ein Build-Skript zum Bündeln von JS, CSS und Bildern für die Produktion mit Source-Maps.
  • Problemlose Updates für die oben genannten Tools mit einer einzigen Abhängigkeit cgb-scripts.

 

Beachte den folgenden Vorbehalt:

Der Nachteil ist, dass diese Tools so vorkonfiguriert sind, dass sie auf eine bestimmte Weise funktionieren. Wenn dein Projekt mehr Anpassungen braucht, kannst du es „auswerfen“ und anpassen, aber dann musst du diese Konfiguration beibehalten.

Sobald du eine lokale WordPress Webseite zur Verfügung hast, starte dein Command Line Tool, navigiere zum Ordner /wp-content/plugins deiner Installation und führe den folgenden Befehl aus:

npx create-guten-block my-first-block

Du musst ein oder zwei Minuten warten, während die Projektstruktur erstellt und die Abhängigkeiten heruntergeladen werden:

Erstellen eines Gutenberg-Blocks mit create-guten-block.
Erstellen eines Gutenberg-Blocks mit create-guten-block.

Wenn der Vorgang abgeschlossen ist, solltest du den folgenden Bildschirm sehen:

Gutenberg-Block erfolgreich mit create-guten-block erstellt.
Gutenberg-Block erfolgreich mit create-guten-block erstellt.

Das nächste Bild zeigt die Projektstruktur, wenn das Terminal in Visual Studio Code läuft:

Das Block Plugin in Visual Studio Code.
Das Block Plugin in Visual Studio Code.

Gehe nun zurück zu deinem WordPress Dashboard. Auf dem Plugin-Bildschirm sollte ein neuer Eintrag zu sehen sein – es ist das my-first-block Plugin:

Der Plugins-Bildschirm mit einem neuen Plugin, das mit create-guten-block erstellt wurde.
Der Plugins-Bildschirm mit einem neuen Plugin, das mit create-guten-block erstellt wurde.

Aktiviere das Plugin und gehe zurück zum Terminal. Ändere das aktuelle Verzeichnis in my-first-block und führe npm start aus:

cd my-first-block
npm start

Du solltest die folgende Antwort erhalten:

npm gestartet.
npm gestartet.

Auch hier kannst du das Plugin im Entwicklungsmodus ausführen. Um den Produktionscode zu erstellen, solltest du:

npm run build

Aktiviere das Plugin, erstelle einen neuen Beitrag oder eine neue Seite, durchsuche deine Blöcke und wähle deinen neuen Gutenberg-Block aus:

Ein neuer Block, der mit create-guten-block erstellt wurde.
Ein neuer Block, der mit create-guten-block erstellt wurde.

Für einen ausführlicheren Überblick oder bei Fehlern kannst du in der Dokumentation von Ahmad Awais nachschlagen.

Ein Rundgang durch das Starter-Block-Gerüst

Für welches der beiden Dev-Tools – create-block oder create-guten-block – du dich auch entscheidest, du hast jetzt ein Block-Gerüst, das du als Ausgangspunkt für die Erstellung eines Block-Plugins verwenden kannst.

Aber was genau ist ein Blockgerüst?

Block Scaffolding ist ein kurzer Begriff, der die unterstützende Verzeichnisstruktur beschreibt, die du brauchst, damit WordPress einen Block erkennt. Normalerweise enthält dieses Verzeichnis Dateien wie index.php, index.js, style.css und andere – die wiederum Aufrufe wie register_block_type enthalten.

Wir haben uns für das offizielle Create Block dev-Tool entschieden, da es im Block Editor Handbook verwendet wird. Aber auch wenn du dich für ein Tool eines Drittanbieters wie create-guten-block entscheidest, wird sich deine Erfahrung nicht allzu sehr unterscheiden.

Deshalb wollen wir uns das Tool create-block genauer ansehen.

Ein genauerer Blick auf das Create Block Dev-Tool

Wie bereits erwähnt, ist Create Block das offizielle Kommandozeilentool zur Erstellung von Gutenberg-Blöcken. Wenn du @wordpress/create-block in deinem Terminal ausführst, werden die PHP-, JS- und SCSS-Dateien und der Code generiert, die für die Registrierung eines neuen Blocktyps benötigt werden:

npx @wordpress/create-block [options] [slug]

Standardmäßig wird ein ESNext Template zugewiesen. Das bedeutet, dass du die nächste Version von JavaScript erhältst, mit dem Zusatz der JSX-Syntax.

Wenn du den Blocknamen weglässt, wird der Befehl im interaktiven Modus ausgeführt, so dass du verschiedene Optionen anpassen kannst, bevor du die Dateien erzeugst:

npx @wordpress/create-block
Ausführen von create-block im interaktiven Modus.
Ausführen von create-block im interaktiven Modus.

Die folgende Abbildung zeigt die Dateistruktur eines Block Plugins, das mit dem offiziellen Create Block Tool erstellt wurde:

Dateien und Ordner eines Block-Plugins, das mit @wordpress/create-block erstellt wurde.
Dateien und Ordner eines Block-Plugins, das mit @wordpress/create-block erstellt wurde.

Schauen wir uns also die wichtigsten Dateien und Ordner unseres neuen Plugins an.

Die Plugin-Datei

Mit der Hauptdatei des Plugins registrierst du den Block auf dem Server:

/**
 * Plugin Name: My First Block
 * Description: Example block written with ESNext standard and JSX support – build step required.
 * Requires at least: 5.8
 * Requires PHP: 7.0
 * Version: 0.1.0
 * Author: The WordPress Contributors
 * License: GPL-2.0-or-later
 * License URI: https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: my-first-block
 *
 * @package create-block
 */
/**
 * Registers the block using the metadata loaded from the `block.json` file.
 * Behind the scenes, it registers also all assets so they can be enqueued
 * through the block editor in the corresponding context.
 *
 * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/
 */
function create_block_my_first_block_block_init() {
	register_block_type( __DIR__ );
}
add_action( 'init', 'create_block_my_first_block_block_init' );

Die Funktion register_block_type registriert einen Blocktyp auf dem Server unter Verwendung der in der Datei block.json gespeicherten Metadaten.

Die Funktion benötigt zwei Parameter:

Im obigen Code wird das Argument für den Blocktyp durch die magic constant  __DIR__ bereitgestellt. Das bedeutet, dass sich die Datei block.json im gleichen Ordner wie die Datei des Plugins befindet.

Die Datei package.json

In der Datei package.json werden JavaScript-Eigenschaften und Skripte für dein Projekt definiert. Hier kannst du deine Projektabhängigkeiten installieren.

Um besser zu verstehen, wofür diese Datei gedacht ist, öffne sie mit deinem bevorzugten Code-Editor:

{
	"name": "my-first-block",
	"version": "0.1.0",
	"description": "Example block written with ESNext standard and JSX support – build step required.",
	"author": "The WordPress Contributors",
	"license": "GPL-2.0-or-later",
	"main": "build/index.js",
	"scripts": {
		"build": "wp-scripts build",
		"format": "wp-scripts format",
		"lint:css": "wp-scripts lint-style",
		"lint:js": "wp-scripts lint-js",
		"start": "wp-scripts start",
		"packages-update": "wp-scripts packages-update"
	},
	"dependencies": {
		"@wordpress/block-editor": "^7.0.1",
		"@wordpress/blocks": "^11.0.1",
		"@wordpress/i18n": "^4.2.1"
	},
	"devDependencies": {
		"@wordpress/scripts": "^18.0.0"
	}
}

Die Eigenschaft scripts ist ein Wörterbuch mit Befehlen, die zu verschiedenen Zeiten im Lebenszyklus eines Pakets mit npm run [cmd] ausgeführt werden.

In diesem Artikel werden wir die folgenden Befehle verwenden:

dependencies und devDependencies sind zwei Objekte, die einen Paketnamen auf eine Version abbilden. dependencies werden in der Produktion benötigt, während devDependences nur für die lokale Entwicklung benötigt werden (mehr dazu).

Die einzige Standardabhängigkeit ist das Paket @wordpress/scripts, das als „eine Sammlung von wiederverwendbaren Skripten für die WordPress-Entwicklung“ definiert ist.

Die block.json-Datei

Seit WordPress 5.8 ist die Metadaten-Datei block.json der klassische Weg, um Blocktypen zu registrieren.

Eine block.json-Datei bietet mehrere Vorteile, darunter eine bessere Leistung und eine bessere Sichtbarkeit im WordPress Plugins Directory:

Wenn Themes Lazy Loading Assets unterstützen, wird das Enqueuing von Assets bei Blöcken, die mit block.json registriert sind, von vornherein optimiert. Die Frontend-CSS- und JavaScript-Assets, die in den style oder script-Eigenschaften aufgelistet sind, werden nur dann in die Warteschlange gestellt, wenn der Block auf der Seite vorhanden ist, was zu einer geringeren Seitengröße führt.

Wenn du den Befehl @wordpress/create-block ausführst, wird die folgende block.json-Datei erstellt:

{
	"apiVersion": 2,
	"name": "create-block/my-first-block",
	"version": "0.1.0",
	"title": "My First Block",
	"category": "widgets",
	"icon": "smiley",
	"description": "Example block written with ESNext standard and JSX support – build step required.",
	"supports": {
		"html": false
	},
	"textdomain": "my-first-block",
	"editorScript": "file:./build/index.js",
	"editorStyle": "file:./build/index.css",
	"style": "file:./build/style-index.css"
}

Hier ist die vollständige Liste der Standardeigenschaften:

Zusätzlich zu den oben aufgeführten Eigenschaften kannst (und wirst) du ein attributes-Objekt definieren, das Informationen über die in deinem Block gespeicherten Daten enthält. In deiner block.json kannst du eine beliebige Anzahl von Attributen in Schlüssel/Wert-Paaren festlegen, wobei der Schlüssel der Attributname und der Wert die Attributdefinition ist.

Sieh dir das folgende Beispiel für eine Attributdefinition an:

"attributes": {
	"content": {
		"type": "array",
		"source": "children",
		"selector": "p"
	},
	"align": {
		"type": "string",
		"default": "none"
	},
	"link": { 
		"type": "string", 
		"default": "https://kinsta.com" 
	}
},

Wir werden später in diesem Artikel näher auf die Datei block.json eingehen, aber du kannst auch im Handbuch für den Block-Editor nachschauen, um mehr über die Metadaten und Attribute der Datei block.json zu erfahren.

Der src-Ordner

Der Ordner src ist der Ort, an dem die Entwicklung stattfindet. In diesem Ordner findest du die folgenden Dateien:

index.js

Die Datei index.js ist dein Startpunkt. Hier importierst du Abhängigkeiten und registrierst den Blocktyp auf dem Server:

import { registerBlockType } from '@wordpress/blocks';
import './style.scss';
import Edit from './edit';
import save from './save';

registerBlockType('create-block/my-first-block', {
	edit: Edit,
	save,
});

Die erste Anweisung importiert die Funktion registerBlockType aus dem Paket @wordpress/blocks. Die folgenden Importanweisungen importieren das Stylesheet sowie die Funktionen Edit und save.

Mit der Funktion registerBlockType wird die Komponente auf dem Client registriert. Die Funktion nimmt zwei Parameter entgegen: einen namespace/block-name (derselbe wie auf dem Server registriert) und ein Block-Konfigurationsobjekt.

Die Funktion Edit liefert die Blockschnittstelle, wie sie im Blockeditor dargestellt wird, während die Funktion save die Struktur liefert, die serialisiert und in der Datenbank gespeichert wird (mehr dazu).

edit.js

In edit.js baust du die Blockverwaltungsoberfläche auf:

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit() {
	return (
		<p {...useBlockProps()}>
			{__('My First Block – hello from the editor!', 'my-first-block')}
		</p>
	);
}

Zunächst importiert es die Funktion __ aus dem Paket @wordpress/i18n (dieses Paket enthält eine JavaScript-Version der Übersetzungsfunktionen), den React-Hook useBlockProps und die Datei editor.scss.

Danach exportiert sie die React-Komponente (lies mehr über Import– und Export-Anweisungen).

save.js

In der Datei save.js bauen wir die Blockstruktur auf, die in der Datenbank gespeichert werden soll:

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';

export default function save() {
	return (
		<p {...useBlockProps.save()}>
			{__(
				'My First Block – hello from the saved content!',
				'my-first-block'
			)}
		</p>
	);
}

editor.scss and style.scss

Neben den Skripten befinden sich zwei SASS-Dateien in den src-Ordnern. Die Datei editor.scss enthält die Stile, die auf den Block im Kontext des Editors angewendet werden, während die Datei style.scss die Stile des Blocks für die Anzeige im Frontend enthält. Im zweiten Teil dieses Leitfadens werden wir diese Dateien genauer unter die Lupe nehmen.

The node_modules and build Folders

Der Ordner node_modules enthält die Node-Module und ihre Abhängigkeiten. Wir werden nicht näher auf die Node-Pakete eingehen, da es den Rahmen dieses Artikels sprengen würde, aber du kannst in diesem Artikel mehr darüber lesen, wo npm die Pakete installiert.

Der build-Ordner enthält die JS- und CSS-Dateien, die während des Build-Prozesses entstehen. In den Anleitungen zur ESNext-Syntax und zum JavaScript-Build-Setup kannst du tiefer in den Build-Prozess eintauchen.

Das Projekt: Baue deinen ersten Gutenberg-Block

Jetzt wird es Zeit, sich die Hände schmutzig zu machen. In diesem Abschnitt lernst du, wie du ein Plugin erstellst, das einen CTA-Block mit dem Namen Affiliate Block bereitstellt.

Der Block wird aus zwei Spalten bestehen, mit einem Bild auf der linken Seite und einem Textabsatz auf der rechten Seite. Unter dem Text wird eine Schaltfläche mit einem anpassbaren Link platziert:

Der Blocktyp, den du in diesem Leitfaden lernen wirst zu bauen.
Der Blocktyp, den du in diesem Leitfaden lernen wirst zu bauen.

Dies ist nur ein einfaches Beispiel, aber es ermöglicht uns, die Grundlagen der Gutenberg-Blockentwicklung zu vermitteln. Sobald du die Grundlagen verstanden hast, kannst du mit Hilfe des Block Editor Handbook und anderer umfangreicher Ressourcen mehr und komplexere Gutenberg-Blöcke erstellen.

Vorausgesetzt, du hast die neueste Version von WordPress auf deiner lokalen Entwicklungsumgebung laufen, erfährst du hier, was du von jetzt an lernen wirst:

Auf die Plätze… fertig… los!

So richtest du das Starter Block Plugin ein

Starte dein Command-Line Tool und navigiere zum Ordner /wp-content/plugins:

Neues Terminal im Ordner in Mac OS.
Neues Terminal im Ordner in Mac OS.

Führe nun den folgenden Befehl aus:

npx @wordpress/create-block

Dieser Befehl generiert die PHP-, SCSS- und JS-Dateien für die Registrierung eines Blocks im interaktiven Modus, so dass du die notwendigen Daten für deinen Block einfach hinzufügen kannst. Für unser Beispiel verwenden wir die folgenden Angaben:

Die Installation des Plugins und aller Abhängigkeiten dauert nur ein paar Minuten. Wenn der Vorgang abgeschlossen ist, siehst du die folgende Antwort:

Der Affiliate-Block wurde installiert und für die Entwicklung registriert.
Der Affiliate-Block wurde installiert und für die Entwicklung registriert.

Führe nun den folgenden Befehl im Ordner /wp-content/plugins aus:

cd my-affiliate-block
Befehle aus dem Visual Studio Code Terminal ausführen.
Befehle aus dem Visual Studio Code Terminal ausführen.

Schließlich kannst du im Ordner deines Plugins (in unserem Beispiel my-affiliate-block) mit der Entwicklung beginnen:

npm start

Öffne nun den Plugins-Bildschirm, um das Affiliate Block Plugin zu finden und zu aktivieren:

Affiliate Block plugin.
Affiliate Block plugin.

Erstelle einen neuen Beitrag, öffne den Block-Inserter und scrolle runter zur Kategorie Design. Klicke darauf, um den Affiliate-Block hinzuzufügen:

Ein Starterblock, der mit @wordpress/create-block erstellt wurde.
Ein Starterblock, der mit @wordpress/create-block erstellt wurde.

block.json bei der Arbeit

Wie wir bereits erwähnt haben, findet die serverseitige Blockregistrierung in der Haupt-.php-Datei statt. Allerdings werden wir die Einstellungen nicht in der .php-Datei festlegen. Stattdessen werden wir die Datei block.json verwenden.

Öffne also noch einmal die Datei block.json und sieh dir die Standardeinstellungen genauer an:

{
	"apiVersion": 2,
	"name": "my-affiliate-plugin/my-affiliate-block",
	"version": "0.1.0",
	"title": "Affiliate Block",
	"category": "design",
	"icon": "money",
	"description": "An example block for Kinsta readers",
	"supports": {
		"html": false
	},
	"textdomain": "my-affiliate-block",
	"editorScript": "file:./build/index.js",
	"editorStyle": "file:./build/index.css",
	"style": "file:./build/style-index.css"
}

Skripte und Stile

Die Eigenschaften editorScript, editorStyle und style geben die relativen Pfade zu den Skripten und Stilen im Frontend und Backend an.

Du musst die hier definierten Skripte und Stile nicht manuell registrieren, denn sie werden von WordPress automatisch registriert und in die Warteschlange gestellt. Um das zu überprüfen, rufe den Browser-Inspektor auf und öffne die Registerkarte Netzwerk:

Ressourcen in den Chrome DevTools inspizieren.
Ressourcen in den Chrome DevTools inspizieren.

Wie du im obigen Bild sehen kannst, wurde unser index.js-Skript, das sich im Build-Ordner befindet, regelmäßig in die Warteschlange aufgenommen, ohne dass wir irgendeinen PHP-Code hinzufügen mussten.

UI Labels

Die Eigenschaften title und description liefern die Beschriftungen, die zur Identifizierung des Blocks im Editor benötigt werden:

Blockname und Beschreibung in der Sidebar des Blocks.
Blockname und Beschreibung in der Sidebar des Blocks.

Keywords

Wie wir bereits erwähnt haben, kannst du deine Blockeinstellungen mithilfe von Eigenschaften und Attributen genau konfigurieren. Du kannst zum Beispiel ein oder mehrere keywords hinzufügen, um den Nutzern die Suche nach Blöcken zu erleichtern:

{ "keywords": [ "kinsta", "affiliate", "money" ] }

Wenn du jetzt „kinsta“, „affiliate“ oder „money“ in den Quick-Inserter eingibst, wird dir der Editor den Affiliate-Block vorschlagen:

Suche nach einem Block mit einem Keyword im Quick Inserter.
Suche nach einem Block mit einem Keyword im Quick Inserter.

Lokalisierung

Wenn du dich fragst, wie die Lokalisierung der Zeichenketten in der JSON-Datei funktioniert, hier ist die Antwort:

In JavaScript kannst du jetzt die Methode registerBlockTypeFromMetadata aus dem Paket @wordpress/blocks verwenden, um einen Blocktyp mit den Metadaten aus der Datei block.json zu registrieren. Alle lokalisierten Eigenschaften werden automatisch in _x (aus dem @wordpress/i18n-Paket) Funktionsaufrufe verpackt, ähnlich wie es in PHP mit register_block_type_from_metadata funktioniert. Die einzige Voraussetzung ist, dass du die Eigenschaft textdomain in der block.json-Datei setzt.

Hier verwenden wir die Funktion registerBlockType anstelle von registerBlockTypeFromMetadata, da letztere seit Gutenberg 10.7 veraltet ist, aber der Mechanismus ist der gleiche.

Eingebaute Komponenten verwenden: Die RichText-Komponente

Die Elemente, aus denen ein Gutenberg-Block besteht, sind React-Komponenten und du kannst über die globale Variable wp auf diese Komponenten zugreifen. Gib zum Beispiel wp.editor in die Konsole deines Browsers ein. Daraufhin erhältst du eine vollständige Liste der Komponenten, die im Modul wp.editor enthalten sind.

Scrolle durch die Liste und errate anhand der Namen, wofür die Komponenten gedacht sind.

Auf ähnliche Weise kannst du die Liste der Komponenten im Modul wp.components überprüfen:

WP Editor Komponenten.
WP Editor Komponenten.

Gehe nun zurück zur Datei edit.js und schau dir das Skript genauer an:

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit() {
	return (
		<p {...useBlockProps()}>
			{__('My First Block – hello from the editor!', 'my-first-block')}
		</p>
	);
}

Dieser Code erzeugt einen statischen Block mit einfachem, nicht editierbarem Text. Aber wir können die Dinge leicht ändern:

Der Startblock im Code-Editor.
Der Startblock im Code-Editor.

Um den Text bearbeitbar zu machen, musst du das aktuelle <p>-Tag durch eine Komponente ersetzen, die den eingegebenen Inhalt bearbeitbar macht. Dafür bietet Gutenberg die integrierte RichText-Komponente.

Das Hinzufügen einer eingebauten Komponente zu deinem Block ist ein Prozess mit 5 Schritten:

  1. Importiere die benötigten Komponenten aus einem WordPress-Paket
  2. Füge die entsprechenden Elemente in deinen JSX-Code ein
  3. Definiere die notwendigen Attribute in der Datei block.json
  4. Definiere Ereignishandler
  5. Speichere Daten

Schritt 1: Importiere die benötigten Komponenten aus einem WordPress-Paket

Öffne nun die Datei edit.js und ändere die folgende import-Anweisung:

import { useBlockProps } from '@wordpress/block-editor';

…zu:

import { useBlockProps, RichText } from '@wordpress/block-editor';

Auf diese Weise importierst du die Funktion useBlockProps und die RichText-Komponente aus dem Paket @wordpress/block-editor.

useBlockProps

Der React-Hook useBlockProps markiert das Wrapper-Element des Blocks:

Wenn du die API-Version 2 verwendest, musst du den neuen useBlockProps-Haken in der Bearbeitungsfunktion des Blocks verwenden (edit), um das Wrapper-Element des Blocks zu markieren. Der Hook fügt die Attribute und Event-Handler ein, die für das Verhalten des Blocks benötigt werden. Alle Attribute, die du an das Blockelement übergeben möchtest, müssen über useBlockProps übergeben werden und der zurückgegebene Wert muss auf das Element verteilt werden.

Vereinfacht gesagt, weisen useBlockProps dem Wrapper-Element (in unserem Beispiel dem p-Element) automatisch Attribute und Klassen zu:

Elemente und Klassen, die von useBlockProps erzeugt werden.
Elemente und Klassen, die von useBlockProps erzeugt werden.

Wenn du useBlockProps aus dem Wrapper-Element entfernst, hättest du einen einfachen Textstring ohne Zugriff auf die Blockfunktionalität und den Stil:

Derselbe Block ohne useBlockProps.
Derselbe Block ohne useBlockProps.

Wie wir später noch erklären werden, kannst du useBlockProps auch ein Objekt mit Eigenschaften übergeben, um die Ausgabe anzupassen.

RichText

Die RichText-Komponente bietet eine inhaltsveränderbare Eingabe, die es den Nutzern ermöglicht, den Inhalt zu bearbeiten und zu formatieren.

Du findest die Komponente auf GitHub unter gutenberg/packages/block-editor/src/components/rich-text/README.md dokumentiert.

Schritt 2: Füge die entsprechenden Elemente in deinen JSX-Code ein

...

const blockProps = useBlockProps();

return (
	<RichText 
		{ ...blockProps }
		tagName="p"
		onChange={ onChangeContent }
		allowedFormats={ [ 'core/bold', 'core/italic' ] }
		value={ attributes.content }
		placeholder={ __( 'Write your text...' ) }
	/>
);

Lass uns den Code Zeile für Zeile kommentieren:

Schritt 3: Definiere die notwendigen Attribute in der Datei block.json

Attribute liefern Informationen über die in einem Block gespeicherten Daten, wie z. B. Rich Content, Hintergrundfarbe, URLs usw.

Du kannst eine beliebige Anzahl von Attributen in einem attributes-Objekt in Schlüssel/Wert-Paaren festlegen, wobei der Schlüssel der Attributname und der Wert die Attributdefinition ist.

Öffne nun die Datei block.json und füge die folgenden attributes prop:

"attributes": {
	"content": {
		"type": "string",
		"source": "html",
		"selector": "p"
	}
},

Das Attribut content ermöglicht es, den vom Benutzer in das bearbeitbare Feld eingegebenen Text zu speichern:

Wir werden der Edit-Funktion ein Objekt mit Eigenschaften übergeben. Gehe also zurück zur Datei edit.js und nimm die folgende Änderung vor:

export default function Edit( { attributes, setAttributes } ) { ... }

Schritt 4: Ereignishandler definieren

Das RichText-Element hat ein onChange-Attribut, das eine Funktion bereitstellt, die aufgerufen wird, wenn sich der Inhalt des Elements ändert.

Definieren wir diese Funktion und sehen wir uns das gesamte edit.js-Skript an:

import { __ } from '@wordpress/i18n';
import { useBlockProps, RichText } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit( { attributes, setAttributes } ) {
	const blockProps = useBlockProps();

	const onChangeContent = ( newContent ) => {
		setAttributes( { content: newContent } )
	}

	return (
		<RichText 
			{ ...blockProps }
			tagName="p"
			onChange={ onChangeContent }
			allowedFormats={ [ 'core/bold', 'core/italic' ] }
			value={ attributes.content }
			placeholder={ __( 'Write your text...' ) }
		/>
	);
}

Speichere nun die Datei und führe npm run start in deinem Terminalfenster aus. Gehe dann zurück zu deinem WordPress Dashboard, erstelle einen neuen Beitrag oder eine neue Seite und füge deinen Affiliate-Block hinzu:

Die Ausgabe der RichText-Komponente im Block-Editor.
Die Ausgabe der RichText-Komponente im Block-Editor.

Füge etwas Text hinzu und wechsle in die Codeansicht. So sollte dein Code aussehen:

<!-- wp:my-affiliate-plugin/my-affiliate-block -->
<p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable Gutenberg block 🤓</p>
<!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Wenn du jetzt die Seite speicherst und das Frontend-Ergebnis überprüfst, wirst du vielleicht etwas enttäuscht sein, weil sich deine Änderungen nicht auf die Webseite auswirken. Das liegt daran, dass du die Datei save.js ändern musst, um die Benutzereingaben in der Datenbank zu speichern, wenn der Beitrag gespeichert wird.

Schritt 5: Daten speichern

Öffne nun die Datei save.js und ändere das Skript wie folgt:

import { __ } from '@wordpress/i18n';
import { useBlockProps, RichText } from '@wordpress/block-editor';

export default function save( { attributes } ) {
	const blockProps = useBlockProps.save();
	return (
		<RichText.Content 
			{ ...blockProps } 
			tagName="p" 
			value={ attributes.content } 
		/>
	);
}

Das ist es, was wir hier tun:

Du kannst mehr über die RichText-Komponente im Handbuch für den Block-Editor lesen und die vollständige Liste der Requisiten auf Github finden.

Jetzt gehen wir noch einen Schritt weiter. Im nächsten Abschnitt erfährst du, wie du der Blocksymbolleiste Steuerelemente hinzufügst.

Hinzufügen von Steuerelementen zur Blocksymbolleiste

Die Blocksymbolleiste enthält eine Reihe von Steuerelementen, mit denen du Teile des Blockinhalts bearbeiten kannst. Für jedes Steuerelement der Symbolleiste findest du eine Komponente:

Die zentrale Absatzblock-Symbolleiste.
Die zentrale Absatzblock-Symbolleiste.

Du könntest zum Beispiel eine Textausrichtungssteuerung für deinen Block hinzufügen. Dazu musst du nur zwei Komponenten aus dem Paket @wordpress/block-editor importieren.

Wir gehen die gleichen Schritte wie im vorherigen Beispiel durch:

  1. Erforderliche Komponenten aus WordPress-Paketen importieren
  2. Füge die entsprechenden Elemente in deinen JSX-Code ein
  3. Definiere die notwendigen Attribute in der block.json-Datei
  4. Definiere Event Handler
  5. Daten speichern

Schritt 1: Importiere BlockControls und AlignmentControl-Komponenten aus @wordpress/block-editor

Um der Block-Symbolleiste eine Ausrichtungssteuerung hinzuzufügen, brauchst du zwei Komponenten:

Bist du es leid, dass WordPress Hosting-Support auf untergeordneter Ebene 1 keine Antworten bietet? Teste unser erstklassiges Support-Team! Schau dir unsere Pläne an

Öffnen Sie die Datei edit.js und bearbeiten Sie die import-Anweisung wie unten gezeigt:

import { 
	useBlockProps, 
	RichText, 
	AlignmentControl, 
	BlockControls 
} from '@wordpress/block-editor';

Schritt 2: Hinzufügen der Elemente BlockControls und AlignmentControl

Gehen Sie zur Funktion Edit und fügen Sie das Element <BlockControls /> auf der gleichen Ebene wie <RichText /> ein. Fügen Sie dann <AlignmentControl /> innerhalb von <BlockControls /> hinzu:

export default function Edit( { attributes, setAttributes } ) {
	const blockProps = useBlockProps();
	return (
		<>
			<BlockControls>
				<AlignmentControl
					value={ attributes.align }
					onChange={ onChangeAlign }
				/>
			</BlockControls>
			<RichText 
				{ ...blockProps }
				tagName="p"
				onChange={ onChangeContent }
				allowedFormats={ [ 'core/bold', 'core/italic' ] }
				value={ attributes.content }
				placeholder={ __( 'Write your text...' ) }
				style={ { textAlign: attributes.align } }
			/>
		</>
	);
}

Im obigen Code sind <> und </> die kurze Syntax für die Deklaration von React-Fragmenten, mit denen wir mehrere Elemente in React zurückgeben.

In diesem Beispiel hat AlignmentControl zwei Attribute:

Wir haben auch zusätzliche Attribute für das RichText-Element definiert (siehe die vollständige Liste der Attribute mit Beispielen)

Schritt 3: Definieren Sie das Attribut align in block.json

Gehen Sie nun zur Datei block.json und fügen Sie das Attribut align hinzu:

"align": {
	"type": "string",
	"default": "none"
}

Gehe zurück zum Terminal, beende den aktuellen Prozess mit ^C und starte das Skript erneut mit npm run start. Gehe dann zurück zum Blockeditor, aktualisiere die Seite und wähle den Block aus. Du solltest die Block-Symbolleiste mit einer Ausrichtungssteuerung sehen:

Die Ausrichtungs-Symbolleiste wurde erfolgreich hinzugefügt.
Die Ausrichtungs-Symbolleiste wurde erfolgreich hinzugefügt.

Wenn du jetzt versuchst, den Blockinhalt mit den neuen Ausrichtungssteuerelementen zu formatieren, wirst du sehen, dass nichts passiert. Das liegt daran, dass wir den Event-Handler noch nicht definiert haben.

Schritt 4: Definiere die Ereignishandler

Definiere nun onChangeAlign:

const onChangeAlign = ( newAlign ) => {
	setAttributes( { 
		align: newAlign === undefined ? 'none' : newAlign, 
	} )
}

Wenn newAlign undefiniert (undefined) ist, setzen wir newAlign auf none. Andernfalls verwenden wir newAlign.

Unser edit.js-Skript sollte nun (vorerst) fertig sein:

export default function Edit( { attributes, setAttributes } ) {
	const blockProps = useBlockProps();
	const onChangeContent = ( newContent ) => {
		setAttributes( { content: newContent } )
	}
	const onChangeAlign = ( newAlign ) => {
		setAttributes( { 
			align: newAlign === undefined ? 'none' : newAlign, 
		} )
	}
	return (
		<>
			<BlockControls>
				<AlignmentControl
					value={ attributes.align }
					onChange={ onChangeAlign }
				/>
			</BlockControls>
			<RichText 
				{ ...blockProps }
				tagName="p"
				onChange={ onChangeContent }
				allowedFormats={ [ 'core/bold', 'core/italic' ] }
				value={ attributes.content }
				placeholder={ __( 'Write your text...' ) }
				style={ { textAlign: attributes.align } }
			/>
		</>
	);
}

Jetzt kannst du zurück zum Editor gehen und den Blockinhalt ausrichten.

Wir müssen die Speicherfunktion ändern, um den Blockinhalt und die Attribute in der Datenbank zu speichern.

Schritt 5: Daten speichern

Öffne save.js und ändere die save-Funktion wie folgt:

export default function save( { attributes } ) {
	const blockProps = useBlockProps.save();
	return (
		<RichText.Content 
			{ ...blockProps } 
			tagName="p" 
			value={ attributes.content } 
			style={ { textAlign: attributes.align } }
		/>
	);
}

Um den Code lesbarer zu machen, kannst du die einzelnen Eigenschaften aus dem attribute-Objekt extrahieren, indem du die Syntax der Destrukturierungszuweisung verwendest:

export default function save( { attributes } ) {
	const blockProps = useBlockProps.save();
	const { content, align } = attributes;
	return (
		<RichText.Content 
			{ ...blockProps } 
			tagName="p" 
			value={ content } 
			style={ { textAlign: align } }
		/>
	);
}

Speichere die Datei, starte den Prozess neu und kehre zum Editor im Code-Editor-Modus zurück. Der Code sollte in etwa so aussehen:

<!-- wp:my-affiliate-plugin/my-affiliate-block {"align":"right"} -->
<p class="wp-block-my-affiliate-plugin-my-affiliate-block" style="text-align:right">This is my first editable <strong><em>Gutenberg</em></strong> <em>block</em> 🤓</p>
<!-- /wp:my-affiliate-plugin/my-affiliate-block -->
Text rechts ausrichten.
Text rechts ausrichten.

Und das war’s schon! Du hast soeben eine Ausrichtungssteuerung zur Blocksymbolleiste hinzugefügt 🤓

Mehr über die Steuerelemente der Blocksymbolleiste erfährst du im Handbuch für den Blockeditor.

Die Sidebar der Blockeinstellungen anpassen

Du kannst auch Steuerelemente zur Sidebar für die Blockeinstellungen hinzufügen (oder sogar eine neue Sidebar für deine Anwendung erstellen).

Die API bietet dafür eine InspectorControls-Komponente.

Im Handbuch für den Blockeditor wird erklärt, wie du die Settings Sidebar verwendest:

Die Sidebar für Einstellungen wird verwendet, um weniger häufig genutzte Einstellungen oder Einstellungen, die mehr Platz auf dem Bildschirm benötigen, anzuzeigen. Die Sidebar für Einstellungen sollte nur für Einstellungen auf Blockebene verwendet werden.

Wenn du Einstellungen hast, die sich nur auf ausgewählte Inhalte innerhalb eines Blocks auswirken (z. B. die Einstellung „fett“ für ausgewählten Text innerhalb eines Absatzes), solltest du sie nicht in der Sidebar für Einstellungen platzieren. Die Sidebar wird auch dann angezeigt, wenn du einen Block im HTML-Modus bearbeitest, also sollte sie nur Einstellungen auf Blockebene enthalten.

Nochmal:

  1. Erforderliche Komponenten aus WordPress-Paketen importieren
  2. Füge die entsprechenden Elemente in deinen JSX-Code ein
  3. Definiere die notwendigen Attribute in der block.json-Datei
  4. Definiere Event Handler
  5. Daten speichern

Schritt 1. Importiere die Komponenten InspectorControls und PanelColorSettings aus @wordpress/block-editor

Du kannst verschiedene Steuerelemente hinzufügen, mit denen die Nutzer bestimmte Aspekte des Blocks anpassen können. Du kannst zum Beispiel ein Farbkontrollfeld einrichten. Dazu musst du die Komponenten InspectorControls und PanelColorSettings aus dem Modul block-editor importieren:

import { 
	useBlockProps, 
	RichText, 
	AlignmentControl, 
	BlockControls,
	InspectorControls,
	PanelColorSettings
} from '@wordpress/block-editor';

Schritt 2: Füge die entsprechenden Elemente in deinen JSX-Code ein

Jetzt kannst du die entsprechenden Elemente in den JSX-Code einfügen, der von der Edit-Funktion zurückgegeben wird:

export default function Edit( { attributes, setAttributes } ) {
	const blockProps = useBlockProps();
	const onChangeContent = ( newContent ) => {
		setAttributes( { content: newContent } )
	}
	const onChangeAlign = ( newAlign ) => {
		setAttributes( { 
			align: newAlign === undefined ? 'none' : newAlign, 
		} )
	}
	return (
		<>
			<InspectorControls>
				<PanelColorSettings 
					title={ __( 'Color settings', 'my-affiliate-block' ) }
					initialOpen={ false }
					colorSettings={ [
						{
						  value: textColor,
						  onChange: onChangeTextColor,
						  label: __( 'Text color', 'my-affiliate-block' ),
						},
						{
						  value: backgroundColor,
						  onChange: onChangeBackgroundColor,
						  label: __( 'Background color', 'my-affiliate-block' ),
						}
					] }
				/>
			</InspectorControls>
			<BlockControls>
				<AlignmentControl
					value={ attributes.align }
					onChange={ onChangeAlign }
				/>
			</BlockControls>
			<RichText 
				{ ...blockProps }
				tagName="p"
				onChange={ onChangeContent }
				allowedFormats={ [ 'core/bold', 'core/italic' ] }
				value={ attributes.content }
				placeholder={ __( 'Write your text...', 'my-affiliate-block' ) }
				style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } }
			/>
		</>
	);
}

Beachte, dass wir auch das style-Attribut des RichText-Elements aktualisiert haben:

<RichText 
	 { ...blockProps }
	 tagName="p"
	 onChange={ onChangeContent }
	 allowedFormats={ [ 'core/bold', 'core/italic' ] }
	 value={ content }
	 placeholder={ __( 'Write your text...', 'my-affiliate-block' ) }
	 style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } }
/>

Schritt 3: Definiere die notwendigen Attribute in block.json

Definiere nun die Attribute backgroundColor und textColor in der Datei block.json:

"attributes": {
	"content": {
		"type": "string",
		"source": "html",
		"selector": "p"
	},
	"align": {
		"type": "string",
		"default": "none"
	},
	"backgroundColor": {
		"type": "string"
	},	 
	"textColor": {
		"type": "string"
	}
},

Schritt 4: Definiere die Event Handler

Jetzt musst du zwei Funktionen definieren, um backgroundColor und textColor bei Benutzereingaben zu aktualisieren:

const onChangeBackgroundColor = ( newBackgroundColor ) => {
	setAttributes( { backgroundColor: newBackgroundColor } )
}
const onChangeTextColor = ( newTextColor ) => {
	setAttributes( { textColor: newTextColor } )
}

Schritt 5: Daten speichern

Ein letzter Schritt: Öffne die Datei save.js und ändere das Skript wie folgt:

export default function save( { attributes } ) {
	const blockProps = useBlockProps.save();
	const { content, align, backgroundColor, textColor } = attributes;
	return (
		<RichText.Content 
			{ ...blockProps } 
			tagName="p" 
			value={ content } 
			style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } }
		/>
	);
}

Beende nun den Prozess (^C) und führe npm run start erneut aus. Aktualisiere die Seite, lösche jede Instanz deines Blocks und füge ihn wieder zu deinem Beitrag hinzu:

Ein benutzerdefinierter Block mit einem Farbeinstellungsfeld.
Ein benutzerdefinierter Block mit einem Farbeinstellungsfeld.

Nimm deine Änderungen vor, speichere den Beitrag und sieh ihn dir im Frontend an. Die Änderungen, die du im Block-Editor vorgenommen hast, sollten auf deiner Webseite zu sehen sein.

In diesem Abschnitt fügst du neue Komponenten zu deinem Blocktyp hinzu:

Schritt 1. Komponenten aus @wordpress/components importieren

Jetzt musst du mehrere Komponenten aus @wordpress/components importieren. Öffne deine edit.js-Datei und füge die folgende import-Anweisung hinzu:

import {
	TextControl,
	PanelBody,
	PanelRow,
	ToggleControl,
	ExternalLink
} from '@wordpress/components';

Schritt 2. Füge die entsprechenden Elemente in deinen JSX-Code ein

Zuerst fügst du das ExternalLink-Element auf der gleichen Ebene wie RichText in einen div-Container ein:

<div { ...blockProps }>
	<RichText 
		...
	/>
	<ExternalLink 
		href={ affiliateLink }
		className="affiliate-button"
		rel={ hasLinkNofollow ? "nofollow" : "" }
	>
			{ linkLabel }
	</ExternalLink>

</div>

Die ExternalLink-Komponente ist nicht dokumentiert, also haben wir uns auf die Komponente selbst bezogen, um die Liste der verfügbaren Attribute zu erhalten. Hier verwenden wir die Attribute href, className und rel.

Standardmäßig ist der Wert des Attributs rel auf noopener noreferrer gesetzt. Unser Code fügt das nofollow Keyword zum rel-Attribut des resultierenden a-Tags hinzu, wenn die Umschaltfunktion aktiviert ist.

Jetzt kannst du der Sidebar des Blocks Linkeinstellungen hinzufügen.

Zuerst fügst du ein PanelBody-Element innerhalb von InspectorControls auf der gleichen Ebene wie PanelColorSettings hinzu:

<InspectorControls>
	<PanelColorSettings 
	...
	/>
	<PanelBody 
		title={ __( 'Link Settings', 'my-affiliate-block' )}
		initialOpen={true}
	>
	...
	</PanelBody>
</InspectorControls>

So machen wir das hier:

  1. Das Attribut title gibt den title des Panels an.
  2. initialOpen legt fest, ob das Panel anfänglich geöffnet ist oder nicht.

Als Nächstes fügen wir zwei PanelRow-Elemente innerhalb von PanelBody und ein TextControl-Element innerhalb jeder PanelRow ein:

<PanelBody 
	title={ __( 'Link Settings', 'my-affiliate-block' )}
	initialOpen={true}
>
	<PanelRow>
		<fieldset>
			<TextControl
				label={__( 'Affiliate link', 'my-affiliate-block' )}
				value={ affiliateLink }
				onChange={ onChangeAffiliateLink }
				help={ __( 'Add your affiliate link', 'my-affiliate-block' )}
			/>
		</fieldset>
	</PanelRow>
	<PanelRow>
		<fieldset>
			<TextControl
				label={__( 'Link label', 'my-affiliate-block' )}
				value={ linkLabel }
				onChange={ onChangeLinkLabel }
				help={ __( 'Add link label', 'my-affiliate-block' )}
			/>
		</fieldset>
	</PanelRow>
</PanelBody>

Der obige Code sollte jetzt ziemlich einfach aussehen. Mit den beiden Textsteuerelementen können die Benutzer die Linkbezeichnung und die URL festlegen.

Außerdem fügen wir eine zusätzliche PanelRow mit einem ToggleControl hinzu, um eine bestimmte Option ein- oder auszuschalten, z. B. ob ein Attribut enthalten sein soll oder nicht:

<PanelRow>
	<fieldset>
		<ToggleControl
			label="Add rel = nofollow"
			help={
				hasLinkNofollow
					? 'Has rel nofollow.'
					: 'No rel nofollow.'
			}
			checked={ hasLinkNofollow }
			onChange={ toggleNofollow }
		/>
	</fieldset>
</PanelRow>

Schritt 3: Definiere die notwendigen Attribute in block.json

Definiere nun die Attribute affiliateLink, linkLabel und hasLinkNofollow in der Datei block.json:

"affiliateLink": {
	"type": "string",
	"default": ""
},
"linkLabel": {
	"type": "string",
	"default": "Check it out!"
},
"hasLinkNofollow": {
	"type": "boolean",
	"default": false
}

Hier gibt es nichts mehr hinzuzufügen! Jetzt geht es an die Definition der Ereignisbehandlungsfunktionen.

Schritt 4: Definiere die Ereignishandler

Gehe zurück zur Datei edit.js und füge die folgenden Funktionen hinzu:

const onChangeAffiliateLink = ( newAffiliateLink ) => {
	setAttributes( { affiliateLink: newAffiliateLink === undefined ? '' : newAffiliateLink } )
}

const onChangeLinkLabel = ( newLinkLabel ) => {
	setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } )
}

const toggleNofollow = () => {
	setAttributes( { hasLinkNofollow: ! hasLinkNofollow } )
}

Diese Funktionen aktualisieren die entsprechenden Attributwerte bei Benutzereingaben.

Schritt 5: Daten speichern

Zuletzt müssen wir die Speicherfunktion save in save.js aktualisieren:

export default function save( { attributes } ) {

	const { align, content, backgroundColor, textColor, affiliateLink, linkLabel, hasLinkNofollow } = attributes;

	const blockProps = useBlockProps.save();

	return (
		<div { ...blockProps }>
			<RichText.Content 
				tagName="p" 
				value={ content } 
				style={ { backgroundColor: backgroundColor, color: textColor } }
			/>
			<p>
				<a 
					href={ affiliateLink }
					className="affiliate-button"
					rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" }
				>
					{ linkLabel }
				</a>
			</p>
		</div>
	);
}

Beachte, dass wir hier ein normales a-Element anstelle von ExternalLink verwendet haben:

Einstellungen für Affiliate-Block-Links.
Einstellungen für Affiliate-Block-Links.

Speichere jetzt die Daten und starte deine Umgebung neu.

Hinzufügen mehrerer Blockstile

Im vorigen Abschnitt hast du gelernt, wie man eine Blocksymbolleiste hinzufügt, mit der man die Benutzereingaben ausrichten kann. Wir können der Block-Symbolleiste weitere Stil-Steuerelemente hinzufügen, aber wir können auch eine Reihe von vordefinierten Blockstilen bereitstellen, aus denen der Benutzer mit einem einzigen Klick auswählen kann.

Zu diesem Zweck werden wir eine nützliche Funktion der Block-API nutzen: Blockstile.

Alles, was du tun musst, ist, die Eigenschaft block.json styles zu definieren und die entsprechenden styles in deinen Stylesheets zu deklarieren.

Du kannst zum Beispiel die folgende Reihe von Stilen hinzufügen:

"styles": [
	{
		"name": "default",
		"label": "Default",
		"isDefault": true
	},
	{
		"name": "border",
		"label": "Border"
	}
],

Damit hast du gerade einen Standardstil und einen zusätzlichen Stil namens border hinzugefügt. Jetzt gehst du zurück zum Block-Editor:

Zwei vordefinierte Blockstile.
Zwei vordefinierte Blockstile.

Die Stile stehen dem Nutzer zur Verfügung, wenn er auf den Blockschalter klickt und dann in der Sidebar der Blockeinstellungen nach dem Bereich Stile sucht.

Wähle einen Stil aus und überprüfe die Klassen, die auf das p-Element angewendet werden. Klicke mit der rechten Maustaste auf den Block und wähle Untersuchen. Es wurde eine neue Klasse mit einem Namen hinzugefügt, der wie folgt aufgebaut ist:

is-style-{style-name}

Wenn du den Stil „Border“ ausgewählt hast, wird dem p-Element die Klasse is-style-border hinzugefügt. Wenn du den Stil „Standard“ ausgewählt hast, wird stattdessen eine is-style-default-Klasse hinzugefügt.

Jetzt musst du nur noch die CSS-Eigenschaften deklarieren. Öffne die Datei editor.scss und ersetze die aktuellen Stile durch die folgenden:

.wp-block-my-affiliate-plugin-my-affiliate-block {
	padding: 2px;
	&.is-style-default{
		border: 0;
	}
	&.is-style-border{
		border: 1px solid #000;
	}
}

Jetzt kannst du das Gleiche mit style.scss machen:

.wp-block-my-affiliate-plugin-my-affiliate-block {
	&.is-style-default{
		border: 0;
	}
	&.is-style-border{
		border: 1px solid #000;
	}
}

Halte den Prozess an (^C) und führe npm run start erneut aus.

Und das war’s schon! Aktualisiere die Seite und hab Spaß mit deinen neuen Blockstilen:

Affiliate-Blockstile.
Affiliate-Blockstile.

Verschachtelte Gutenberg-Blöcke mit der InnerBlocks-Komponente

Obwohl er voll funktionsfähig ist, ist unser Affiliate-Block immer noch nicht sehr ansprechend. Um es für das Publikum ansprechender zu machen, könnten wir ein Bild hinzufügen.

Zum Glück musst du das Rad aber nicht neu erfinden, denn Gutenberg bietet eine spezielle Komponente, mit der du eine Struktur aus verschachtelten Blöcken erstellen kannst.

Die InnerBlocks-Komponente ist wie folgt definiert:

InnerBlocks exportiert ein Paar Komponenten, die in Blockimplementierungen verwendet werden können, um verschachtelte Blockinhalte zu ermöglichen.

Zuerst musst du eine neue .js-Datei im Ordner src erstellen. In unserem Beispiel nennen wir diese Datei container.js.

Nun musst du die neue Ressource in die Datei index.js importieren:

import './container';

Gehe zurück zu container.js und importiere die notwendigen Komponenten:

import { registerBlockType } from "@wordpress/blocks";
import { __ } from "@wordpress/i18n";
import {
	useBlockProps, 
	InnerBlocks 
} from "@wordpress/block-editor";

Der nächste Schritt ist die Definition eines Templates, das die Struktur vorgibt, in der die Blöcke platziert werden sollen. Im folgenden Beispiel definieren wir ein Template, das aus zwei Spalten besteht, die einen Kernblock „Bild“ und unseren benutzerdefinierten Block „Partner“ enthalten:

const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [
	[ 'core/column', { templateLock: 'all' }, [
		[ 'core/image' ],
	] ],
	[ 'core/column', { templateLock: 'all' }, [
		[ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ],
	] ],
] ] ];

Das Template ist als Array von blockTypes (Blockname und optionale Attribute) aufgebaut.

Im obigen Code haben wir mehrere Attribute verwendet, um die Blöcke Columns und Column zu konfigurieren. Das Attribut templateLock: 'all' sperrt die Spaltenblöcke, so dass der Benutzer keine Blöcke hinzufügen, neu anordnen oder löschen kann. templateLock kann einen der folgenden Werte annehmen:

Das Template wird dann dem InnerBlocks-Element zugewiesen:

<InnerBlocks
	template={ TEMPLATE }
	templateLock="all"
/>

Um Kompatibilitätsprobleme zu vermeiden, haben wir außerdem ein TemplateLock-Attribut zur InnerBlocks-Komponente hinzugefügt (siehe auch Issue #17262 und Pull #26128).

Hier ist unsere endgültige container.js-Datei:

import { registerBlockType } from "@wordpress/blocks";
import { __ } from "@wordpress/i18n";
import { useBlockProps, InnerBlocks } from "@wordpress/block-editor";

const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [
	[ 'core/column', { templateLock: 'all' }, [
		[ 'core/image' ],
	] ],
	[ 'core/column', { templateLock: 'all' }, [
		[ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ],
	] ],
] ] ];

registerBlockType('my-affiliate-plugin/my-affiliate-container-block', {
	title: __( 'Container', 'my-affiliate-block' ),
	category: 'design',

	edit( { className } ) {
		
		return(
			<div className={ className }>
				<InnerBlocks
					template={ TEMPLATE }
					templateLock="all"
				/>
			</div>
		)
	},

	save() {
		const blockProps = useBlockProps.save();
		return(
			<div { ...blockProps }>
				<InnerBlocks.Content />
			</div>
		)
	},
});
Der verschachtelte Affiliate-Block im Editor.
Der verschachtelte Affiliate-Block im Editor.

Zusätzliche Verbesserungen

Unser Block ist voll funktionsfähig, aber wir könnten ihn mit ein paar kleinen Änderungen noch ein wenig verbessern.

Wir haben das Attribut backgroundColor dem Absatz zugewiesen, der von der RichText-Komponente erzeugt wird. Wir könnten es jedoch vorziehen, die Hintergrundfarbe dem Container-div zuzuweisen:

Ändere also die Datei edit.js und die divs save.js wie folgt:

<div 
	{ ...blockProps }
	style={ { backgroundColor: backgroundColor } }
>
...
</div>

Damit kann der Benutzer den Hintergrund des gesamten Blocks ändern.

Eine wichtigere Änderung betrifft jedoch die Methode useBlockProps. Im ursprünglichen Code haben wir die Konstante blockProps wie folgt definiert:

const blockProps = useBlockProps();

Aber wir können useBlockProps noch effektiver nutzen, indem wir eine Reihe von Eigenschaften übergeben. Zum Beispiel können wir classnames aus dem classnames-Modul importieren und den Namen der Wrapper-Klasse entsprechend festlegen.

Im folgenden Beispiel weisen wir einen Klassennamen zu, der auf dem Wert des Attributs align basiert (edit.js):

import classnames from 'classnames';

...

export default function Edit( { attributes, setAttributes } ) {
	...
	const blockProps = useBlockProps( {
		className: classnames( {
			[ `has-text-align-${ align }` ]: align,
		} )
	} );
	...
}

Die gleiche Änderung nehmen wir in der Datei save.js vor:

import classnames from 'classnames';

...

export default function save( { attributes } ) {
	...
	const blockProps = useBlockProps.save({
		className: classnames( {
			[ `has-text-align-${ align }` ]: align,
		} )
	});
	...
}

Und das war’s schon! Du kannst jetzt den Build für die Produktion ausführen.

Wenn du nach einer ausführlichen Anleitung für den Einstieg in die Entwicklung von Gutenberg-Blöcken suchst, ist dieser Leitfaden genau das Richtige für dich. Schau es dir an und fang noch heute an, deine Gutenberg-Blöcke zu bauen! 👷‍♀️🧱Click to Tweet

Zusammenfassung

Und hier sind wir nun, am Ende dieser unglaublichen Reise! Wir haben mit der Konfiguration der Entwicklungsumgebung begonnen und schließlich einen kompletten Blocktyp erstellt.

Wie wir in der Einleitung erwähnt haben, sind solide Kenntnisse in Node.js, Webpack, Babel und React unerlässlich, um fortgeschrittene Gutenberg-Blöcke zu erstellen und sich als professioneller Gutenberg-Entwickler auf dem Markt zu positionieren.

Du musst aber keine fundierte React-Erfahrung haben, um Spaß an der Blockentwicklung zu haben. Die Entwicklung von Blöcken kann dich motivieren und dir Ziele setzen, um immer umfassendere Kenntnisse über die Technologien hinter den Gutenberg-Blöcken zu erwerben.

Dieser Leitfaden ist daher bei weitem nicht vollständig. Es ist lediglich eine Einleitung in eine Vielzahl von Themen, die dir helfen werden, deine ersten Gutenberg-Blöcke zu erstellen.

Deshalb empfehlen wir dir, dein Wissen zu vertiefen, indem du die Online-Dokumentation und Anleitungen sorgfältig liest. Unter den vielen Ressourcen, die es da draußen gibt, empfehlen wir die folgenden:

Wenn du gerade erst mit der WordPress-Entwicklung beginnst, möchtest du vielleicht die grundlegenden Konzepte der Frontend-Entwicklung verstehen. Hier ist eine kurze Liste von Ressourcen, die dir den Einstieg erleichtern können:

Und vergiss nicht, dass der komplette Code der Beispiele dieses Leitfadens auf Gist verfügbar ist.

Jetzt bist du an der Reihe: Hast du schon Gutenberg-Blöcke entwickelt? Was sind die größten Schwierigkeiten, die du bisher erlebt hast? Lass uns in den Kommentaren von deinen Erfahrungen wissen!


Spare Zeit, Kosten und maximiere die Leistung deiner Seite mit:

  • Schnelle Hilfe von WordPress Hosting Experten, 24/7.
  • Cloudflare Enterprise Integration.
  • Globale Reichweite mit 29 Rechenzentren weltweit.
  • Optimierung mit unserem integrierten Application Performance Monitoring.

All das und noch viel mehr, in einem Plan ohne langfristige Verträge, betreute Migrationen und eine 30-Tage-Geld-zurück-Garantie. Schau Dir hier unsere Pakete an oder sprich mit dem Vertrieb, um den richtigen Tarif für dich zu finden.