Kowal Hyva Colors — Shopfarben unter Kontrolle

Admin-Panel und Berechtigungen

Sie öffnen das Modul über kowal.store → Modules → Hyva Colors. Die Konfiguration erfolgt in den drei Modulansichten und nicht in einem separaten Bereich unter Stores → Configuration.

Der Administrator vergibt Berechtigungen unter System → Permissions → User Roles. Weisen Sie den Rollen die entsprechenden übergeordneten Ressourcen des Kowal-Menüs und die Ressourcen von Hyva Colors zu:

Ein Import mit neuen Katalogdefinitionen erfordert zusätzlich die Berechtigung zum Hinzufügen von Elementen. Nach einer Rollenänderung muss sich der Benutzer möglicherweise erneut anmelden.

Shop-Geltungsbereich

Bei der Veröffentlichung wählen Sie eine aktive Shop-Ansicht (Store View) aus. Das Modul prüft das zugewiesene Theme: Das aktuelle Profil unterstützt exakt Hyva/default mit Default Theme 1.5.2–1.5.x. Weisen Sie kein anderes Theme zu, nur um die Validierung zu umgehen — Child-Themes benötigen separat vorbereitete Mappings.

Ein Set ist ein wiederverwendbarer Entwurf. Sie können es separat für mehrere Ansichten veröffentlichen. In dieser Version gibt es keine vererbte Konfiguration auf der Ebene default/website/store.

System-Sets und eigene Sets

Die fertigen Definitionen umfassen sieben Paletten und ein leeres natives Set. Ihre gespeicherten Kopien sind unter ›Meine Sets‹ verfügbar. Am einfachsten erstellen Sie eigene Sets auf dieser Grundlage, sodass die Originale als Referenz erhalten bleiben.

Farbeditor

Der Editor unterteilt den Katalog in die Bereiche Global, Header, Buttons, Product cards sowie Catalog and product page. Die Namen können auf Englisch bleiben. Der ursprüngliche Katalog enthält 34 Elemente und 99 Mappings. Ein einzelnes Element kann separate Einträge für Hintergrund, Text, Rahmen und Interaktionszustände haben.

Verfügbare Methoden zum Festlegen eines Werts:

native fügt nicht das CSS inherit ein. Der Wert transparent ist eine explizite transparente Farbe und keine Rückkehr zum Theme. Sie können auch currentColor verwenden. Beliebige CSS-Funktionen wie rgb() oder var() werden in den Farbfeldern nicht akzeptiert.

Speichern Sie den Entwurf, bevor Sie den Bereich oder die Editor-Seite wechseln. Durch das Speichern werden die Änderungen nicht veröffentlicht.

Gemeinsame Farben: Token

Unter ›Palette — erweiterte Einstellungen (JSON)‹ werden benannte Farben gespeichert. Beispiel für ein Fragment:

{ 'brand': {'mode': 'color', 'value': '#1d4ed8'}, 'on-brand': {'mode': 'color', 'value': '#ffffff'}}

Wählen Sie in der Elementzeile ›Farbe aus der Palette‹ und geben Sie brand ein. Eine Änderung des Tokens aktualisiert bei der nächsten Veröffentlichung alle Werte, die darauf verweisen. Wenn Sie ein fertiges Set bearbeiten, behalten Sie die übrigen vorhandenen Token bei — das Ersetzen des gesamten JSON durch das oben gezeigte Fragment kann zu nicht aufgelösten Verweisen führen. Zyklen und fehlende Token werden abgelehnt.

Elemente und Bereiche hinzufügen

Dafür müssen keine Moduldateien geändert werden. Der passende CSS-Selektor muss jedoch ermittelt werden. Das Modul bietet keinen visuellen Elementinspektor.

1. Öffnen Sie den Editor eines beliebigen Sets.
2. Klappen Sie ›Eigenes Element hinzufügen — erweiterter Modus‹ auf.
3. Geben Sie einen Namen ein, z. B. ›Aktionsbanner‹.
4. Wählen Sie einen vorhandenen Bereichsnamen aus oder geben Sie einen neuen Namen ein, z. B. ›Aktionen‹.
5. Geben Sie einen stabilen Selektor ein, z. B. #promo-banner, der im Shop vorhanden ist.
6. Wählen Sie Eigenschaften aus, z. B. background-color, color, border-color.
7. Wählen Sie Zustände aus, z. B. normal und hover, und fügen Sie anschließend das Element hinzu.
8. Öffnen Sie den entsprechenden Bereich, weisen Sie Farben zu, speichern Sie das Set und veröffentlichen Sie es.

