Selective Refresh im WordPress-Customizer
Veröffentlicht: – Kommentar hinterlassen Letzte Aktualisierung:
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';
Code-Sprache: PHP (php)
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',
) );
Code-Sprache: PHP (php)
Ü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';
}
Code-Sprache: PHP (php)
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' );
}
Code-Sprache: PHP (php)
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', [
'selector' => '#masthead',
'settings' => [
'my_option',
'my_second_option',
],
'render_callback' => 'my_option_render_callback',
] );
Code-Sprache: PHP (php)
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. ⚡️