Block-Templates für neue Seiten, Beiträge und Custom Post Types definieren

Es gibt bei dem Block-Editor von WordPress die Möglichkeit, Templates von Blöcken zu definieren, die beim Erstellen neuer Inhalte automatisch eingefügt werden. Hier zeige ich, wie das funktioniert und wie auch wiederverwendbare Blöcke in Templates genutzt werden können.

Wofür sind Block-Templates gut?

Nehmen wir an, dass ihr auf einer Website immer oder sehr häufig bei neuen Seiten einen oder mehrere bestimmte Blöcke einbindet, beispielsweise einen Container-Block und darin eine Überschrift.

In solchen Fällen ist es praktisch, wenn direkt beim Anlegen der Seiten nicht der Standard-Absatzblock vorhanden ist, sondern bereits der Container mit einer leeren Überschrift eingefügt ist.

Und genau dafür gibt es Block-Templates.

Ein Block-Template erstellen

Die Post-Type-Objekte haben eine Eigenschaft template, der ein Array von Blöcken zugewiesen werden kann.

Wir hängen uns dafür in den init-Action-Hook und verändern das oder die gewünschten Objekte entsprechend. Der Code für ein einfaches Block-Template für Seiten sieht dann beispielsweise so aus:

/**
 * Add group block to new pages.
 * 
 * @link https://developer.wordpress.org/block-editor/developers/block-api/block-templates/
 */
function slug_post_type_template() {
	$page_type_object = get_post_type_object( 'page' );
	$page_type_object->template = [
		[ 'core/group', [], [
			[ 'core/paragraph' ],
		] ],
	];
}
add_action( 'init', 'slug_post_type_template' );
Code-Sprache: PHP (php)

Wie erwähnt hooken wir unsere Funktion an die init-Action. Innerhalb der Funktion holen wir uns das Post-Type-Objekt für Seiten und übergeben ein Array mit den Blöcken des Templates an template.

Dabei handelt es sich um Arrays innerhalb eines anderen Arrays, die die Blöcke der obersten Ebene abbilden (in unserem Fall nur einen Gruppe-Block). Als zweiten Wert innerhalb eines Block-Arrays könnten wir Eigenschaften für diesen Block festlegen, im Fall des Gruppe-Blocks zum Beispiel vordefinierte Werte für Hintergrund- und Textfarbe. Dieser Eintrag ist bei uns leer.

Der dritte Wert ist optional ein Array mit weiteren Block-Arrays, die dann innerhalb des Eltern-Blocks eingefügt werden – in unserem Beispiel wird so ein Absatz-Block in den Gruppe-Block eingefügt. Das funktioniert natürlich nur bei Blöcken, die verschachtelte Blöcke erlauben.

Eigenschaften für Blöcke festlegen

Ich habe es bereits kurz angerissen: über den zweiten Wert eines Block-Arrays können wir die Werte des Blocks verändern. So ist es beispielsweise möglich, dem Gruppe-Block eine Hintergrundfarbe zuzuweisen.

Dafür übergeben wir im folgenden Code-Block den Slug einer Farbe, die wir über einen add_theme_support()-Aufruf eingefügt haben, wie es in der Theme-Support-Referenz auf developer.wordpress.org beschrieben ist:

/**
 * Add group block to new pages.
 * 
 * @link https://developer.wordpress.org/block-editor/developers/block-api/block-templates/
 */
function slug_post_type_template() {
	$page_type_object = get_post_type_object( 'page' );
	$page_type_object->template = [
		[ 'core/group', [ 'backgroundColor' => 'light' ], [
			[ 'core/paragraph' ],
		] ],
	];
}
add_action( 'init', 'slug_post_type_template' );
Code-Sprache: PHP (php)

Wiederverwendbare Blöcke in Block-Templates verwenden

Wenn ihr einmal den Fall habt, dass ein wiederverwendbarer Block in einem Block-Template zum Einsatz kommen soll, ist auch das möglich. Ein wiederverwendbarer Block ist vom Typ core/block und bekommt als ref-Attribut die ID des Block-Posts (im Hintergrund sind wiederverwendbare Blöcke ein Custom-Post-Type).

Wir müssen also die ID dieses Posts ermitteln und sie dann in dem Block-Template verwenden. Das könnte beispielsweise so aussehen:

$unsere_leistungen_block = new WP_Query(
	[
		'post_type' => 'wp_block',
		'title' => 'Unsere Leistungen',
	]
);

if ( ! empty( $unsere_leistungen_block->posts ) ) {
	$page_type_object->template = [
		[ 'core/block', [ 'ref' => $unsere_leistungen_block->posts[0]->ID] ],
	];
}
Code-Sprache: PHP (php)

Wir holen zunächst mit einer WP_Query() die wiederverwendbaren Blöcke mit dem Titel »Unsere Leistungen«, prüfen danach ob wir ein Ergebnis haben und setzen die ID des ersten Blocks für das ref-Attribut des core/block-Blocks in dem Template ein.

Wenn sich der Titel dieses Blocks verändert, müsste der Code natürlich entsprechend angepasst werden.

Block-Templates für Beiträge und Custom-Post-Types verwenden

Nach demselben Prinzip wie für Seiten können auch Block-Templates für Beiträge und Custom-Post-Types definiert werden. Dafür wird bei dem get_post_type_object()-Aufruf entsprechend der Parameter angepasst, etwa post statt page um ein Template für Beiträge zu erstellen.

Wenn ihr ein Template für einen eigenen Post-Type erstellen möchtet, könnt ihr das auch direkt beim Aufruf von register_post_type() tun und das Array mit den Blöcken für den template-Eintrag übergeben.

Ein Beispiel dazu und mehr gibt es auf der Templates-Seite in der Block-Editor-Referenz. Dort wird auch beschrieben, wie ein Template gegen Änderungen geschützt werden kann, sodass der User die Blöcke nicht entfernen, keine neuen hinzufügen und/oder die Blöcke verschieben kann.