Die Definition wird dem gemeinsamen Katalog hinzugefügt. Durch das Hinzufügen allein werden nicht in allen Sets Farben festgelegt. Der Selektor sollte möglichst präzise sein. Selektorlisten, :has() und beliebige CSS-Deklarationen werden in dieser Version nicht unterstützt. Durch das Hinzufügen eines Elements wird dessen HTML nicht im Shop erstellt. Eine Bearbeitung vorhandener Selektoren und die Archivierung von Elementen über das Admin-Panel sind noch nicht verfügbar.

Infrastrukturkonfiguration

Die Veröffentlichung ist von Cron, beschreibbaren Medien und Cache abhängig. Das CSS-Stylesheet wird vor der Aktivierung generiert und anschließend statisch bereitgestellt. Das Modul fügt dem regulären Storefront kein JavaScript für Farben hinzu. Dies ist keine Garantie für ein bestimmtes Performance-Ergebnis — Messungen müssen im Ziel-Shop durchgeführt werden.

Prüfen Sie bei Varnish den Zugriff auf die Purge-Server. Prüfen Sie bei einem CDN und mehreren Nodes die HTML-Propagation sowie die Verfügbarkeit der Stylesheets. Implementierungsdetails finden Sie in der Installationsanleitung.

Kowal Hyva Colors — Installation und Aktualisierung

Anleitung für Version 0.1.6. Führen Sie die Befehle im Magento-Stammverzeichnis als Deployment-Benutzer im Rahmen des standardmäßigen Deployment-Verfahrens Ihres Shops aus. Prüfen Sie die Installation zuerst in einer Testumgebung.

Anforderungen

Die vollständigen Abhängigkeiten sind incomposer.jsondefiniert. Die Anforderungen der Abhängigkeiten stellen keine Erklärung dar, dass alle Versionskombinationen getestet wurden. Child-Themes werden derzeit von der Veröffentlichungsvalidierung abgelehnt, selbst wenn sie von Hyvä erben.

1. Composer-Zugriff

Konfigurieren Sie das Composer-Repository, daskowal/module-hyva-colorssowiekowal/basebereitstellt, entsprechend den vom Anbieter erhaltenen Zugangsdaten. Außerdem benötigen Sie einen autorisierten Zugriff auf das Hyvä-Repository. Repository-Adresse und Autorisierungsverfahren hängen vom bereitgestellten Zugang ab. Diese Anleitung setzt keine öffentliche Verfügbarkeit des Pakets voraus.

Beispiel für die Konfiguration — ersetzen Sie die Adresse durch die tatsächliche Adresse des Composer-Repositorys:

composer config repositories.kowal composer 'https://ADRES-REPOZYTORIUM-COMPOSER'

Bewahren Sie Anmeldedaten außerhalb des Projekt-Repositorys auf, beispielsweise in einer privatenauth.jsonoder in der CI-Konfiguration. Kopieren Sie sie nicht in die Dokumentation.

2. Installation

Nach der Bereitstellung von Version 0.1.6 im Repository:

composer require kowal/module-hyva-colors:0.1.6 --with-all-dependencies
php bin/magento module:enable Kowal_Base Kowal_HyvaColors
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy pl_PL en_US
php bin/magento cache:clean config layout block_html full_page
php bin/magento module:status Kowal_HyvaColors
php bin/magento kowal:hyva-colors:diagnose

Die angegebenen Locales sind Beispiele — stellen Sie die Sprachen bereit, die im Shop und im Admin-Panel verwendet werden. Integrieren Sie die DI-Generierung und die Bereitstellung der Assets in Ihr standardmäßiges Deployment-Verfahren, anstatt sie während des laufenden Betriebs im aktiven Produktionsverzeichnis auszuführen.

Bei der Installation werden der Katalog und die anfänglichen Sets erstellt.Es werden keine Farben veröffentlicht und die Darstellung des Shops wird nicht verändert.Mit dem Befehldiagnoseprüft den Paketkatalog und meldet den Funktionsumfang; er ist kein vollständiger Umgebungstest.

3. Cron und CSS-Dateien

Das Modul verwendet die Aufgabekowal_hyva_colors_publishin der Cron-Gruppedefault, die jede Minute ausgeführt wird. Auf dem Server muss der standardmäßige Magento-Cron aktiv sein. Ein Durchlauf verarbeitet maximal 10 Aufgaben; eine Veröffentlichung muss daher nicht sofort erfolgen.

Manuelle Verarbeitung der Warteschlange zu Diagnosezwecken:

php bin/magento kowal:hyva-colors:publication:process

Prüfen Sie den Status einer bestimmten Aufgabe im Änderungsverlauf. Eine erfolgreiche Ausführung des Befehls bedeutet nicht, dass jede Aufgabe erfolgreich abgeschlossen wurde.

Stylesheets werden unterpub/media/kowal/hyva-colors/<store-id>/<hash>.cssgespeichert. Stellen Sie sicher, dass Schreibzugriff sowie HTTP-Lesezugriff möglich sind. Bei mehreren Nodes müssen gemeinsam genutzte Medien vorhanden sein. Für diese unveränderlichen Dateien könnenContent-Type: text/css, Komprimierung undCache-Control: public, max-age=31536000, immutablekonfiguriert werden. Das Modul nimmt keine Konfiguration des Servers oder CDN vor.

4. Abnahme der Installation

1. Öffnen Siekowal.store → Modules → Hyva Colors. Wenn das Menü nicht sichtbar ist, prüfen Sie Kowal Base und die Rollenberechtigungen.
2. Prüfen Sie die drei Seiten: ›Sets und Veröffentlichung‹, ›Meine Sets‹ und ›Änderungsverlauf‹.
3. Veröffentlichen Sie in einer Test-Store-View eine Palette und warten Sie, bis die Aufgabe abgeschlossen ist.
4. Prüfen Sie Header, Konto, Mini-Warenkorb, Kategorie und Produkt auf Desktop- und Mobilgeräten, einschließlich hover/focus.
5. Bestätigen Sie die Verfügbarkeit des CSS, die Aktualisierung von FPC/Varnish sowie aller CDN-Nodes.
6. Veröffentlichen Sie das Zurücksetzen auf das native Theme und prüfen Sie anschließend die Wiederherstellung einer früheren Veröffentlichung.

Aktualisierung

Nach der Bereitstellung einer neuen Version:

composer update kowal/module-hyva-colors kowal/base --with-all-dependencies
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy pl_PL en_US
php bin/magento cache:clean config layout block_html full_page

Prüfen Sie die Versionseinschränkung in der zentralencomposer.jsondes Shops: Die exakte Version0.1.6verhindert, dass der Befehlupdateeine neuere Version auswählt. Ändern Sie die Einschränkung bewusst, beispielsweise mitcomposer require ...:NOWA-WERSJA --with-all-dependenciesverwenden.

Bei einer Aktualisierung wird die aktive Veröffentlichung nicht durch eine neue Palette ersetzt. Wählen Sie nach Änderungen an den Werkseinstellungen das fertige Set erneut aus und veröffentlichen Sie es. Gespeicherte eigene Entwürfe behalten ihre eigenen Werte.

Probleme bei der Installation

• Paket ist nicht verfügbar:Prüfen Sie die Verfügbarkeit der Version, die Repositorys und die Composer-Autorisierung.
• Menü fehlt:Prüfen Sie die Aktivierung vonKowal_Base, die Rollenrechte und den Konfigurations-Cache. Aktualisieren Sie anschließend das Admin-Panel.
• Katalogkonflikt:Führen Siephp bin/magento kowal:hyva-colors:catalog:sync --dry-runaus. Vergleichen Sie geänderte Definitionen vor der Synchronisierung und überschreiben Sie eigene Elemente nicht manuell.
• Interceptor-Fehler nach einer alten Version:Stellen Sie sicher, dass Composer das korrigierte Paket installiert hat, und erstellen Sie den generierten Code im standardmäßigen Deployment-Prozess neu.
• Farben ändern sich nicht:Prüfen Sie Verlauf, Cron, aktives Theme, CSS im Medienverzeichnis und Cache-Propagation.

Das Zurücksetzen der Farben erfolgt im Admin-Panel. Eine Deinstallation des Moduls oder das Löschen von Tabellen ist nicht erforderlich. Exportieren Sie vor dem Deaktivieren oder Entfernen des Moduls die benötigten Sets und erstellen Sie gemäß dem Wartungsverfahren Ihres Shops eine Datenbanksicherung.