Eigenen WordPress Block entwickeln – Teil 2: Block Plugin mit create-guten-block erstellen

Veröffentlicht am von / Lesezeit: 5 Minuten

In dieser Artikelreihe erkläre ich, wie du von Grund auf deinen eigenen WordPress Block entwickeln kannst. Im zweiten Teil sehen wir uns an, wie du dein erstes Block Plugin mit create-guten-block erstellen kannst, einem Starter-Toolkit für Gutenberg Blocks.

Zum Start der Serie und ersten Teil geht es hier.

WordPress Block entwickeln mit create-guten-block

Die Konfiguration von Webpack, Babel und Co. ist anfangs ziemlich verwirrend und kompliziert. Für Entwickler lohnt es sich aber, sich etwas damit zu beschäftigen. Wer sich näher damit auseinandersetzen möchte, dem kann ich folgende zwei Tutorials ans Herz legen:

Für dieses Tutorial wählen wir den einfachen und schnellen Weg und setzen Create Guten Block von Ahmad Awais ein. Dabei handelt es sich um ein Zero Configuration Dev-Toolkit für WordPress Gutenberg Blocks, sodass wir React, Webpack und Babel nicht selbst konfigurieren müssen.

WordPress Block Plugin erstellen

Für die Verwendung des Tools solltest du Node.js installiert haben und bereits mit NPM vertraut sein. Außerdem brauchst du einen lokalen Server mit einer WordPress Installation.

Die Installation erfolgt über die Kommandozeile. Begebe dich dazu als Erstes in das Plugin-Verzeichnis deiner lokalen WordPress Website.

cd wp-content/plugins

Anschließend kannst du dein Block Plugin mit dem Befehl npx create-guten-block erstellen. Dem Kommando wird außerdem der Name für das WordPress Plugin übergeben. Du kannst einen beliebigen Namen wählen. Für unser Tutorial verwenden wir themecoder-block.

npx create-guten-block themecoder-block

Das Tool legt für uns den Plugin-Ordner an und installiert alle benötigten Node Module.

Create Guten Block Installation

Die Installation kann deshalb einige Minuten in Anspruch nehmen.

WordPress Block Plugin aktivieren

Nach Abschluss der Installation kannst du das Plugin in deinem WordPress Backend aktivieren.

ThemeCoder Block Plugin

Das Toolkit beinhaltet einen Dummy-Block als Boilerplate. Im Gutenberg Editor kannst du nach CGB Block suchen, um diesen einzufügen. Der Block zeigt nur etwas Text, ohne Eingabefelder oder Optionen. Wir werden später den Namen ändern und den Block editierbar machen.

CGB Standard Block

Fürs Erste wissen wir nun, dass die Installation ordnungsgemäß funktioniert hat.

Struktur des WordPress Block Plugins

Für die nächsten Schritte benötigst du einen Editor, z.B. VS Code.

Wir sehen uns damit die Dateien des Block Plugins genauer an. Wenn du den Plugin-Ordner themecoder-block öffnest, findest du dort folgende Ordner und Dateien:

├── dist
|   ├── blocks.build.js
|   ├── blocks.editor.build.css
|   └── blocks.style.build.css
|
├── node_modules
|
├── src
|   ├── block
|   |   ├── block.js
|   |   ├── editor.scss
|   |   └── style.scss
|   |
|   ├── blocks.js
|   ├── common.scss
|   └── init.php
|
├── .eslintignore
├── .eslintrc.json
├── .gitignore
├── plugin.php
├── package.json
├── README.md

Das sieht auf den ersten Blick komplex aus. In Teil 1 habe ich noch davon gesprochen, dass ein einfaches Block Plugin aus nur vier Dateien besteht. Auch wenn wir nun etwas mehr Dateien haben, lässt sich die grundlegende Block Architektur darin wiederfinden.

Aber der Reihe nach:

JavaScript Tooling

Im Root-Verzeichnis des Plugins findest du eine Reihe von Dateien für die Konfiguration von Git, ESLint und der NPM Packages (.gitignore, package.json, etc). Diese sind für das ganze Tooling notwendig, nicht aber für die eigentliche Funktionsweise des Plugins.

Das Gleiche gilt für den Ordner /node_modules/, in dem alle Tools wie Webpack, Babel und ESLint installiert sind.

PHP Dateien

Wichtig für die Initialisierung des Plugins sind die zwei PHP-Dateien plugin.php und src/init.php. Die erste Datei enthält nur den Plugin Header und bindet die zweite Datei ein.

Die init.php beinhaltet zwei Funktionen, welche das Block-Skript und die Block-Stylesheets im Theme und im WordPress Editor laden. Dazu werden die zwei neuen Action Hooks enqueue_block_assets und enqueue_block_editor_assets verwendet.

/**
 * Enqueue Gutenberg block assets for both frontend + backend.
 */
function themecoder_block_cgb_block_assets() {
	// Styles.
	wp_enqueue_style(
		'themecoder_block-cgb-style-css',
		plugins_url( 'dist/blocks.style.build.css', dirname( __FILE__ ) ),
		array( 'wp-editor' )
	);
}
add_action( 'enqueue_block_assets', 'themecoder_block_cgb_block_assets' );

/**
 * Enqueue Gutenberg block assets for backend editor.
 *
 */
function themecoder_block_cgb_editor_assets() {
	// Scripts.
	wp_enqueue_script(
		'themecoder_block-cgb-block-js',
		plugins_url( '/dist/blocks.build.js', dirname( __FILE__ ) ),
		array( 'wp-blocks', 'wp-i18n', 'wp-element', 'wp-editor' )
	);

	// Styles.
	wp_enqueue_style(
		'themecoder_block-cgb-block-editor-css',
		plugins_url( 'dist/blocks.editor.build.css', dirname( __FILE__ ) ),
		array( 'wp-edit-blocks', 'themecoder_block-cgb-style-css' )
	);
}
add_action( 'enqueue_block_editor_assets', 'themecoder_block_cgb_editor_assets' );

Aus Gründen der Übersichtlichkeit habe ich den Code und die Kommentare etwas gekürzt.

*UPDATE*
In der neuesten Version von Create-Guten-Block werden die Skripte inzwischen nur noch registriert und mit register_block_type() eingebunden:

register_block_type(
	'cgb/block-themecoder-block', array(
		'style'         => 'themecoder_block-cgb-style-css',
		'editor_script' => 'themecoder_block-cgb-block-js',
		'editor_style'  => 'themecoder_block-cgb-block-editor-css',
	)
);

Auch wenn sich die Implementierung geändert hat, ist der Zweck der Datei immer noch der Gleiche. Ich empfehle, die init.php selbst im Editor zu öffnen und den Code nachzuvollziehen.

Ordner dist/

dist steht für Distribution und enthält deshalb die gebündelten Files mit kompiliertem Code, also das Ergebnis unseres Build-Prozesses mit Webpack. Falls du die zwei PHP-Funktionen aufmerksam studiert hast, dann hast du bereits bemerkt, dass damit die drei Dateien vom Ordner dist/ geladen werden:

  • blocks.build.js
  • blocks.editor.build.css
  • blocks.style.build.css

Kommt dir das bekannt vor? Es handelt es sich um die Block-JS, Block-Stylesheet und Editor-Stylesheet, welche ich im ersten Teil als die zentralen Bestandteile eines Blocks vorgestellt habe.

Ordner src/

src steht für Source und damit für die Quelldateien. Hier findet die Entwicklung der Blocks statt.

Du kannst hier beliebig viele JS- und Sass-Dateien erstellen und von Webpack bündeln lassen. Auch die Ordnerstruktur bleibt dir überlassen. Nach dem Build-Prozess erhalten wir immer die drei kompilierten Dateien in /dist/, egal ob du einen oder zwei dutzend Blocks programmierst.

Mit Create-Guten-Block ist die Datei src/blocks.js als sogenannter Entry Point festgelegt. Das bedeutet, dass Webpack diese Datei einliest und alle Dateien bündelt, welche von dort importiert werden. Es ist praktisch der Start von unserem Trichter, in den wir unsere Source-Dateien und Code (ES6, JSX, SCSS) kippen, um bei der Metapher aus dem ersten Teil zu bleiben.

Block Development mit create-guten-block

Wer nun eine JavaScript-Datei aus dem Source-Ordner verändert und beispielsweise den Namen des Blocks anpasst, wird feststellen, dass die Änderung in WordPress erst einmal keine Auswirkung hat. Das liegt daran, dass im Gutenberg Editor nur die kompilierten Skripte aus dem Distribution-Ordner eingebunden werden, nicht die Source-Files.

Bevor wir deshalb mit der Entwicklung von Gutenberg Blocks loslegen können, müssen wir unseren Webpack-Prozess anstoßen, damit unser Code auch kompiliert wird. Wir gehen dafür zurück in die Kommandozeile und wechseln direk in unseren neuen Plugin-Ordner.

cd themecoder-block
npm start

Mit dem Befehl npm start kannst du den Build-Prozess starten.

create-guten-block build process

Webpack überwacht nun den src-Ordner automatisch und kompiliert den Code jedes Mal neu, wenn du eine Änderung durchführst. Bei Syntax-Fehlern in deinem Code wird dir ein Kompilierungsfehler in deinem Terminal angezeigt.

Neben dem Development Mode kannst du mit npm run build auch Production Code erzeugen:

npm run build

Dabei wird der Code kompiliert, minifiziert und alle Kommentare entfernt. Die Dateigröße wird damit soweit wie möglich reduziert, um ein möglichst performantes Einbinden unserer Blocks zu gewährleisten. Der Build-Prozess läuft einmalig und ist nicht für die laufende Entwicklung geeignet, sondern zur Bereitstellung deines Plugins für den Endnutzer.

Ausblick auf Teil 3

Nach dem Setup und Einrichtung unseres Plugins und dem Tooling können wir in Teil 3 endlich damit beginnen, unseren eigenen Block zu entwickeln. Fragen zum Block Setup oder Tooling können sehr gerne in den Kommentaren gestellt werden 🙂

Überblick über alle Beiträge dieser Serie