Customize-JS-API zur Erstellung von Panels, Sections und Controls nutzen

Bisher habe ich für den WordPress-Customizer eigentlich nur die PHP-API genutzt. Seit ich den Beitrag von Weston Ruter über die Neuerungen bei der JS-API in WordPress 4.9 gelesen habe, wollte ich das ändern und mich mehr mit der Customize-JS-API beschäftigen. Hier erkläre ich, wie sich damit Panels, Sections und Controls anlegen lassen.

Warum die Customize-JS-API Vorteile gegenüber der PHP-API hat

Darüber hatte ich mir bisher keine großen Gedanken gemacht – ich habe mit der PHP-API angefangen und das halt so weitergemacht. Aber die PHP-API ist – wie Weston in seinem oben verlinkten Beitrag schreibt – nur ein Wrapper für die JS-API. Er schreibt weiterhin (übersetzt aus dem Englischen):

»Der Punkt hierbei ist, dass die JavaScript-API direkt genutzt werden muss, damit der Customizer skalieren kann. Deshalb sind die Customize-JS-API-Verbesserungen in 4.9 wichtig, weil sie viele langjährige Ärgernisse und Unzulänglichkeiten mit der JS-API beheben.«

Weston Ruter in Improvements to the Customize JS API in 4.9

Weston Ruter in Improvements to the Customize JS API in 4.9

Also dachte ich mir, probiere ich das doch bei nächster Gelegenheit aus. Und da ich mein Hannover-Theme (und Bornholm) dringend optisch und technisch überarbeiten muss, hatte ich sie da bereits.

Nachteil der Customize-JS-API

Es gibt auch einen großen Nachteil der Customize-JS-API: sie ist bisher mehr schlecht als recht dokumentiert. Teilweise dauert es ein bisschen, bis man sich die Infos zusammengesucht hat, auch wenn die Funktionsweise der API theoretisch auch aus einer (oder wenigen) Core-Dateien herausgearbeitet werden könnte – das hat mir persönlich aber nur wenig geholfen.

Hilfreicher war Google, und immer wieder auftauchende Antworten oder Artikel von Weston Ruter 🙂

Doch kommen wir jetzt zum eigentlichen Thema.

Panels, Sections und Controls mit der JS-API erstellen

Zuerst müssen wir eine JavaScript-Datei in den Customizer einbinden, und zwar in den Bereich der Controls, nicht in die Vorschau. Dazu nutzen wir den folgenden Code:

// Include scripts into the customizer.
add_action( 'customize_controls_enqueue_scripts', 'hannover_customizer_controls_script' );

/**
 * Prints styles inside the customizer view.
 */
function hannover_customizer_controls_script() {
	// Add script control section.
	wp_enqueue_script( 'hannover-customize-controls', get_theme_file_uri( 'assets/js/customize-controls.js' ), [], null, true );
}
Code-Sprache: PHP (php)

Jetzt erstellen wir die customize-controls.js im assets/js-Ordner und füllen sie mit diesem Inhalt:

/**
 * Custom JavaScript functions for the customizer controls.
 *
 * @version 2.0.0
 *
 * @package Hannover
 */
;(function (api) {
	api.bind('ready', function () {
		// Create theme options panel.
		api.panel.add(
			new api.Panel('hannover_theme_options', {
				title: 'Theme Options',
			})
		);

		// Add section.
		api.section.add(
			new api.Section('hannover_example_section', {
				title: 'Example Section',
				panel: 'hannover_theme_options',
				customizeAction: 'Customizing ▸ Theme Options'
			})
		);

		// Add checkbox control.
		api.control.add(
			new api.Control('hannover_example_control', {
				setting: 'hannover_example_setting',
				type: 'checkbox',
				section: 'hannover_example_section',
				label: 'Check this box to do something.'
			})
		);
	});
})(wp.customize);
Code-Sprache: JavaScript (javascript)

Zunächst warten wir darauf, dass der Customizer fertig ist und fügen dann ein Panel, eine Section und eine Control ein. Wie ihr seht, ähnelt sich die Vorgehensweise beim Hinzufügen der drei Elemente sehr. Der erste Parameter der new-Aufrufe ist die ID, danach kommt ein Objekt mit den Optionen, die von der PHP-API bekannt sind.

Eine Ausnahme hiervon: Bei new api.Section gibt customizeAction an, was in der Section-Ansicht über dem Titel steht:

Und damit wären wir bereits am Ende dieses kleinen Einstiegsbeitrags in die Customize-JS-API. Wichtig ist, dass ihr die Settings in der Regel weiter über die PHP-API erzeugen müsst – sonst werden die Werte nicht in der Datenbank gespeichert. Es gibt aber auch einen Weg, die Settings dynamisch über die JS-API zu erzeugen, aber das ist Thema eines anderen Beitrags.