Individuelle Theme Einstellungen - Der Wordpress Theme Customizer

Bereits seit Wordpress 3.4 gibt es die Möglichkeit ein Theme-abhängiges Options Menü zu hinterlegen. Hier können die verschiedensten Einstellungsmöglichkeiten vorgegeben, und dem Theme Nutzer dann im Wordpress Backend unter "Appearance -> Customize" bzw. "Design -> Anpassen" zur Verfügung gestellt werden. So können beispielsweise Texte hinterlegt, CSS Klassen oder ganze CSS Dateien individuell aktiviert oder deaktiviert , Farben ausgewählt werden etc. Und das alles ohne das der Quellcode bearbeitet werden muss. Insbesondere wenn man ein Theme einem größeren Publikum zur Verfügung stellen will, zum Beispiel auf Wordpress.org oder als Premium Theme, gibt man damit dem Anwender damit eine elegante Möglichkeit an die Hand alle wichtigen Einstellung bequem vom Wordpress Backend aus vorzunehmen.

Im folgenden möchte ich an einem einfachen Beispiel zeigen wie eine individuelle Einstellungsmöglichkeit über die functions.php Datei eines Wordpress Themes angelegt und dann im Frontend genutzt werden kann.

Ein Beispiel aus der Wirklichkeit

Vor kurzem habe ich mein eigenes kleines Wordpress Theme Framework mit Namen "UnderStrap" vorgestellt. Dieses Theme Framework nutzt ein Slider Script (Owl Carousel von Bartosz Wojciechowski ) im Kopfbereich um von einem Widget zum nächsten zu "sliden" (siehe Demo). Das Script selber kommt mit vielerlei Optionen daher. Z.B. kann die Zeit in Millisekunden hinterlegt werden, die ein "Slide" angezeigt werden soll bevor der nächste erscheint. Das Problem ist, dass dieser Wert hardgecoded im JavaScript Code hinterlegt ist. Möchte man diesen ändern muß man das Script direkt editieren. Wesentlich eleganter wäre es, wenn man im Wordpress Backend ein Wert für die Zeit hinterlegt und das Script dann diesen nutzen würde.

wordpress_theme_customizer_slider_time_setting So soll das Ganze dann am Ende im Theme Customizer aussehen

Um dies zu bewerkstelligen muss zunächst eine Eingabemöglichkeit im Wordpress Backend geschaffen werden.

Von Sections, Settings und Controls - Die Theme Customizer Grundlagen in der functions.php Datei

Zunächst müssen wir in der functions.php Datei des Wordpress Themes eine eigene Funktion hinterlegen und diese dann an den Hook customize_register anhängen:

function understrap\_theme\_customize\_register( $wp\_customize ) {
    // Hier kommt dann der eigentliche Code rein

}
add\_action( 'customize\_register', 'understrap\_theme\_customize\_register' );

Der Name der Funktion ist frei wählbar, wichtig ist nur das der Name der Funktion der gleiche ist, der auch als customize_register Aktion hinzugefügt wird. Innerhalb dieser Funktion müssen jetzt drei Dinge eingefügt und definiert werden: Die "Section" (mit add_section), das "Setting" (mit add_setting) und die "Control" (mit add_control).

Mit `add_section` einen neune Bereich definieren

Mit "add_section" wird ein Bereich definiert, der mehrere Optionen umfassen kann. Denkbar ist zum Beispiel das wir nicht nur die Zeit des Sliders erfassen wollen, sondern auch andere Optionen für den Slider hinterlegt und zusammengefaßt werden sollen. Die "Section" dient also der Gruppierung und Sortierung von Optionen. Der obige Code muss wie folgt optimiert werden werden (Änderungen in grün):

function understrap\_theme\_customize\_register( $wp\_customize ) {
$wp\_customize->add\_section( 'understrap\_theme\_slider\_options', array(
    'title'          => \_\_( 'Slider Settings', 'understrap' ),
) );
}
add\_action( 'customize\_register', 'understrap\_theme\_customize\_register' );

Damit wird eine "Section" mit der ID understrap_theme_slider_options angelegt. Diese wird dann mit dem Titel "Slider Settings" im Wordpress Backend angezeigt werden. Jetzt haben wir eine "Section" der wir Einstellungen zuordnen können.

Mit `add_setting` eine Einstellung anlegen

Dies geschieht mit add_setting:

function understrap\_theme\_customize\_register( $wp\_customize ) {
$wp\_customize->add\_section( 'understrap\_theme\_slider\_options', array(
    'title'          => \_\_( 'Slider Settings', 'understrap' ),
) );

$wp_customize->add_setting( 'understrap_theme_slider_time_setting', array( 'default' => '5000' ) ); } add_action( 'customize_register', 'understrap_theme_customize_register' );

Hier wird die Einstellung mit der ID understrap_theme_slider_time_setting angelegt und dieser der Standardwert "5000" zugeordnet. Das Slider Script nutzt Werte in Milisekunden. "5000" steht also für 5 Sekunden. Dieser wert wird genutzt solange der User noch keinen eigenen Wert angegeben hat. Die ID dieses Wertes ist hier besonders wichtig. Nicht nur weil diese die Verbindung zwischen "control" und "setting" darstellt, sondern weil diese auch für die Ausgabe im Theme genutzt wird.

Mit `add_control` ein Eingabefeld anlegen

Mit add_control legt man Eingabemöglichkeiten an um die Einstellungen (oder deren Änderungen) dann auch erfassen zu können. Dies können Textfelder, Radiobuttons, Checkboxen, Upload-Felder usw. sein. Im vorliegenden Fall wollen wir ein einfaches Eingabefeld hinterlegen und der "Section" understrap_theme_slider_options zuordnen. Dies geschiet mit folgendem Code (Änderungen wieder in grün ):

function understrap\_theme\_customize\_register( $wp\_customize ) {
$wp\_customize->add\_section( 'understrap\_theme\_slider\_options', array(
    'title'          => \_\_( 'Slider Settings', 'understrap' ),
) );

$wp_customize->add_setting( 'understrap_theme_slider_time_setting', array( 'default' => '5000' ) ); $wp_customize->add_control( 'understrap_theme_slider_time', array( 'label' => __( 'Slider Time', 'understrap' ), 'section' => 'understrap_theme_slider_options', 'type' => 'text', 'settings' => 'understrap_theme_slider_time_setting' ) ); } add_action( 'customize_register', 'understrap_theme_customize_register' );

Mit label wird die Beschriftung des Eingabefeldes definiert. Mit section die zugehörige Sektion. In unserem Fall nehmen wir natürlich unsere zuvor festgelegte understrap_theme_slider_options Sektion. Mit type wird die Art der Eingabe definiert. In unserem Fall eben ein Textfeld (weitere Infos über mögliche Eingabearten finden sich hier). Zuguter letzt wird das Ganze noch mit der zuvor definierten Einstellung understrap_theme_slider_time_setting verknüpft.

Ausgabe des Wertes im Theme Code

Die Ausgabe des eingestellten Wertes ist dann denkbar einfach. Mit:

<?php echo get_theme_mod( 'understrap_theme_slider_time_setting' ); ?>

wird der Wert "5000"ausgegeben. wordpress_theme_customizer_slider_timeout_code Fügt man diesen PHP Schnipsel entsprechend innerhalb des JS Codes an der richtigen Stelle ein, kann dieser Wert von dem Theme Nutzer aus dem Backend heraus geändert werden, ohne das der JavaScript Code geändert werden muss. Wird dann aus der "5000" beispielsweise eine "3000" gemacht, erscheint ein "Slide" jeweils nur 3 Sekunden.