Für Theme-Entwickler¶

Diese Seite richtet sich an Entwickler, die ein Theme oder Plugin an wpShopGermany anpassen. Die Liste der Variablen ist fest: Neue Variablen kommen nur dazu, keine fällt weg oder ändert ihre Bedeutung. Für die Gestaltung reichen in der Regel die Variablen und eigenes CSS; eigene Kopien von Templates sind der letzte Weg, weil Sie sie nach Updates nachziehen müssen. Sie beschreibt die Stildateien, Variablen und Einhängepunkte seit Version 4.6.1.

Grundlage ist die Darstellung „An das Theme angepasst“, siehe Darstellung der Shopseiten. In der Darstellung „Klassisch“ gelten frontend.css und das Markup der klassischen Templates.

Stildateien¶

Darstellung	Stildatei	Handle
An das Theme angepasst	`views/css/wpsg-theme.css`	`wpsg-theme`
Klassisch	`views/css/frontend.css`; bei aktiven Produktübersichten zusätzlich `productindex.css`	`wpsg-frontendstyle`, `wpsg-mod-productindex-style`

wpsg-theme.css kommt ohne !important aus. Farben, Schrift, Rahmen und Abstände haben die Spezifität einer Klasse (.klasse :where(…)), Rückfälle für Eingabefelder und Knöpfe die Spezifität 0; Theme-Regeln mit gleicher oder höherer Spezifität gewinnen, bei Gleichstand entscheidet die Reihenfolge. Regeln zum Aufbau (Breiten eigener Felder, Ein- und Ausblenden, Einblendungen) haben volle Spezifität, damit Resets von Themes sie nicht aufheben.
wpsg-theme wird bei wp_enqueue_scripts mit Priorität 20 eingereiht. In Block-Themes steht es vor global-styles, damit das Zusätzliche CSS des Betreibers und die Stile aus theme.json gewinnen.
Ein Theme, das wpShopGermany gestaltet, gibt wpsg-theme als Abhängigkeit seiner eigenen Stildatei an oder hängt seine Regeln mit wp_add_inline_style( 'wpsg-theme', … ) an (bei wp_enqueue_scripts mit Priorität über 20). So stehen sie hinter den Vorgaben des Shops und gewinnen bei gleicher Spezifität.
Regeln in styles.css der theme.json eignen sich nicht: Speichert der Betreiber im Website-Editor Zusätzliches CSS, ersetzt es das CSS des Themes dort ganz.
Der Filter wpsg_enqueue_styles erhält die Liste der Stildateien; ein leeres Array schaltet sie ab. Die Einstellung „Shop CSS styles nicht einbinden“ schaltet beide Darstellungen ab; dann fehlt auch das Handle, an das ein Theme anhängen könnte.
Eine eigene wpsg-theme.css unter wpsg_views/css/ im Theme oder unter wp-content/uploads/wpsg/user_views/css/ ersetzt die mitgelieferte ganz. Updates der Datei greifen dann nicht mehr; der Website-Zustand weist darauf hin.
Im Editor ist die Stildatei der gewählten Darstellung als wpsg-blocks-editor-style registriert.

Erkennen der Darstellung¶

body-Klasse wpsg-style-theme bzw. wpsg-style-classic auf allen Seiten des Frontends
in PHP \wpsg\ThemeStyle::isThemeMode(), true bei „An das Theme angepasst“

Variablen¶

Alle Variablen stehen auf :where(:root). Jede eigene Angabe auf :root oder body gewinnt.

