Styleguide
Version 23.02
Einleitung
Der Styleguide beschreibt die geltenden Konventionen und Richtlinien für die Verwendung eines TemplateKit. Zudem werden alle Bestandteile aufgelistet und mit dem im Projekt hinterlegten Styling visualisiert.
Richtlinien
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!
Konventionen
- 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.
- Controls und Components werden mit dem Prefix "tk" versehen.
- 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)
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
unddesc
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
unddesc
Tags zu nutzen.
In einem Button könnenaria-
Tags genutzt werden.