Styleguide

Das vorliegende TemplateKit gliedert sich in folgende Module:

• ACCOUNT - Benuterbezogener Bereich der die Benutzerdaten und dessen letzte Bestellungen anzeigt
• ARTICLE - Alle Artikel/Produkt-bezogenen Informationen und Merkmale im Detail
• BASKET - Ermöglicht das Anzeigen und Editieren des aktuellen Warenkorbs
• CHECKOUT - Bestellungsablauf eines aktiven Warenkorbs
• COMPARE - Artikelvergleich
• CONTACT - Kontaktformular
• FAVORITE - Verwaltung der Benutzerfavoriten auf mehreren Merklisten
• GENERAL - Start-, Maintenance- und Error-Seite
• INTERNAL - Interne Funktionalität wie dieser Styleguide
• NEWSLETTER - Newsletter-Verwaltung
• STATIC - Statischer Inhalt wie AGB und Impressum
• STRUCT - Kategorie- und Artikel-Trefferlisten
• VERIFICATION - Anmelde- und Passwort-Funktionalität

Pro Modul werden mehrere Pages abgebildet. Das entsprechende Page-Layout wird unter folgendem Verzeichnis abgelegt: webportal\config\layout\page

Im Library.cnf wird das dazugehörige Styling und JavaScript hinterlegt.

Damit dieses im Projekt erweitert werden kann, werden die dazu nötigen POSTCSS- und TypeScript-Dateien in Themes-Ordner unterteilt: webportal\config\layout\themes

Die Themes werden nach tk und project unterteilt.

Um das TK-ESHOP in Zukunft Update-fähig zu machen, werden im tk-Ordner alle Web-Components abgelegt. Hier sind nur die nötigen TypeScript-Dateien zu finden, welche sich an der gleichen Struktur wie dieser Styleguide orientieren:

• basics
• controls
• components
• utilities

Ein Editieren dieser Dateien ist nicht erlaubt, da sie mit einem zukünftigen TK-Update überschrieben werden!

Im project-Ordner sind die Einstiegsdateien für die TS-Logik zu finden, welche die benötigte Logik aus dem tk-Ordner importieren. Zudem sind hier alle modifizierbaren CSS-Dateien und Assets abgelegt:

• assets
  • fonts
  • icons
  • img
• css
• ts

Aus diesen Dateien werden während des Build-Process die benötigten CSS- und JS-Files erstellt:

• generated
  • css
  • js

Die für die gFunktionen nötigen HTML-Vorlagen werden in Form von Razor-Templates weiterhin von WAS zur Verfügung gestellt.

Da sich die HTML-Strukturen und die Selektoren fürs Styling und JavaScript aber grundlegend verändert haben, werden in diesem TK alle nötigen Razor-Templates in folgendem Ordner mitgeliefert: home\razor

Die bestehenden Dateien mit Prefix tk- dürfen nicht editiert werden, da sie mit einem zukünftigen TK-Update überschrieben werden!

Bei Bedarf können Projekt-spezifische Razor-Templates mit einem eigenen Prefix im gleichen Ordner abgelegt werden. Diese Dateien werden durch ein Update nicht überschrieben!

• Für JS-Selektoren werden Data-Attribute eingesetzt.
• Für Selektoren, welche in der Grundfunktionalität mit dem CDN ausgeliefert werden, wird das Naming "data-op-xxx" berücksichtigt.
• Projekt-Spezifische-Attribute werden mit dem Prefix "data-tk-" geschrieben.
• wo nötig und sinnvoll, werden Custom-Elements erstellt und eingesetzt. Custom-Elements werden mit dem Prefix "tk" erstellt.

• Für das Styling des TK werden CSS-Klassen eingesetzt.
• CSS wird nach der BEM Konvention im "Two Dashes Style" aufgebaut.
  • Controls und Components werden mit dem Prefix "tk" versehen.
    
  • Markup für die Seitenstruktur wird NICHT mit einem Prefix geschrieben.
    
• Es werden keine fixen Werte im CSS verwendet. Stattdessen werden CSS3 Variablen eingesetzt.
• Default CSS-Werte werden gem. folgender Namenskonvention benannt. --> Beispiel: $default-btn-size.

Einleitung

PostCSS ist ein mächtiges Werkzeug zur Transformation von CSS-Dateien mittels JavaScript. Anders als herkömmliche Präprozessoren wie Sass oder Less, die eigene Syntaxen verwenden, analysiert PostCSS CSS-Dateien als JavaScript-Objekte und ermöglicht es Entwicklern, Plugins zu verwenden, um verschiedene Transformationen durchzuführen. Diese Transformationen reichen von der Hinzufügung von Browserpräfixen über die Optimierung von Stylesheets bis hin zur Generierung von CSS aus anderen Sprachen wie Sass oder Less. PostCSS ist bekannt für seine Flexibilität und Erweiterbarkeit, was es zu einem beliebten Werkzeug in modernen Frontend-Entwicklungsumgebungen macht.