Variable	Vorgabe	Wofür
`--wpsg-color-background`	`--wp--preset--color--base`, Rückfall Astra, Kadence, `#ffffff`	Hintergrund von Einblendungen und Auswahllisten
`--wpsg-color-foreground`	`--wp--preset--color--contrast`, Rückfall Astra, Kadence, `#111111`	Schrift auf Flächen, die der Shop selbst färbt
`--wpsg-color-accent`	`--wp--preset--color--primary`, sonst `contrast`, sonst `currentColor`	Fortschritt der Kasse, Balken
`--wpsg-color-line`	`rgba(127, 127, 127, 0.35)`	Rahmen von Kästen
`--wpsg-color-field-line`	Mischung aus Schrift- und Hintergrundfarbe	Rahmen der Eingabefelder, mindestens 3:1
`--wpsg-color-line-soft`	`rgba(127, 127, 127, 0.2)`	Trennlinien
`--wpsg-color-surface`	`rgba(127, 127, 127, 0.08)`	Flächen: gewählte Versandart, Meldungen
`--wpsg-color-overlay`	`rgba(0, 0, 0, 0.6)`	Abdunkeln hinter Einblendungen
`--wpsg-color-error`	`#e12b2b`	Fehler: Rand, Pflichtfeld-Stern, Fehlertext
`--wpsg-color-success`	`#228732`	Erfolg
`--wpsg-color-notice`	`#a66709`	Hinweis
`--wpsg-muted-opacity`	`0.7`	gedämpfter Text
`--wpsg-radius`	`3px`	Ecken von Feldern, Knöpfen, Einblendungen
`--wpsg-label-background`	`--wpsg-color-accent`	Fläche der Etiketten „Neu“ und „Angebot“
`--wpsg-label-color`	`--wpsg-color-background`	Schrift der Etiketten
`--wpsg-gap`	`1rem`	Grundabstand
`--wpsg-font-size-small`	`--wp--preset--font-size--small`, sonst `0.875em`	kleine Texte
`--wpsg-field-border`	`1px solid var(--wpsg-color-field-line)`	Rahmen der Eingabefelder
`--wpsg-field-padding`	`0.6em 0.75em`	Innenabstand der Eingabefelder
`--wpsg-field-background`	`transparent`	Hintergrund der Eingabefelder
`--wpsg-button-background`	`transparent`	Hintergrund des Knopfs, wenn das Theme keine Knöpfe gestaltet
`--wpsg-button-color`	`inherit`	Schrift dieses Knopfs
`--wpsg-button-padding`	`0.6em 1.2em`	Innenabstand dieses Knopfs
`--wpsg-columns`	`4`	Spalten der Produktkacheln, setzt das Template
`--wpsg-color-rating`	`#b07800`	volle Sterne (Modul Produktbewertungen)
`--wpsg-color-rating-empty`	Schriftfarbe zu 60 %	Umriss der leeren Sterne

Die beiden Variablen der Sterne setzt der Shop nicht auf :root; ihre Vorgaben stehen in der Stildatei des Moduls Produktbewertungen (Handle wpsg-reviews). Eigene Werte auf :root gelten in beiden Darstellungen.

Die Statusfarben haben auf Weiß und auf Schwarz mindestens 4,5:1 Kontrast. Sie färben vor allem Ränder und Markierungen; Meldungstexte bleiben in der Schriftfarbe des Themes.

Knöpfe und Eingabefelder¶

Knöpfe des Shops bekommen die Klasse wp-element-button, wenn das Theme Knöpfe gestaltet: in jedem Block-Theme und in klassischen Themes mit styles.elements.button in der theme.json. Sonst zeichnet der Shop einen schlichten Knopf mit Rahmen in der Textfarbe.
In eigenen Templates setzen Sie die Klasse mit <?php echo wpsg_button_class(); ?> direkt hinter Ihre Klassen; die Funktion gibt das führende Leerzeichen mit aus.
Eingabefelder haben einen schlichten Rückfall (Rahmen, Schrift inherit) mit der Spezifität 0. Gestaltet das Theme Felder, gewinnt es.

Markup¶

Produktseite: views/produktseite/produkt.phtml, Wurzel .wpsg-product; Etiketten .wpsg-label, .wpsg-label--new, .wpsg-label--sale; die Ausgabe nach dem Knopf (z. B. „Vertrag widerrufen“) steht in .wpsg-product__after-buy.
Kasse: Schritte als ol mit aria-current="step" am aktuellen Schritt; „Ihre Bestellung“ in views/warenkorb/checkout_summary.phtml.
Blöcke: Rahmen mit den Klassen wpsg-block wpsg-block-<name>, z. B. wpsg-block-product-list.
Mini-Warenkorb: .wpsg-mini-cart__content mit .wpsg-mini-cart__count („3 Artikel“) und darin die Zahl allein in .wpsg-mini-cart__number, daneben .wpsg-mini-cart__sum. Eine Kurzform wie „(3)“ bilden Sie per CSS, ohne Text zu zerlegen. Der Mini-Warenkorb lädt neu, wenn ein Produkt über ein Produkttemplate eingelegt wird oder am document das Ereignis wpsg_basket_changed eintrifft. Der SmartCheckout löst es nach jeder Änderung aus; ein eigenes Skript kann es ebenso auslösen.
Produktkacheln: Die Abfrageschleife trägt die Klasse wpsg-product-tiles.

Templates überschreiben¶

Kopien von Templates legen Sie mit gleichem Pfad unter wpsg_views/ im Child-Theme oder Theme oder unter wp-content/uploads/wpsg/user_views/ ab, siehe Templates. Das gilt auch für die Templates der Produktseite und der Blöcke, etwa produktseite/produkt.phtml oder blocks/product-list.phtml.

Jedes Template trägt in den ersten Zeilen eine Version:

/**
 * Template für den Warenkorb
 * @version 4.6.1
 */

Die Version steigt nur, wenn Kopien nachgezogen werden sollten: neue Klasse, neues Feld, Sicherheitskorrektur. Übernehmen Sie in Ihrer Kopie die Version des Originals, sobald Sie die Änderungen eingearbeitet haben. Kopien ohne Version gelten als „Version unbekannt“. Der Kasten Eigene Vorlagen unter Darstellung und der Website-Zustand zeigen jede Kopie mit Fundort und beiden Versionen.

