Das eigene WordPress-Theme erstellen – #18: Der Customizer

In dieser Artikelreihe geht es darum, ein WordPress-Theme zu erstellen – von Grund auf. In Teil 18 geht es um den Customizer, in dem der Nutzer Einstellungen des Themes ändern kann.

Kurz noch zum letzten Teil der Reihe: Wir (beziehungsweise eher ich) haben vergessen, die beiden Widget-Dateien in die functions.php einzubinden und die Widgets zu registrieren – so kann das natürlich nicht funktionieren. Wir müssen also erst mal ans Ende der functions.php folgenden Code schreiben, damit die Widgets auch wirklich einsatzbereit sind:

require get_template_directory() . '/inc/class-recent-galleries.php';
require get_template_directory() . '/inc/class-featured-galleries.php';
 
function register_bornholm_widgets() {
    register_widget( 'Bornholm_Recent_Galleries' );
    register_widget( 'Bornholm_Featured_Galleries' );
}
add_action( 'widgets_init', 'register_bornholm_widgets' );
Code-Sprache: JavaScript (javascript)

Mit require binden wir einfach die Dateien ein und an die register_widget()-Funktion werden die Namen der Widgets übergeben, die wir gerne registrieren möchten. Damit das auch wirklich funktioniert, muss register_bornholm_widgets im Anschluss an den widgets_init-Hook angehängt werden.

Der Customizer

Nicht, dass es vergessen wird: Auch die Customizer-Funktionen kommen in eine seperate Datei, die customizer.php im inc-Ordner, die natürlich wieder in die eingebunden werden muss:

require get_template_directory() . '/inc/customizer.php';
Code-Sprache: JavaScript (javascript)

Für Einstellungen im Customizer gibt es einige wenige Methoden der WP_Customize_Manager-Klasse, die wir gleich nutzen werden – im Voraus hier eine Auflistung mit kurzer Erklärung:

add_setting(): Diese Methode ist für die Erstellung einer Einstellung zuständig und kümmert sich um die Speicherung und Überprüfung der eingegebenen Werte.
add_control(): Die Methode zeigt ein Formularelement im Customizer an und ist mit einer Einstellung verbunden.
add_section(): Bietet die Möglichkeit, für die Formularelemente einen eigenen Bereich im Customizer anzulegen.
add_panel(): Kommt bei uns nicht zum Einsatz, bietet aber die Möglichkeit, mehrere Sections in einem Oberbereich zusammenzufassen.

Alle diese Methoden kommen in eine Funktion, die an den Action-Hook customize_register angehängt wird – dadurch wird die WP_Customize_Manager-Klasse in der Funktion nutzbar. Es gibt auch die Möglichkeit, all das mit JavaScript umzusetzen, allerdings habe ich mich damit noch nicht näher beschäftigt.

Fangen wir mit dem Grundgerüst der Funktion an:

function bornholm_customize_register( $wp_customize ) {
}
 
add_action( 'customize_register', 'bornholm_customize_register' );
Code-Sprache: PHP (php)

Wie bereits beschrieben, wird die Funktion an customize_register gehängt, sodass $wp_customize ein Objekt der WP_Customize_Manager-Klasse ist.

Zuerst möchten wir dem Nutzer ermöglichen, die Anzahl an Galerien aus derselben Kategorie einzustellen, die in der Einzelansicht einer Galerie angezeigt werden. Dafür reicht ein einfaches Eingabefeld mit einem Standardwert aus. Dafür kommt folgender Code in die bornholm_customize_register()-Funktion:

$wp_customize->add_setting( 'number_of_galleries_from_same_category_on_single_gallery_page', array(
    'default'           => 3,
    'sanitize_callback' => 'absint'
) );
$wp_customize->add_control( 'number_of_galleries_from_same_category_on_single_gallery_page', array(
    'type'     => 'number',
    'section'  => 'gallery',
    'label'    => __( 'Number of galleries from the same category to show in the single view of a gallery (0 if no galleries should be displayed)', 'bornholm' ),
) );
Code-Sprache: PHP (php)

Wie bereits beschrieben, ist add_setting() für die Speicherung der Werte eines Formularelements zuständig. Als erster Paremeter wird an die Methode eine ID übergeben, gefolgt von einem Array, dem einige Argumente übergeben werden können. Wir sind mit den meisten Standard-Werten so zufrieden und legen lediglich als Standard-Wert für das verknüpfte Formularelement 3 fest und als Callback, der den eingetragenen Wert überprüft, die Funktion absint(), die bereits von WordPress bereitgestellt wird.

