Selective Refresh im WordPress-Customizer

Mithilfe des Selective Refresh kann man im WordPress-Customizer bei der Änderung einer Customizer-Option nur einen Teil der Vorschau neu laden lassen statt der gesamten. Dadurch erhält der Nutzer einerseits schneller Feedback, andererseits wird der Server weniger belastet, da eben nur ein Teil statt der gesamten Vorschau neu geladen werden muss.

Disclaimer

Ich setze für diesen Blog-Beitrag bereits Grundkenntnisse in der Funktionalität des Customizers sowie in der Theme-Entwicklung voraus. Man sollte vorher also bereits selbst mal eine Customizer-Option angelegt haben.
Ansonsten ist es sicherlich hilfreich, sich einmal das Hinzufügen von einzelnen Customizer-Optionen (Settings) anzusehen:
WPTRT @GitHub

Customizer-Option vorbereiten

Nachdem die Customizer-Option bereits über $wp_customize->add_setting() hinzugefügt wurde, muss selbige nun für den Selective Refresh vorbereitet werden. Dazu holen wir uns die Option über $wp_customize->get_setting() und ändern ihren transport-Wert zu postMessage. Das sieht dann folgendermaßen aus:

$wp_customize->get_setting( 'my_option' )->transport = 'postMessage';

Doch warum genau postMessage?
Damit sagen wir WordPress, dass wir individuelles JavaScript nutzen möchten, um nur einen Teil der Customizer-Vorschau neu zu laden.

Selective Refresh/Add Partial nutzen

Nun weiß unser WordPress, dass wir bei der Option my_option selbst steuern möchten, was in der Customizer-Vorschau neu geladen wird. Also müssen wir nun angeben, was genau neu geladen wird.

Ein Beispiel aus dem Theme Twenty Seventeen:

	$wp_customize->selective_refresh->add_partial( 'blogname', array( 
		'selector' => '.site-title a',
		'render_callback' => 'twentyseventeen_customize_partial_blogname',
	) );

Über $wp_customize->selective_refresh->add_partial() können wir einen Teil der Seite als Selektor hinzufügen, der dann wiederum beim Ändern einer Option verändert wird.

In diesem Fall wird der Teil mit dem Selektor .site-title a immer dann geändert, wenn die Option blogname geändert wird. Dabei wird dann die Funktion twentyseventeen_customize_partial_blogname aufgerufen.

Und wie kann ich meinen neuen Inhalt nun anzeigen?

Über die im render_callback genannte Funktion können wir nun die Anzeige anpassen. Da wir im oben vorliegenden Fall einfach nur einen String – nämlich den Seitentitel – geändert ausgeben möchten, hält sich die Länge der Funktion in Grenzen.

Um die Funktionalität an diesem Punkt erst einmal grundlegend testen zu können, können wir einen einfachen Test erstellen:

function twentyseventeen_customize_partial_blogname() {
	echo 'Test';
}

Das Ergebnis muss jetzt sein, dass beim Ändern des Seitentitels im Customizer selbiger in der Vorschau durch „Test“ ersetzt wird.

In der Funktion, die als render_callback angegeben ist, haben wir natürlich sämtliche Funktionen von WordPress zur Verfügung. Die Originalfunktion aus dem Theme Twenty Seventeen sieht in dem Fall beispielsweise folgendermaßen aus:

/**
 * Render the site title for the selective refresh partial.
 *
 * @since Twenty Seventeen 1.0
 * @see twentyseventeen_customize_register()
 *
 * @return void
 */
function twentyseventeen_customize_partial_blogdescription() {
	bloginfo( 'name' );
}

Mehrere Optionen gleichzeitig neu laden

Die ID (der erste Parameter) bei $wp_customize->selective_refresh->add_partial() kann frei definiert werden. Dann muss über das Argument settings noch angegeben werden, bei welcher Option der render_callback ausgeführt werden soll. Das kann dann so aussehen:

	$wp_customize->selective_refresh->add_partial( 'my_option_partial', array(
		'selector' => '#masthead',
		'settings' => array(
			'my_option',
			'my_second_option'
		),
		'render_callback' => 'my_option_render_callback'
	) );

Das funktioniert natürlich auch bei nur einer Option, wenn man die ID anders benennen möchte.

 

Wenn alles geklappt hat, wird nur noch der im Selektor angegebene Teil der Webseite in der Customizer-Vorschau neu geladen. ⚡️

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.