In unserem Fall nutzen wir diverse Plugins, dass es möglich macht gewisse SASS-Funktionalitäten in CSS zu nutzen. In diesem Kapitel werden alle Plugins aufgelistet und mit Beispielen diverse Möglichkeiten gezeigt.

VS Code Extension

Damit die Syntax übereinstimmt wird diese VSCode Extension empfohlen: vscode-postcss

PostCSS Config

Im postcss.config.js File hat man die Möglichkeit die Plugins zu integrieren. Die Reihenfolge hat Einflus auf den generierten Code. In unserem spezifischen Szenario erfolgt zunächst die Entfernung sämtlicher Kommentare, gefolgt von der Konsolidierung sämtlicher CSS-Dateien zu einer einzigen Datei.

PostCSS Discard Comments

Dieses Plugin entfernt alle Kommentare /* comment */. Wichtige Kommentare mit einem Ausrufezeichen /*! comment */ werden nicht entfernt.

Weitere Infos unter: NPM (PostCSS Discard Comments)

PostCSS Import

Dieses Plugin ermöglicht es .css Files zu importieren.

Input

Output

Weitere Infos unter: NPM (PostCSS Import)

PostCSS map-get

Dieses Plugin ermöglicht es die Funktion map-get($list, $key) zu nutzen, die auch in SASS bekannt ist.

Weitere Infos unter: NPM (PostCSS map-get)

PostCSS Advanced Variables

Dieses Plugin ermöglicht es viele Sass-Funktionaltitäten zu nutzen wie Variablen, Bediengungen und Iteratoren.

Variablen

Wir empfehlen für Template-Strings nur $(var-name) zu nutzen und nicht #{$var-name}.

@if und @else Regeln

@for und @each Regeln

Aktuell kann die @each Funktion nur Listen ausgeben und keine Maps, aber die Erweiterung ist bereits als Pull-Request erfasst im GitHub.

@mixin und @include Regeln

Weitere Infos unter: NPM (PostCSS Advanced Variables)

PostCSS - Calc

PostCSS Calc ermöglicht es Ihnen, Verweise auf calc() zu reduzieren, wann immer dies möglich ist. Wenn mehrere Einheiten in derselben Ausdruck gemischt werden, bleibt die calc()-Anweisung unverändert, um auf die W3C-calc()-Implementierung zurückzugreifen.

Weitere Infos unter: NPM (PostCSS Calc)

PostCSS - Functions

Dieses Plugin ermöglicht es, JavaScript Funktionen als CSS-Funktionen zu brauchen. Wichtig ist, dass der Return-Wert immer ein String ist.

Weitere Infos unter: NPM (PostCSS Functions)

PostCSS - Current Selector

Dieses Plugin ermöglicht es, den aktuellen Selektor in eine Variable zu speichern, dass das Anwenden von BEM vereinfacht um so einen sauberen Aufbau zu halten von unserem CSS-File. In unseren Einstellungen ist das Symbol ^@ konfiguriert.

BEM Beispiel

Weitere Infos unter: NPM (PostCSS Current Selector)

PostCSS - Nested

Dieses Plugin ermöglicht es, Nested Rules anzuwenden in CSS.

Weitere Infos unter: NPM (PostCSS Nested)

PostCSS - Autoprefixer

Das PostCSS-Plugin analysiert CSS und fügt Herstellerpräfixe zu CSS-Regeln hinzu, wobei Werte von "Can I Use" verwendet werden. Es wird von Google empfohlen und von X sowie Alibaba verwendet.

Weitere Infos unter: NPM (PostCSS Autoprefixer)

Die SVGToFont Library um Icon Font und SVG Symbols zu generieren bietet somit eine super Gelegenheit an, um je nach Situation beide Methoden zu nutzen.

Vorteile von Icon Font:

• Einfache Nutzung durch CSS3-Variablen
• Weniger Markup
• Anwendung in Pseudo-Elementen mit content-Property. z.B. content: var(--tk-icon-add);
• Minimale File-Grösse

Vorteile von SVG Symbols

• Bessere Skalierbarkeit, somit besseres Rendering
• Customization, also Mehrfarbigkeit ist möglich
• Accessibility, es können title und desc Tags genutzt werden, dass das Lesen von Screen Readers und Text Browser vereinfacht.

Beide Methoden haben ihre Vor und Nachteile. Es kommt immer auf den Anwendungsfall drauf an, welche Methode man nutzen möchte.
Wir empfehlen:

• Soll das Icon grösser gleich als 20px sein? Dann empfehlen wir Icon Font
• Ist das Icon losgelöst von anderen HTML-Tags, nicht in einem Button oder Anchor? Dann empfehlen wir SVG Symbols um title und desc Tags zu nutzen.
  In einem Button können aria- Tags genutzt werden.

Der Startseitenslider, die Neuheiten, Aktionen und Topseller werden über Artikelpools gesteuert. Aus diesem Grund müssen im ERP folgende Artikelpools definiert und anschliessend im Katalog hinterlegt werden.

Pool Bezeichnung	Katalog Zuweisung	Besonderheit
Pool Bezeichnung Startseitenslider	Katalog Zuweisung Cat.ArtPoolNo1	Besonderheit ArtPoolItem.Free1 = Aktiv (Boolean) ArtPoolItem.Free4 =Sortierung (Numerisch)
Pool Bezeichnung Neuheiten	Katalog Zuweisung Cat.ArtPoolNo2	Besonderheit
Pool Bezeichnung Aktionen	Katalog Zuweisung Cat.ArtPoolNo3	Besonderheit
Pool Bezeichnung Topseller	Katalog Zuweisung Cat.ArtPoolNo4	Besonderheit

Damit im TemplateKit die News / Aktionen / Topseller korrekt angezeigt werden können, müssen in der ES Konfig Datei folgende Attribute enthalten sein:

Die Steuerung der Differenzierungs- und Filterattribute erfolgt über einen Hilfskatalog. Mit folgendem Skript lässt sich der Hilfskatalog automatisiert erstellen.
F-Script Name: TK-Cat-FillHelper-01.ff

Das Skript übernimmt folgende Parameter:

Parameter	Beschreibung	Beispiel
Parameter CatProcess.CatNo	Beschreibung Katalognummer des eigentlichen EnterpriseShop Katalog	Beispiel 100
Parameter CatProcess.ConfigNo	Beschreibung Verarbeitungskonfiguration des eigentlichen EnterpriseShop Katalog	Beispiel 1
Parameter CreateHelperCat	Beschreibung Soll der Hilfskatalog automatisiert erstellt werden?	Beispiel 1
Parameter HelperCatNo	Beschreibung Nummer des Steuerungskatalog, falls er erzeugt werden soll.	Beispiel 110
Parameter HelperCatDescription	Beschreibung Beschreibung des Steuerungskataloges	Beispiel Steuerungskatalog EShop 100

Das Skript hat folgenden Zweck:

• Initiales Eröffnen des Steuerungskatalog
  • Der neue Steuerungskatalog wird automatisch beim eigentlichen Katalog auf Cat.Free4 hinterlegt.
  • Der Schattenartikel CAT-HELPER wird automatisch eröffnet.
  • Folgende Werte / Redefinitionen werden via Skript automatisch erstellt:
    • Cat.NoDuplicateArticles = 0
    • Cat.CatArtNo = CAT-HELPER
    • Ul>Cat.StructItemsAllowed = 1
    • Redefinitionen
      • CatStruct.Free7 = Kategorie / A
      • CatItem.Free1 = Datentyp / A
      • CatItem.Free2 = Differenzierungsattr / B
      • CatItem.Free3 = SelectBox Attr? / B
      • CatItem.Free4 = Unit / A
      • CatItem.Free8 = ArtSpecType / A
      • CatItem.Free9 = Bo / A
      • CatItem.Free10 = BoAttr / A
      • CatItem.Free14 = ArtSpecGroupNo / A
      • CatItem.Free19 = RelatedObject / A
      • CatItem.Free20 = RelatedBo / A
      • CatItem.Free21 = RelatedConstraint / A
      • CatItem.Free22 = ArtSpecGroupName / A
• Repetitives Abgleichen aller Artikelmerkmalstypen und Attribute
  • Dabei werden "nur" neue Artikelmerkmale sowie neu definiert Attribute ergänzt.
  • Bestehende Attribute werden nicht mehr mutiert!
  • Sinnvollerweise wird das Skript in der Katalogverarbeitung Cat.ScriptProcessFree hinterlegt. Somit sind die Steuerungsattribute immer aktuell mit dem aktuellen Katalog.

Zugehörig zum Steuerungskatalog benötigt es noch einen zusätzlichen Attributssteuerungs ES Index mit folgender Definition:
Wichtig: Die Bezeichnung im Feld Name muss dem zugewiesen Wert aus der Hilfskatalogzuweisung aus Cat.Free4 enstrepchen

Das F-Script ist unter dem Pfad /webportal/config/layout/include/fscript/TK-Cat-FillHelper-01.ff zu finden.

Folgende Attribute müssten im ES-Index Config ergänzt werden: