Validierung von Customize-Settings mit Ausgabe von Fehlermeldungen

Seit WordPress 4.6 ist es recht leicht möglich, eine Validierung von Customize-Settings einzubauen, die dem User bei einem Fehler eine entsprechende Rückmeldung gibt. Hier zeige ich kurz, wie das funktioniert.

Es gibt verschiedene Möglichkeiten, diese Validierung einzubauen:

1. Über die Angabe eines validate_callback beim Anlegen einer Setting.
2. Über den sanitize_callback einer Setting.
3. Über eine eigene validate-Methode der WP_Customize_Setting-Klasse.

Ich beschreibe hier die zweite Variante – Beispiele für die erste und dritte sowie weitere Infos zu dem Thema findet ihr in dem Beitrag »Customizer APIs in 4.6 for Setting Validation and Notifications« von Weston Ruter.

Das hier ist beispielhaft meine Sanitize-Funktion zur Prüfung des ausgewählten Eintrags einer Select-Liste, die alle Kategorien der WordPress-Site enthält:

/**
 * Select sanitization callback for categories select control.
 *
 * @param string $input Value of select field.
 *
 * @return string
 */
function hannover_sanitize_categories_select( $input ) {
	$can_validate = method_exists( 'WP_Customize_Setting', 'validate' );

	$term = get_term( $input );

	if ( 'category' !== $term->taxonomy ||  is_wp_error( $term ) || null === $term ) {
		return $can_validate ? new WP_Error( 'nan', __( 'The ID does not match a category.', 'hannover' ) ) : null;
	}

	return $input;
}
Code-Sprache: JavaScript (javascript)

Es ist eigentlich recht einfach: um eine spezifische Fehlermeldung auszugeben, können wir ein WP_Error-Objekt zurückgeben, dem wir als ersten Parameter einen Fehler-Code und als zweiten die Fehlermeldung übergeben. Dieses Verhalten funktioniert allerdings erst ab WordPress 4.6, weshalb wir zunächst prüfen, ob die validate-Methode der WP_Customize_Setting-Klasse existiert.

Danach prüfen wir, ob es sich bei der Eingabe um eine Kategorie handelt und geben im Fehlerfall entweder (in WordPress 4.6 und neuer) eine konkrete Fehlermeldung zurück, oder null, wenn wir es mit einer älteren Version zu tun haben. In diesem Fall würde dem Nutzer eine allgemeine Fehlermeldung angezeigt, dass der Wert ungültig ist. Wenn alles in Ordnung ist, geben wir den Eingabewert zurück.

Die Fehlermeldung sieht dann so aus (dauert nach Ändern des Wertes etwas, während die Vorschau neu lädt):