Eigene Blöcke entwickeln

Die mitgelieferten Blöcke decken viel ab, aber nicht alles. Ein Yogastudio möchte vielleicht eine Kurskarte mit Uhrzeit, freien Plätzen und Buchungsknopf, ein Fahrradladen einen Rahmengrößen-Rechner, ein Café eine Karte mit Röstgrad und Herkunft. Mit eigenen Blöcken fügen sich solche Elemente nahtlos in den Editor ein: Redakteure setzen sie wie jeden anderen Block ein, stellen Optionen in der Seitenleiste ein und sehen sofort eine Vorschau. Diese Lektion zeigt, wie ein Block aufgebaut ist, wie man ihn mit dem offiziellen Werkzeug anlegt und wann er statisch oder dynamisch sein sollte.

1. Aufbau eines Blocks

Abb. 3.1Aufbau eines eigenen Blocks

Die Darstellung im Editor wird in JavaScript mit React geschrieben – im Editor ist WordPress eine React-Anwendung. Die Ausgabe auf der Website entsteht entweder beim Speichern als statisches HTML (save.js) oder bei jedem Seitenaufruf in PHP (render.php). Probieren Sie aus, wie sich block.json verändert:

1{
2  "$schema": "https://schemas.wp.org/trunk/block.json",
3  "apiVersion": 3,
4  "name": "studio/kurskarte",
5  "title": "Kurskarte",
6  "category": "widgets",
7  "icon": "calendar-alt",
8  "attributes": {
9    "kursId": { "type": "integer" },
10    "zeigePreis": { "type": "boolean", "default": true }
11  },
12  "supports": {
13    "color": { "background": true, "text": true },
14    "spacing": { "padding": true, "margin": true },
15    "html": false
16  },
17  "editorScript": "file:./index.js",
18  "style": "file:./style-index.css",
19  "render": "file:./render.php"
20}

2. Einen Block anlegen

Niemand schreibt die Grundstruktur eines Blocks von Hand. Das offizielle Werkzeug @wordpress/create-block erzeugt ein vollständiges Plugin mit Block, Build-Konfiguration und Beispielcode. Klicken Sie sich durch den Ablauf:

1import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
2import { PanelBody, ToggleControl } from '@wordpress/components';
3import ServerSideRender from '@wordpress/server-side-render';
4
5export default function Edit( { attributes, setAttributes } ) {
6    return (
7        <div { ...useBlockProps() }>
8            <InspectorControls>
9                <PanelBody title="Einstellungen">
10                    <ToggleControl
11                        label="Preis anzeigen"
12                        checked={ attributes.zeigePreis }
13                        onChange={ ( wert ) => setAttributes( { zeigePreis: wert } ) }
14                    />
15                </PanelBody>
16            </InspectorControls>
17            <ServerSideRender block="studio/kurskarte" attributes={ attributes } />
18        </div>
19    );
20}

3. Statisch oder dynamisch?

Die wichtigste Entscheidung beim Blockbau: Wird die Ausgabe beim Speichern festgelegt oder bei jedem Aufruf neu erzeugt? Statische Blöcke sind schnell und unabhängig vom Plugin – selbst wenn es deaktiviert wird, bleibt das gespeicherte HTML sichtbar. Ändert man aber später ihr Markup, müssen alte Blöcke migriert werden, sonst meldet der Editor „Dieser Block enthält unerwarteten Inhalt“. Dynamische Blöcke erzeugen ihre Ausgabe in PHP und zeigen immer aktuelle Daten; ihr Markup lässt sich jederzeit ändern. Üben Sie die Entscheidung:

1<?php
2$kurs_id = (int) ( $attributes['kursId'] ?? 0 );
3$kurs    = $kurs_id ? get_post( $kurs_id ) : null;
4if ( ! $kurs ) {
5    return;
6}
7$frei = (int) get_post_meta( $kurs_id, 'plaetze_frei', true );
8?>
9<div <?php echo get_block_wrapper_attributes(); ?>>
10    <h3><?php echo esc_html( get_the_title( $kurs ) ); ?></h3>
11    <p><?php echo $frei > 0 ? esc_html( "Noch $frei Plätze frei" ) : 'Ausgebucht'; ?></p>
12    <?php if ( $attributes['zeigePreis'] ?? true ) : ?>
13        <p><?php echo esc_html( get_post_meta( $kurs_id, 'preis', true ) ); ?> €</p>
14    <?php endif; ?>
15</div>

