Customizer-Optionen werteabhängig ein-/ausblenden

Wer ein Theme selbst entwickelt, kommt früher oder später vermutlich an den Punkt, an dem er oder sie Customizer-Optionen hinzufügen möchte. Wie wäre es dann noch mit einer Möglichkeit, eine Customizer-Option abhängig des Wertes einer anderen Customizer-Option ein- oder auszublenden?

Genau darum wird es hier gehen und es ist einfacher, als man vermuten mag.

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-Optionen einbinden

Zuerst müssen natürlich mindestens zwei Customizer-Optionen vorhanden sein, damit eine von einer anderen abhängig sein kann. Dazu verwenden wir folgenden Code:

/**
 * Customizer settings
 *
 * @param WP_Customize_Manager $wp_customize
 */
function prefix_customizer_register( $wp_customize ) {
	$wp_customize->add_setting( 'my_option', [
		'default' => 0,
		'type' => 'theme_mod',
	] );
	$wp_customize->add_control( 'my_option', [
		'label' => __( 'My Option', 'prefix' ),
		'section' => 'my_section',
		'settings' => 'my_option',
		'type' => 'checkbox',
	] );
	$wp_customize->add_setting( 'my_option_dependency', [
		'default' => '',
		'type' => 'theme_mod',
		'sanitize_callback' => 'esc_textarea',
	] );
	$wp_customize->add_control( 'my_option_dependency', [
		'label' => __( 'My Option Dependency', 'prefix' ),
		'section' => 'my_section',
		'settings' => 'my_option_dependency',
		'type' => 'text',
	] );
}
add_action( 'customize_register', 'prefix_customizer_register' );

Soweit, so bekannt. Wichtig ist, dass die Option my_option vom Typ theme_mod sein muss. Andernfalls funktioniert die hier gezeigte – einfache – Variante nicht.

Ein- und Ausblenden aktivieren

Nun müssen wir versuchen, die Option my_option_dependency erst dann sichtbar zu bekommen, wenn die Checkbox von my_option ausgewählt wurde.
Dafür gibt es von WordPress selbst den active_callback. Diesen müssen wir bei der Control von my_option_dependency einfach anhängen. Das sieht dann so aus:

 	$wp_customize->add_control( 'my_option_dependency', array(
 		'label' => __( 'My Option Dependency', 'prefix' ),
 		'section' => 'my_section',
 		'settings' => 'my_option_dependency',
 		'type' => 'text',
 		'active_callback' => 'my_option_callback'
 	) );

Der active_callback verweist nun auf die Funktion my_option_callback. Diese ist dafür zuständig, den Zustand von my_option zu prüfen und anhand deren Wert true oder code>false auszugeben. Im Falle einer Checkbox eignet sich dazu folgender Callback:

/**
  * Check if my_option is true.
  *
  * @param WP_Customize_Control $control
  * @return bool
  */
 function my_option_callback( $control ) {
 	if ( $control->manager->get_setting( 'my_option' )->value() ) {
 		return true;
 	}
 	return false;
 }

Und das war es dann auch schon! Wenn die Checkbox bei my_option nun gesetzt wird, wird die Option my_option_dependency eingeblendet, ansonsten ist und bleibt sie ausgeblendet.

Ein Dank geht an Simon Kraft und Florian Brinkmann, die mir direkt oder indirekt geholfen haben, dass dieser Blog-Beitrag entstanden ist. ❤️