Nützlich: Vorgefertigte Callback-Funktionen für andere Fälle, wie Checkboxen oder ähnliches, gibt es im entsprechenden GitHub-Repo des Theme-Review-Teams. Daneben gibt es dort auch einige andere nützliche Code-Beispiele, die den Customizer betreffen.

Um die Einstellung verändern zu können, brauchen wir ein Formularelement, das wir mit add_control() einfügen. Als ersten Parameter übergeben wir den Bezeichner der dazugehörenden Setting-Methode, damit WordPress die beiden Methoden automatisch in Zusammenhang bringt, und als zweiten ein Argument-Array. Mit type geben wir den Typ des Formularelements an, über section den Bereich, in dem das Element angezeigt werden soll – gallery ist ein Bereich, den wir gleich noch erstellen müssen. label nimmt die Beschreibung des Elements entgegen, die dem Nutzer angezeigt wird. Wenn ihr für den Bezeichner aus irgendeinem Grund etwas anderes als die ID aus der add_setting()-Methode angeben wollt, könnt ihr deren ID als Wert für den Schlüssel settings setzen.

Nun erstellen wir kurz alle Sections, die das Theme benötigt – unter anderem gallery. Diesen Teil habe ich ganz ans Ende der Funktion geschrieben:

$wp_customize->add_section( 'alternative_front_page', array(
    'title'      => _x( 'Alternative front page', 'Title of the alternative front page section in the Customizer', 'bornholm' ),
    'priority'   => 140,
) );
 
$wp_customize->add_section( 'content', array(
    'title'      => _x( 'Content', 'Title of the content section in the Customizer', 'bornholm' ),
    'priority'   => 160,
) );
 
$wp_customize->add_section( 'gallery', array(
    'title'      => _x( 'Gallery single view', 'Title of the Gallery single view section in the Customizer', 'bornholm' ),
    'priority'   => 130,
) );
 
$wp_customize->add_section( 'portfolio_page', array(
    'title'      => _x( 'Portfolio Page', 'Title of the portfolio page section in the Customizer', 'bornholm' ),
    'priority'   => 150,
) );
Code-Sprache: PHP (php)

Der erste Parameter von add_section() ist der Bezeichner, der bei add_control() für section verwendet werden muss. Als Titel wird der Text angegeben, der dem Nutzer angezeigt wird und als Priorität geben wir optional Werte für die Reihenfolge an.

Als nächstes soll die Option integriert werden, dass der Nutzer die Titel der Galerien in der Sidebar mit Galerien aus derselben Kategorie verbergen kann. Dafür nutzen wir eine Checkbox, was folgendermaßen aussieht:

$wp_customize->add_setting( 'hide_gallery_titles_for_galleries_from_same_category', array(
    'sanitize_callback' => 'bornholm_sanitize_checkbox'
) );
$wp_customize->add_control( 'hide_gallery_titles_for_galleries_from_same_category', array(
    'type'     => 'checkbox',
    'priority' => 12,
    'section'  => 'gallery',
    'label'    => __( 'Check if the titles of the galleries should be hidden for the galleries from the same category.', 'bornholm' ),
) );
Code-Sprache: PHP (php)

add_setting() hält nichts Neues bereit, außer, dass als Callback die Funktion bornholm_sanitize_checkbox() verwendet wird. An add_control() wird checkbox als type übergeben, damit die richtige Art Formularelement gerendert wird, mit dem optionalen Parameter priority können wir angeben, in welcher Reihenfolge die Elemente in ihrer Section angezeigt werden sollen – 10 ist hier der Standard-Wert, alles was größer ist wird weiter unten angezeigt, alles kleiner 10 darüber.

Die Funktion zur Bereinigung des eingetragenen Wertes kommt außerhalb der bornholm_customize_register()-Funktion in die customizer.php und sieht so aus:

function bornholm_sanitize_checkbox( $checked ) {
    return ( ( isset( $checked ) && true == $checked ) ? true : false );
}
Code-Sprache: PHP (php)

Es wird geprüft, ob der übergebene boolesche Wert gesetzt ist und ob er true entspricht. Wenn das der Fall ist, gibt die Funktion true zurück, andernfalls false.

Mit der nächsten Einstellung wollen wir ermöglichen, dass die Titel der Galerien im Widget mit den neuesten Galerien der Website verborgen werden. Auch diese Einstellung setzen wir mit einer Checkbox um, weshalb sie der letzten Einstellung gleicht:

