WordPress-Theme-Customizer um eigene Farbschemata erweitern

In unserem heutigen Tutorial möchte ich euch eine nützliche Theme-Erweiterung zeigen: Wie erweitere ich den Customizer von WordPress um verschiedene Farbschemata, um diese im Frontend entsprechend auszuwerten.

Diese Implementation wird bereits in unseren Hamburg-Theme eingesetzt, um dem Benutzer von Haus aus drei verschiedene Farbschemata zu liefern. Zusätzlich kann in einem Child-Theme, über den entsprechenden Filter, einfach und schnell ein neues Schema hinzugefügt werden.

Der Theme-Customizer in Aktion:

Für den kompletten Customizer benötigen wir folgende vier Bausteine:

• Eigene Customizer-Klasse
• Registrieren des Customizers
• Farbschema bereitstellen
• Ausgabe des Farbschemas im Frontend

Eigene Customizer-Klasse definieren

WordPress bietet bereits seit der Version 3.4 mit der Customizer API eine umfangreiche Schnittstelle um das Theme nach Wünschen on the fly zu gestalten. Diese API wollen wir uns heute zu nutze machen und entsprechend erweitern.

Da wir für unsere Farbschemata nicht mit normalen Select-Feldern oder Checkboxen arbeiten wollen, sondern auch die verschiedenen Schemata visuell hervorheben möchten, erstellen wir uns zuerst unsere eigene Customizer-Klasse. Diese Klasse erbt die Basisklasse WP_Customize_Control:

class Marketpress_Customizer_Color_Scheme extends WP_Customize_Control {

	protected $schemes, $default_scheme;

 	/**
	 * Constructor.
	 *
	 * @param	WP_Customize_Manager $manager
	 * @param	String $id
	 * @param	Array $args
	 * @return	Void
	*/
	public function __construct( WP_Customize_Manager $manager, $id, Array $args = array() ) {
		$this->schemes		= $args[ 'schemes' ];
		$this->default_scheme	= $args[ 'default' ];
		parent::__construct( $manager, $id, $args );
	}

	/**
	 * Callback to render the Content in our Customizer-Panel
	 *
	 * @return Void
	*/
	public function render_content() {
		$current = get_theme_mod( $this->id, $this->default_scheme );
		?>

<?php foreach ( $this->schemes as $key => $values ) { echo ‘
• ‘; echo $this->get_radio( $key, $values, $current ); echo ‘

‘; } ?>

		<?php
	}

	/**
	 * Generate a radio-button
	 *
	 * @param	String $key
	 * @param	Array $values
	 * @param	String $current
	 *
	 * @return	String $output
	*/
	protected function get_radio( $key, Array $values, $current ) {
		$output = sprintf(
			' %6$s',
			"$this->id-$key",
			$values[ 'foreground' ],
			$values[ 'background' ],
			$this->id,
			checked( $key, $current, FALSE ),
			esc_html( $values[ 'label' ] ),
			$key,
			$this->get_link()
		);
		return $output;
	}
}

Innerhalb unseres Konstruktors müssen wir den Konstruktor der geerbten WP_Customize_Control-Klasse aufrufen um die entsprechenden Argumente zu setzen.

Interessant wird es bei der Methode render_content(). Mit dieser überschreiben wir die bereits vorhandene Methode aus der Basisklasse, um die Anzeige entsprechend zu manipulieren. Standardmäßig wird nur Input-Text, -Checkbox, -Radio, Select-Fields und Dropdown-Pages unterstützt. Für unsere neue Methode möchten wir eigene Radio-Buttons mit entsprechender farblicher Hervorhebung, je nach Farbschema, generieren.

Registrieren des Customizers

Um den Customizer auch nutzen zu können, müssen wir diesen registrieren. Hierfür hat WordPress den Hook customize_register bereitgestellt.

add_action( 'customize_register', 'marketpress_register_color_scheme_customizer' );

/**
 * Adding our own colorscheme "burly-wood"
 *
 * @wp-hook 	customize_register
 * @param	WP_Customize_Manager $wp_customize
 * @return	Void
 */
function marketpress_register_color_scheme_customizer( WP_Customize_Manager $wp_customize ) {

	$schemes	= marketpress_get_color_schemes();
	$section	= 'color_scheme_section';
	$key		= 'color_scheme';
	$title		= __( 'Color scheme', 'marketpress' );
	$section_args	= array (
		'title'    => $title,
		'priority' => 5,
	);

	$wp_customize->add_section(
		$section,
		$section_args
	);

	$wp_customize->add_setting(
		$key,
		array ( 'default' => 'default' )
	);

	$customizer_args = array (
		'label'    => $title,
		'section'  => $section,
		'settings' => $key,
		'schemes'  => $schemes,
		'default'  => 'blue'
	);

	$wp_customize->add_control(
		new Marketpress_Customizer_Color_Scheme(
			$wp_customize,
			'color_scheme',
			$customizer_args
		)
	);
}

