07/09/2013

Theme Customization Part #1

Du möchtest dein Theme „aufpimpen“, weißt aber noch nicht genau wie? Dann bist du hier genau richtig!

Der folgende Beitrag soll dir zeigen, wie du deinem Theme neue Funktionen (bzw. Optionen) „beibringen“ kannst.

Bei diesen Schritten spielt die Theme Customization API eine wesentliche Rolle.

Und los geht’s! – Das Grundgerüst

Als erstes brauchen wir ein umschließendes „Gerüst“, in welchem alle Anweisungen eingetragen werden, die zur Ausgabe der neuen Optionen führen.

Und damit die Funktionen auch ausgeführt werden können, melden wir diese am Schluss noch an.

All diese Anweisungen werden in die functions.php eingetragen.

class ckblog_customize {
public static function register ($wp_customize) {
[...]
}
}
add_action('customize_register', array('ckblog_customize', 'register'));

ODER

function ckblog_customize_register ($wp_customize) {
[...]
}
add_action('customize_register', 'ckblog_customize_register');

Sections, Settings & Controls

Das Zusammenspiel dieser 3 Bausteine ermöglicht das Hinzufügen neuer Optionen. In den folgenden Zeilen sollen Section, Setting und Control etwas genauer unter die Lupe genommen werden.

Section – Baustein #1

Hierbei handelt es sich um eine Gruppe bzw. einen Bereich, die/der verschiedene Optionen beinhalten kann.

WordPress stellt standardmäßig folgende Bereiche zur Verfügung:

• title_tagline … Seitentitel und Untertitel
• colors … Farben
• header_image … Kopfbild
• background_image … Hintergrundbild
• nav … Navigation
• static_front_page … Statische Startseite

// Anwendung
$wp_customize->add_section($id, $args);
// INFO
$id ... eindeutiger unique Name der Section [required]
$args ... Array [required]

Array $args:
title » Titel/Name
priority » Sortierung
description » Beschreibung

// Beispiel
$wp_customize->add_section('ckblog_section_name',
array(
'title'      => __('ckBLOG'),
'priority'   => 30
)
);

Setting – Baustein #2

Hier werden die Einstellungsmöglichkeiten festgelegt.

// Anwendung
$wp_customize->add_setting($id, $args);
// INFO
$id ... eindeutiger unique Name der Einstellung [required]
$args ... Array [required]

Array $args
default » Standardwert der Einstellung
type » Art/Typ der Einstellung 'option' oder 'theme_mod'¹ [optional]
capability » Berechtigung (Wer darf diese Einstellung anpassen/ändern?) [optional]
transport » 'refresh'1 oder 'postMessage' [optional]

// Beispiel #1
$wp_customize->add_setting('ckblog_setting_one',
array(
'default'   => '#fff',
'type'      => 'option',
'transport' => 'refresh'
)
);

// Beispiel #2
$wp_customize->add_setting('ckblog_setting_two',
array(
'default'   => 'Beispieltext',
'type'      => 'option',
'transport' => 'refresh'
)
);

Control – Baustein #3

Hier werden alle Bestandteile, die zur Generierung der Theme-Optionen notwendig sind, zusammengeführt.
In gewisser Weise wird hier die Verknüpfung zwischen Section und Setting geschaffen.

// Anwendung
$wp_customize->add_control($id, $args);

// Beispiel #1
$wp_customize->add_control('ckblog_control_text_color',
array(
'label'      => __('Textfarbe'),
'section'    => 'ckblog_section_name',
'settings'   => 'ckblog_setting_one',
'type'       => 'radio',
'choices'    => array(
'#fff' => 'white',
'#666' => 'grey',
'#000' => 'black'
)
)
);

// Beispiel #2
$wp_customize->add_control(
new WP_Customize_Control(
$wp_customize, 'ckblog_text_example',
array(
'label'      => __('Beispieltext'),
'section'    => 'ckblog_section_name',
'settings'   => 'ckblog_setting_two'
)
)
);

Das zweite Beispiel bezieht sich auf eine vordefinierte Klasse zur Ausgabe der Option.
Folgende Klassen können genutzt werden:

• WP_Customize_Control()
• WP_Customize_Color_Control()
• WP_Customize_Upload_Control()
• WP_Customize_Image_Control()
• WP_Customize_Background_Image_Control()
• WP_Customize_Header_Image_Control()

Und so sieht’s aus …

Die folgenden Abbildungen zeigen die Ansicht unter Design => Anpassungen vor (Abb. links) und nach (Abb. rechts) der oben aufgeführten Anpassung.

Fertig?

Noch nicht ganz. Die Optionen wurden hinzugefügt. Und nun?
Damit auch etwas passiert, müssen die Werte der Optionen an entsprechender Stelle ausgegeben bzw. eingebunden werden.

// allgemein
<?php echo get_theme_mod('setting_id'); ?>
<?php echo get_option('setting_id'); ?>

Bezogen auf Beispiel #1 und #2 …

<?php echo get_option('ckblog_setting_one'); ?>
<?php echo get_option('ckblog_setting_two'); ?>

Ein kleiner Exkurs – Joomla macht es ähnlich ;)

Für diejenigen, die schon einmal ein Joomla-Template mit individuellen Parametern erstellt bzw. entwickelt haben, könnte folgender Vergleich die Beziehungen zwischen Sections, Settings & Controls verdeutlichen.

So könnte es in der templateDetails.xml eines Joomla-Templates aussehen …

<config>
<fields name="params">
<fieldset name="fieldset_name">
// Beispiel #1
<field
name="field_one"
type="radio"
default="#fff"
label="Textfarbe"
description=""
>
<option value="#fff">white</option>
<option value="#666">grey</option>
<option value="#000">black</option>
</field>
// Beispiel #2
<field
name="field_two"
type="text"
default="Beispieltext"
label="Beispieltext"
description=""
/>
</fieldset>
</fields>
</config>

Der QuellCode sollte nun gezeigt haben, dass section und fieldset in gewisser Weise die gleiche Aufgabe haben. Sie bilden den „Rahmen“ um die Optionen bzw. Parameter. Die Aufgaben von setting und control werden im weitesten Sinne von field übernommen.

¹ Standardwert