In meinem Artikel von letzter Woche habe ich mich damit beschäftigt, wie Panels, Sections und Controls mit der JS-API des Customizers erstellt werden können. In diesem Beitrag geht es um die Erstellung von Settings über die Customize-JS-API, die standardmäßig weiterhin über die PHP-API registriert werden müssen.
Meist ist genau bekannt, wie viele und welche Settings benötigt werden, sodass sie einfach in PHP angelegt werden können. Ich habe jedoch den Fall, dass die Nutzer – ähnlich wie bei den Menü-Verwaltung im Customizer – vordefinierte Sections mit Controls selbst hinzufügen und entfernen können sollen, sodass ich vorher die Anzahl der benötigten Settings zum Speichern der Werte nicht weiß. Dafür ist es nützlich, dass Settings auch über die JS-API erstellt werden können – das ist aber ein wenig komplizierter, als Panels, Sections und Controls anzulegen.
Zur Vorbereitung binden wir wie im Beitrag letzter Woche wieder eine JS-Datei in den Customizer ein und füllen sie mit dem folgenden Code:
/**
* Custom JavaScript functions for the customizer controls.
*
* @version 2.0.0
*
* @package Hannover
*/
;(function (api) {
api.bind('ready', function () {
// Create a setting.
var setting = new api.Setting( 'portfolio_category_page' );
api.add( setting );
});
})(wp.customize);Code-Sprache: JavaScript (javascript)Das ist der JS-Teil zum Anlegen eines Settings mit der ID portfolio_category_page. Das sieht jetzt eigentlich einfacher aus als die Teile von letzter Woche, aber wir müssen zusätzlich noch einen PHP-Filter nutzen, damit die Registrierung des portfolio_category_page-Settings funktioniert. Dafür fügen wir den folgenden Code in eine passende PHP-Datei ein, beispielsweise die, in der ihr auch den Aufruf zur Einbindung der JS-Datei gemacht habt:
// Filter the dynamically created customizer settings.
add_filter( 'customize_dynamic_setting_args', 'hannover_filter_dynamic_setting_args', 10, 2 );
/**
* Filters a dynamic setting’s constructor args.
*
* For a dynamic setting to be registered, this filter must be employed
* to override the default false value with an array of args to pass to
* the WP_Customize_Setting constructor.
*
* @link https://wordpress.stackexchange.com/a/286503/112824
*
* @param false|array $setting_args The arguments to the WP_Customize_Setting constructor.
* @param string $setting_id ID for dynamic setting, usually coming from `$_POST['customized']`.
*
* @return array|false
*/
function hannover_filter_dynamic_setting_args( $setting_args, $setting_id ) {
if ( 'portfolio_category_page' === $setting_id ) {
$setting_args = [
'type' => 'theme_mod',
];
}
return $setting_args;
}Code-Sprache: PHP (php)An den customize_dynamic_setting_args-Filter hängen wir die hannover_filter_dynamic_setting_args()-Funktion an, der als Parameter die Argumente des Settings und die ID übergeben werden. Diese Funktion wird jetzt für jedes Customize-Setting aufgerufen – $setting_args ist dabei für Settings, die über die Customize-JS-API erstellt werden, standardmäßig false, und wenn dieser Wert für ein Setting zurückgegeben wird, wird es nicht registriert.
Wir müssen also für alle Settings, die wir über die Customize-JS-API registrieren, $setting_args in ein Array umwandeln. In unserem Beispiel prüfen wir auf die exakte ID portfolio_category_page und verändern in dem Fall $setting_args entsprechend. Hier könnt ihr alle Optionen der PHP-Methode zum Hinzufügen von Settings nutzen, also beispielsweise einen Sanitize-Callback angeben.
Wenn ihr beispielsweise Settings mit dem ID-Format portfolio_category_page[1], portfolio_category_page[2] und portfolio_category_page[3] habt, würde die Prüfung in hannover_filter_dynamic_setting_args() am besten über einen regulären Ausdruck erfolgen. Weston Ruter hat dazu in einer Antwort auf wordpress.stackexchange.com einige Beispiele aus Core und Plugins verlinkt.
Jetzt sollten wir problemlos das Setting portfolio_category_page für eine Control angeben können.