$wp_customize->add_setting( 'hide_gallery_titles_on_recent_galleries_widget', array(
    'sanitize_callback' => 'bornholm_sanitize_checkbox'
) );
$wp_customize->add_control( 'hide_gallery_titles_on_recent_galleries_widget', array(
    'type'     => 'checkbox',
    'priority' => 12,
    'section'  => 'content',
    'label'    => __( 'Check if the titles of the galleries should be hidden on the recent galleries widget.', 'bornholm' ),
) );
Code-Sprache: PHP (php)

Neu ist hier im Prinzip nur, dass das Formularelement nicht in der gallery-Section angezeigt wird, sondern in content.

Die nächste Einstellung wird das Verbergen von Galerie-Titeln im Widget der Featured-Galerien ermöglichen:

$wp_customize->add_setting( 'hide_gallery_titles_on_featured_galleries_widget', array(
    'sanitize_callback' => 'bornholm_sanitize_checkbox'
) );
$wp_customize->add_control( 'hide_gallery_titles_on_featured_galleries_widget', array(
    'type'     => 'checkbox',
    'priority' => 14,
    'section'  => 'content',
    'label'    => __( 'Check if the titles of the galleries should be hidden on the featured galleries widget.', 'bornholm' ),
) );
Code-Sprache: PHP (php)

Auch hier gibt es nicht wirklich was Neues zu sehen.

Damit der Nutzer die Anzahl kleiner Bilder festlegen kann, die in der Blog-Übersicht bei einer Galerie unter dem großen Bild angezeigt werden, brauchen wir als nächstes wieder ein Zahlenfeld:

$wp_customize->add_setting( 'number_of_small_images_from_gallery_in_blog_view', array(
    'default'           => 2,
    'sanitize_callback' => 'absint'
) );
$wp_customize->add_control( 'number_of_small_images_from_gallery_in_blog_view', array(
    'type'     => 'number',
    'priority' => 10,
    'section'  => 'content',
    'label'    => __( 'Number of small images from the gallery to show in the blog view below the big image (0 if no small images should be displayed)', 'bornholm' ),
) );
Code-Sprache: PHP (php)

Der Standard-Wert wird auf 2 festgelegt und als Callback wieder direkt absint() verwendet. Auch der add_control()-Teil ist bekannt.

Das nächste Element wird es dem Nutzer ermöglichen, die Galerie-Kategorien in dem Seiten-Template für die alternative Startseite hierarchisch darzustellen – dafür reicht wieder eine Checkbox:

$wp_customize->add_setting( 'hierarchy_of_gallery_on_alternative_front_page', array(
    'sanitize_callback' => 'bornholm_sanitize_checkbox'
) );
$wp_customize->add_control( 'hierarchy_of_gallery_on_alternative_front_page', array(
    'type'     => 'checkbox',
    'priority' => 10,
    'section'  => 'alternative_front_page',
    'label'    => __( 'Check if the galleries from child categories should be displayed below the galleries of the parent category.', 'bornholm' ),
) );
Code-Sprache: PHP (php)

Auch hier gibt es keine Überraschungen – als section wird lediglich der Bereich alternative_front_page verwendet.

Damit der Nutzer die Galerie-Titel auf der alternativen Startseite verstecken kann, ist das nächste Element wieder eine Checkbox:

$wp_customize->add_setting( 'hide_gallery_titles_on_alternative_front_page', array(
    'sanitize_callback' => 'bornholm_sanitize_checkbox'
) );
$wp_customize->add_control( 'hide_gallery_titles_on_alternative_front_page', array(
    'type'     => 'checkbox',
    'priority' => 12,
    'section'  => 'alternative_front_page',
    'label'    => __( 'Check if the titles of the galleries should be hidden.', 'bornholm' ),
) );
Code-Sprache: PHP (php)

Auch diese Checkbox kommt in den Bereich alternative_front_page.

Für die Einstellungsmöglichkeit der Anzahl an Galerien, die auf der alternativen Starseite vor dem Link auf die Kategorie-Übersicht angezeigt werden, hilft uns wieder ein schlichtes Zahlenfeld:

$wp_customize->add_setting( 'number_of_galleries_on_alternative_front_page', array(
    'default'           => 3,
    'sanitize_callback' => 'absint'
) );
$wp_customize->add_control( 'number_of_galleries_on_alternative_front_page', array(
    'type'     => 'number',
    'priority' => 14,
    'section'  => 'alternative_front_page',
    'label'    => __( 'Number of galleries from every category to show', 'bornholm' ),
) );
Code-Sprache: PHP (php)