Seitenvorlagen im Block-Theme¶

In Block-Themes registriert der Shop in der Darstellung „An das Theme angepasst“ Seitenvorlagen über register_block_template() im Namensraum wpshopgermany:

Vorlage	Slug
Produktartikel	`single-<URL-Präfix der Produkte>`, z. B. `single-produkt`
Produktkategorie	`taxonomy-<URL-Präfix der Kategorien>`, z. B. `taxonomy-produkte`
Produktdetailseite	`page-<Name der Seite Produktdetails>`

Eine gleichnamige Datei unter templates/ im Theme geht vor, ebenso eine im Website-Editor gespeicherte Fassung. Die Produktartikel-Vorlage enthält keinen Beitragstitel: Brotkrumen und Hauptüberschrift gibt das Produkt selbst aus. Zeigt Ihre Vorlage einen core/post-title, lässt das Produkt seine Überschrift weg.

Für Warenkorb und Kasse wählt der Shop beim Anlegen der Warenkorbseite die Vorlage page-checkout des Themes, wenn es eine hat, sonst page-no-title.

Einhängepunkte in den Templates¶

Vor den Modulen feuert an festen Stellen der Templates die Aktion wpsg_template_<Name>, mit den Argumenten einzeln. Eine Ausgabe per echo erscheint an dieser Stelle. Die Namen hängen nicht an den Modulen, die dort ausgeben. Daneben feuern die Aktionen wpsg_<Name> mit einem Array als Argument.

add_action('wpsg_template_product_top_afterheadline', function(int $product_id, int $template_index) {
    echo '<p class="mein-hinweis">Versand innerhalb von 24 Stunden</p>';
}, 10, 2);

Bereich	Aktionen `wpsg_template_…`
Warenkorb	`basket_top`, `basket_row_before`, `basket_row`, `basket_row_end`, `basket_row_afterproducts`, `basket_inner_prebutton`, `basket_after`
Kasse	`checkout_customer_inner`, `checkout_inner_prebutton`, `checkout_payment`
Bestellübersicht	`overview_top`, `overview_row_before`, `overview_row`, `overview_row_end`, `overview_inner_prebutton`, `order_handle`
Abschluss	`order_done`
Produkttemplates	`product_top`, `product_top_afterheadline`, `product_bottom`, `product_bottom_end`
Kundenprofil	`customer_profile_inner`
Mails	`mail_row`, `mail_aftercalculation`, `mail_shipping`, `mail_payment`, `mail_payment_after`, `mail_status`, `mail_order_end`

Vor jedem Template läuft außerdem der Filter wpsg_render_<Pfad> mit den Daten des Templates, z. B. wpsg_render_warenkorb/basket.phtml. Er gilt auch, wenn eine Kopie aus dem Theme geladen wird.

Filter¶

Filter	Argumente	Wirkung
`wpsg_button_class`	`string $classes`	weitere Klassen an allen Knöpfen, die `wpsg_button_class()` nutzen
`wpsg_button_text`	`string $text, string $key`	Beschriftung; `add_to_basket` („In den Warenkorb“) und `to_product` („Zum Produkt“)
`wpsg_price_html`	`string $html, float $price, string $context`	Preis mit Währung; Kontext `product`, `product_old`, `list`, `list_old`, `mini_cart`. Erhält und liefert escaptes HTML.
`wpsg_buy_in_list`	`bool $buy, int $product_id`	ob eine Liste den Knopf „In den Warenkorb“ zeigt
`wpsg_enqueue_styles`	`array $styles`	Stildateien des Shops
`wpsg_product_jsonld`	`array $data, wpsg_product $product`	strukturierte Produktdaten, siehe unten

Die Beschriftung des Bestellknopfs („zahlungspflichtig bestellen“) ist gesetzlich vorgegeben und lässt sich nicht über einen Filter ändern.

Für eigene Templates gibt es die Hilfsfunktionen wpsg_button_class(), wpsg_button_text(), wpsg_price_html() und wpsg_buy_in_list($product_id). Mit wpsg_buy_in_list() fragt ein Listen-Template, ob ein Produkt aus der Liste gekauft werden darf, etwa wegen Kauf nur über die Detailseite.

Strukturierte Produktdaten¶

Die strukturierten Produktdaten lassen sich vor der Ausgabe ändern. Ein leeres Array schaltet sie für dieses Produkt ab.

add_filter('wpsg_product_jsonld', function(array $data, wpsg_product $product) {
    $data['category'] = 'Kaffee';
    return $data;
}, 10, 2);

Optionen für Theme-Links¶

Die Seiten-IDs der wichtigsten Shopseiten stehen in den Optionen wpsg_page_basket, wpsg_page_mod_kundenverwaltung_profil, wpsg_page_versand, wpsg_page_widerrufsbelehrung, wpsg_page_impressum, wpsg_page_datenschutz und wpsg_page_agb. Ein Theme kann damit Links im Fußbereich setzen.