4. Neuere Möglichkeiten

Die Blockentwicklung wird laufend einfacher. Seit WordPress 7.0 lassen sich einfache Blöcke rein in PHP registrieren, ohne eigenes JavaScript und ohne Build-Schritt; der Editor erzeugt die Oberfläche aus den Attributen. Die Interactivity API ermöglicht Interaktionen auf der Website – etwa ein Filter im Stundenplan oder ein Merkzettel – mit wenigen Zeilen deklarativem Code statt eigener Skripte. Und über die Block Bindings API lassen sich Attribute vorhandener Blöcke mit Daten verbinden, etwa ein Absatz mit dem Feld „Uhrzeit“ eines Kurses. Bevor ein eigener Block entsteht, lohnt deshalb die Frage, ob ein vorhandener Block mit Bindings, ein Muster oder eine Blockvariante nicht schon genügt.

5. Ein Beispiel

Ein Yogastudio wünschte sich eine Kurskarte, die Redakteure auf beliebigen Seiten einsetzen können. Mit create-block entstand ein dynamischer Block studio/kurskarte. In der Seitenleiste wählt man den Kurs aus einer Liste und schaltet Preis und Buchungsknopf ein oder aus; der Block unterstützt Farben und Abstände aus der theme.json. render.php liest Titel, Uhrzeit, Preis und freie Plätze und zeigt bei ausgebuchten Kursen automatisch „Warteliste“. Weil der Block dynamisch ist, stimmen die Plätze immer, und als das Studio später ein Foto der Kursleitung ergänzen wollte, genügte eine Änderung in render.php – ohne dass eine einzige Seite neu gespeichert werden musste.

6. Häufige Fragen

Muss ich React können, um Blöcke zu bauen? Für die Editor-Oberfläche hilft Grundwissen in React, vor allem zu Komponenten und Zuständen. Die WordPress-Komponenten wie PanelBody, ToggleControl oder SelectControl nehmen aber viel Arbeit ab. Für einfache Blöcke genügen die Beispiele aus create-block und die Blockreferenz; mit PHP-only-Blöcken seit 7.0 geht es für manche Fälle sogar ganz ohne JavaScript.

Wohin gehören eigene Blöcke – ins Theme oder in ein Plugin? Meist in ein Plugin, denn Blöcke sind Inhalt: Wird das Theme gewechselt, sollen Kurskarten auf allen Seiten erhalten bleiben. Nur rein gestalterische Blöcke, die ausschließlich zu einem Theme passen, gehören ins Theme.

Wie aktualisiere ich einen statischen Block, ohne alte Inhalte zu zerstören? Über „deprecations“: Der Block bekommt eine Liste früherer Fassungen seiner save-Funktion. Der Editor erkennt alte Blöcke daran und wandelt sie beim nächsten Speichern in die neue Fassung um. Bei dynamischen Blöcken entfällt dieses Problem.

7. Übung zum Selbermachen

Wer Node.js installiert hat, erzeugt lokal mit npx @wordpress/create-block hinweis einen statischen Block, der einen Hinweistext mit farbigem Rand darstellt. Ergänzen Sie in block.json die Unterstützung für Farben und Abstände und prüfen Sie im Editor, dass die Einstellungen erscheinen. Legen Sie dann mit --variant dynamic einen zweiten Block an, der in render.php die Anzahl veröffentlichter Beiträge ausgibt. Vergleichen Sie, was nach dem Deaktivieren des Plugins mit beiden Blöcken auf der Seite passiert – ein anschauliches Beispiel für den Unterschied zwischen statisch und dynamisch.

Stand: September 2026, WordPress 7.1, PHP 8.3. Kursmaterial der Klarwerk Akademie. WordPress entwickelt sich schnell – maßgeblich ist die aktuelle Dokumentation auf developer.wordpress.org.