Als Nächstes wenden wir uns dem Portfolio-Template zu. Auch hier soll der Nutzer die Galerie-Titel verbergen können, weshalb wieder mal eine Checkbox zum Einsatz kommt – bei den Sections sind wir nun bei portfolio_page angekommen:

$wp_customize->add_setting( 'hide_gallery_titles_on_portfolio_page', array(
    'default'           => 0,
    'sanitize_callback' => 'bornholm_sanitize_checkbox'
) );
$wp_customize->add_control( 'hide_gallery_titles_on_portfolio_page', array(
    'type'     => 'checkbox',
    'priority' => 12,
    'section'  => 'portfolio_page',
    'label'    => __( 'Check if the titles of the galleries should be hidden.', 'bornholm' ),
) );
Code-Sprache: PHP (php)

Etwas interessanter wird es bei der nächsten Einstellung: Der Nutzer soll entscheiden können, ob die Galerien auf der Portfolio-Seite ungruppiert angezeigt werden oder nach Kategorien gruppiert inklusive der dritten Möglichkeit, auch noch die Hierarchie mit einzubeziehen. Hierfür nutzen wir drei Radio-Buttons, die folgendermaßen umgesetzt werden:

$wp_customize->add_setting( 'galleries_on_portfolio_page', array(
    'default'           => 'standard',
    'sanitize_callback' => 'bornholm_sanitize_radio'
) );
$wp_customize->add_control( 'galleries_on_portfolio_page', array(
    'type'     => 'radio',
    'priority' => 10,
    'section'  => 'portfolio_page',
    'label'    => __( 'Change the appearance of the galleries on the portfolio page', 'bornholm' ),
    'choices'  => array(
        'standard' => 'Standard',
        'portfolio_page_grouped_by_categories' => __( 'Display the galleries grouped by categories.', 'bornholm' ),
        'portfolio_page_grouped_by_categories_with_hierarchy' => __( 'Display the galleries grouped by categories with hierarchy (child categories below parent categories).', 'bornholm' ),
    ),
) );
Code-Sprache: PHP (php)

In add_setting() geben wir als Standard-Wert der Radio-Buttons den Button standard an und als Sanitize-Callback die Funktion bornholm_sanitize_radio(), die wir gleich besprechen. In der add_control()-Methode wird als type der Wert radio angegeben – die verschiedenen Optionen werden als Array an den choices-Schlüssel übergeben. Die Schlüssel dieses Unter-Arrays bilden immer das value-Attribut des Button-Elements, auf das später im Theme geprüft werden kann, der dazugehörende Wert ist die Beschriftung der jeweiligen Option.

Die Funktion zur Prüfung sieht wie folgt aus:

function bornholm_sanitize_radio( $input, $setting ) {
    $input   = sanitize_key( $input );
    $choices = $setting->manager->get_control( $setting->id )->choices;
 
    return ( array_key_exists( $input, $choices ) ? $input : $setting->default );
}
Code-Sprache: PHP (php)

Mit $input wird die ID des Radio-Buttons übergeben, die der Nutzer ausgewählt hat, mit $setting das WP_Customize_Setting-Objekt der zugehörenden Einstellung. In der Funktion wird die ID aus $input zuerst an sanitize_key() übergeben, um nicht erlaubte Zeichen zu entfernen. Um die möglichen Werte zu ermitteln, die der Nutzer auswählen konnte, wird mit $setting->manager auf das WP_Customize_Manager-Objekt zugegriffen und von dem mit get_control( $setting->id )->choices die Optionen ermittelt, die für die Control mit der ID der Einstellung hinterlegt sind.

Abschließend wird der Wert der gewählten Option zurückgegeben, falls dieser in dem Array der Möglichkeiten exitiert, andernfalls der Standard-Wert, auf den mit $setting->default zugegriffen werden kann.

Das wäre es dann bereits zum großen Teil mit der customizer.php. Im nächsten Teil wird es dann darum gehen, wie die konkreten Einstellungen in den übrigen Theme-Dateien genutzt werden.

Zum Nachbasteln

Für alle, die den Code des Themes haben möchten, gibt es den im GitHub-Repo. Den aktuellen Stand nach diesem Teil findet ihr bei Tag „v0.16“.

Die weiteren Teile meiner WordPress-Reihe:

Dieser Beitrag ist eine Übernahme meines Beitrags für t3n.de.

Der Customizer

Zum Nachbasteln

Schreibe einen Kommentar Antworten abbrechen