Wordpress Gutenberg durch eigene Blocks erweitern

13.06.2018 von Alexander Schwirjow

Der PHP-Teil

Die Basisstruktur von einem Block an sich ist einfach - es besteht aus dem PHP-Teil, welches defacto nur die Abhängigkeiten einbindet, und JavaScript, der den eigentlichen Block definiert. Das Ganze kann entweder im Plugin, aber auch als Part von Theme eingebunden werden, was mir persönlich sinnvoll erscheint, wenn die konkreten Elemente sich eben auf die konkrete Optik beziehen.

Um einen Block im Editor zu registrieren genügt es die entsprechende JavaScript Funktion per enqueue_block_editor_assets-Action zu laden:

add_action('enqueue_block_editor_assets', 'myblock_enqueue_block_editor_assets');
function myblock_enqueue_block_editor_assets() {
	wp_enqueue_script(
		'myblock',
		get_template_directory_uri().'/blocks/content/block.js',
		array( 'wp-blocks', 'wp-element' ),
		filemtime(get_template_directory().'/blocks/content/block.js')
	);
}

Wo genau das passiert ist weniger wichtig, aber es empfiehlt sich natürlich eine klare Struktur im Voraus zu überlegen. Sollte man aber auch immer tun. Kurze Erklärung

Die Zeile

get_template_directory_uri().'/blocks/content/block.js'

Ist verständlicherweise der Pfad zu der Datei, die den eigentlichen Block implementiert. get_template_directory_uri() ist dabei bekannterweiße die URL von dem Theme-Ordner.

array( 'wp-blocks', 'wp-element' ),

Sind die Abhängigkeiten von dem Script. Die Zusammensetzung kann sich je nach Block unterscheiden.

filemtime(get_template_directory().'/blocks/content/block.js')

Ist das Erstellungs-/ Bearbeitungsdatum der Datei. Durch das Anhängen von diesem Timestamp an den Request wird gewährleistet, dass immer die Neueste Version geladen ist und der Browsercache nicht greift. Nach dem es ja nur für Backend gedacht ist, wo die Ladezeit weniger wichtig als die Zuverlässigkeit ist, sollte man es auch nutzen.

Der JavaScript-Teil

Per se kann man logischerweise beliebiges Superset verwenden, sei es TypeScript, oder von mir aus CoffeeScript. Solange es am Ende eine im Browser ausführbare .js Datei erzeugt, sollte es auch funktionieren. Hier werden nur Basics behandelt, somit ist Vanilla-JS auch ausreichend. Für größere Projekte, die auch Skalieren sollen sieht es dann auch unter Umständen anders aus.

Die Grundstruktur sieht wie folgt aus:

( function() {
	var createElement = wp.element.createElement;
	var InnerBlocks = wp.editor.InnerBlocks;
	
	wp.blocks.registerBlockType( 'myblock', {
		title: 'MyBlock',
		icon: 'editor-contract',
		category: 'layout',
		
		edit() {
			return createElement( InnerBlocks );
		},
		
		save: function( props ) {
			return createElement('div', { className: 'myClass' }, createElement( InnerBlocks.Content );
		},
	} );
} )();

Wie man sieht ist es in diesem Fall eine "Self-Invoking"-Funktion, die eben einen Element Deklariert. Jetzt etwas konkreter:

var createElement = wp.element.createElement;
var InnerBlocks = wp.editor.InnerBlocks;

Sind die Teile der Gutenberg JavaScript, die verwendet werden. Diese werden als Referenz den jeweiligen Variablen zugeschrieben um innerhalb des nachfolgend angelegten Objektes bequem verwendet zu werden.

wp.blocks.registerBlockType

Ist eben die Funktion, die einen Block erzeugt. Es besteht mindestens aus dem Namen, den Eigenschaften (title, icon, category) und beiden Funktionen edit und save. Der Name ist hier als eindeutige Kennung zu verstehen, nicht der Angezeigter Titel (siehe die Liste unten). Die Eigenschaften beschreiben im Endeffekt die Darstellung in der Auswahlliste

title - der angezeigter Name
icon - Icon, z.B. eines der Dashicons
category - Bereich, in dem es erscheint (hier: Layout-Elemente)

Mehr können Sie auf https://github.com/WordPress/gutenberg/blob/master/docs/block-api/attributes.md nachlesen.

Die beiden Funktionen sind für die Darstellung im Editor (edit), und den Inhalt, der gespeichert und im Frontend dargestellt wird(save) zuständig. Der entsprechende Inhalt wird von der jeweiligen Funktion zurückgegeben. Dabei kann es defacto beliebiger Content sein, von RichText oder Bild, bis zu komplexen Strukturen. Tutorials für die Erstellung einfacher Elemente finden Sie in dem offiziellem Repository auf GitHub. Hier wird ein Block erzeugt, der andere Blöcke umschließt, was in den Anleitungen nicht oft vorkommt, aber oft nützlich ist. Konkret hier - um den Inhalt in einen div zu packen, der eine bestimmte Klasse trägt. Jetzt im Detail:

edit() {
	return createElement( InnerBlocks );
},

Für die Bearbeitungsansicht wird hier nicht viel mehr gebraucht, als die innen liegende Blocks als Element zurückzugeben.

save: function() {
	return createElement('div', { className: 'myClass' }, createElement( InnerBlocks.Content );
},

Vor dem Speichern wird der Inhalt hingegen mit einem Element umschlossen, der die Klasse "myClass" zwangsläufig hat. Mehr ist es nicht.

Wozu ist es gut

Ganz einfach - die Klasse kann anschließend in CSS formatiert werden. Ein Beispiel:

.myClass {
	width: 100%;
	max-width: 1280px;
	margin: 0 auto;
}

würde den Content auf den Bildschirmen von über 1280px zentriert und auf die Breite begrenzt darstellen. Alternativ könnte der Hintergrund mit Farbe oder Parallax belegt werden, oder Sie implementieren ein ordentliches mehrdimensionales CSS-Grid-Layout Ihrer Fantasie sind aber keine Grenzen gesetzt.