Unser Callback bekommt eine Instanz der Klasse WP_Customize_Manager übergeben. Mit dieser Instanz können wir unsere eigenen Sektionen und Kontroll-Elemente definieren.

Zuerst registrieren wir mit der Methode add_section() eine neue Sektion im Customizer-Panel, da wir einen separaten Punkt haben möchten.
Mit der Methode add_setting() können wir eine neue Einstellung registrieren. Der $key ist dabei später zum Laden und Ausgeben der gespeicherten Einstellung wichtig. Der “transport” ist per Default auf “refresh”, also: “Wenn ich hier einen Wert ändere, zeige die Änderung on the fly an”. Der “type” ist per Default auf “theme_mod” gesetzt. Alternative können wir auch “option” wählen um eine eigene Option anzulegen. Da wir aber später per get_theme_mod() auf unser neues Feature zugreifen wollen, belassen wir dies so.

Tipp: Als “type” in der Methode add_setting() kann man auch einen eigenen definieren und später beim Speichern per Filter auf customize_update_{type} eine Speicherroutine dafür festlegen.

Zu guter letzt registrieren wir mit der Methode add_control() unsere neue Klasse mit den hübschen Kontroll-Elementen.

Farbschema bereitstellen

Um verschiedene Farbschemata im Customizer bereitzustellen, brauchen wir die folgende Hilfsfunktion an unterschiedlichen Stellen:

/**
 * Get color schemes.
 *
 * @return-filter	marketpress_get_color_schemes
 * @return			Array
 */
function marketpress_get_color_schemes() {

	$schemes = array (
		'blue' => array (
			'background' => '2CC2E1',
			'foreground' => 'fff',
			'label'      => _x( 'Blue', 'Color scheme picker', 'marketpress' )
		),
		'yellow' => array (
			'background' => 'ffbc00',
			'foreground' => 'fff',
			'label'      => _x( 'Yellow', 'Color scheme picker', 'marketpress' )
		)
	);

	return apply_filters( 'marketpress_get_color_schemes', $schemes );
}

Die Funktion beinhaltet zusätzlich einen Return-Filter um eigene Schemata zu registrieren. Wichtig für die korrekte Darstellung hierbei ist die Definition der folgenden 3 Werte im Schema-Array:

• Background (Hintergrund)
• Foreground (Textfarbe)
• Label (Beschriftung im Customizer)

Der Key ist zugleich auch der Schemaname und wird später in einer Body-Klasse hinzugefügt.

Beispiel-Filter für eigenes Schema

Ein Beispielfilter, um unser eigenes Schema “Burly-Wood” zu registrieren, sieht wie folgt aus:

add_filter( 'marketpress_get_color_schemes', 'marketpress_demo_filter_add_color_scheme' );

/**
 * Adding our own colorschema “burly-wood”
 *
 * @wp-hook 	marketpress_get_color_schemes
 * @param	Array $schemes
 * @return	Array $schemes
 */
function marketpress_demo_filter_add_color_scheme( Array $schemes = array() ) {

	$schemes[ 'burly-wood' ] = array(
		'background' => 'deb887',
		'foreground' => '000000',
		'label'      => _x( 'Burly Wood', 'Color scheme picker', 'marketpress' )
	);

	return $schemes;
}

Ausgabe des Colorschemas im Frontend

Nachdem wir den Customizer erweitert haben und entsprechend die Einstellungen abspeichern, müssen wir diese noch im Frontend ausgeben und unser CSS erweitern. Hierfür nutzen wir in unserem Hamburg-Theme den Hook body_class, um unser Farbschema anschließend entsprechend per CSS gestalten zu können:

add_filter( 'body_class', 'marketpress_filter_body_class_add_colorscheme' );

/**
 * Adding our color scheme to the body-classes
 *
 * @wp-hook	body_class
 * @uses	get_theme_mod, marketpress_get_color_schemes
 * @param	Array $classes
 * @return	Array $classes
 */
function marketpress_filter_body_class_add_colorscheme( Array $classes ) {

	$scheme		= get_theme_mod( 'color_scheme' );
	$schemes	= marketpress_get_color_schemes();

	if ( empty ( $schemes ) || !array_key_exists ( $scheme, $schemes ) ) {
		$scheme = "default";
	}

	$classes[] = "color-scheme-" . $scheme;

	return $classes;
}

Über die WP-Funktion get_theme_mod() (wir haben bei add_setting() den Default-Wert bei “type” gelassen) holen wir unser gespeichertes “color_scheme” (unser $key in add_setting()) und fügen diesen als CSS-Klasse zum Body-Element hinzu.

Fazit

Ich hoffe das Tutorial hat euch gefallen und ihr konntet einen Einblick in die Customizer-API bekommen. Die Farbschema-Erweiterung ist mittlerweile ein geschätztes Standardfeature in unserem Hamburg-Theme geworden. In vielen Kundenprojekten konnten wir schon den Nutzen aus unterschiedlichsten Customizer-Erweiterungen ziehen. Welche Erweiterungen für die Customizer-API nutzt ihr?