Ein Styleguide in brandbox ist technisch gesehen ein durch Composer installierbares Paket. Es verfügt über ein eigenes vendor prefix
innerhalb der composer.json und muss einer festen Struktur von Ordnern und Dateien folgen.
custom-styleguide
asset
component
element
javascript
scss
templates
composer.json
custom-styleguide.config.json
composer.json
Zum einen muss auf den Namen des Composer-Paketes geachtet werden. Als vendor prefix
muss brandbox-styleguide
genutzt werden. Zudem muss der Name des Pakets auf -styleguide
enden. Als Autoloader muss die classmap
genutzt werden, da die Datenklassen der Komponenten eines Styleguide nicht den Vorgaben von PSR folgen.
custom-styleguide.config.json
Eigenschaft | Beschreibung |
---|---|
label | Der Name des Styleguides welcher innerhalb der Fractal-Oberfläche dargestellt wird. |
order | Die Position des Styleguides innerhalb der Fractal-Oberfläche. Diese Eigenschaft bestimmt nur die Position innerhalb der Liste aller Styleguides und hat keinerlei Einfluss auf die Priorität des Styleguides. |
priority | Die Priorität des Styleguides bestimmt die Ladereihenfolge der HBS-Dateien (Partials) und Überschreibungsreihenfolge der SCSS-Dateien. Es wird mindestens 1001 als Priorität empfohlen, zudem muss diese einzigartig sein. |
depends | Legt die Reihenfolge und Styleguides fest, welche vor diesem Styleguide verarbeitet werden müssen. Styleguides welche für eine Benutzeroberfläche erstellt werden, müssen mindestens den framework-styleguide als Abhängigkeit ausweisen. |
preview | Die innherlab von der Fractal-Oberfläche genutzte Rahmenvorlage für die Darstellung einer Komponente. |
Optionale Ordner
Nicht alle in der Sturktur gelisteten Order sind notwendig um einen Styleguide einsatzfähig zu machen. Nachfolgend finden Sie eine Liste der optionalen Order und ihrer Funktionen.
Ordner | Beschreibung |
---|---|
asset | Hier können Bilddateien innerhalb des Unterordners images und Schriftdateien für Browser innerhalb des Unterordners fonts abgelegt werden. Diese Dateien werden durch einen Node-Task aus allen Styleguides eingesammelt und an eine öffentlich zugängliche Stelle der brandbox-Installation kopiert. |
javascript | Hier können Javascripte, welche keiner Komponente zuzuordnen sind, abgelegt werden. Diese werden zusätzlich zu den Javascripten der Komponenten eingesammelt und eine öffentlich zugängliche Stelle kopiert. |
scss | Zusätzlich zu den SCSS-Dateien der einzelnen Komponenten können globale SCSS-Dateien in diesem Order abgelegt werden. Weitere Informationen hierzu sind den nachfolgenden Punkten zu entnehmen. |
templates | Manche Subsysteme von brandbox gestatten die Auswahl einer Rahmenvorlage. Dabei werden unter anderem die HBS-Dateien aus diesen optionalen Ordnern der Styleguides angeboten. |
Sonderrolle scss
Wird der optionale Order scss
innerhalb eines Styleguides eingesetzt, muss dieser eine bestimmte Orderstruktur einhalten. Nachfolgend ist diese Struktur aufgelistet und genauer beschrieben. Alle Namen der SCSS-Dateien in diesen Ordnern müssen mit einem Unterstrich (_
) beginnen. In allen Fällen ist das Strukturieren von komplexeren Teilen in Unterordner mit eigenen SCSS-Dateien möglich. Es werden jedoch nur die SCSS-Dateien aus dem Hauptordner automatisch geladen. Daher müssen Dateien aus Unterordnern selbst eingebunden werden.
Ordner | Beschreibung |
---|---|
variable | Durch diesen Ordner können neue globale SCSS-Variablen deklariert oder bereits aus anderen Styleguides existierende Variablen mit einem anderen Standardwert versehen werden. Um neue globale Variablen zu deklarieren muss die Datei _default.scss genutzt werden oder um bereits aus anderen Styleguides existierende globale Variablen mit einem anderen Standardwert zu befüllen muss die Datei _override.scss genutzt werden. |
mixin | Hier können Hilfsfunktionen (https://sass-lang.com/documentation/at-rules/mixin, https://sass-lang.com/documentation/at-rules/function) für SCSS erstellt werden. Die Namen dieser Dateien sind über die geladenen Styleguides hinweg eindeutig. Daher wird bspw. eine SCSS-Datei mit dem Namen _test.scss nur aus dem Styleguide mit der höchsten Priorität (von allen Abhängigkeiten und dem aktuellen) geladen. |
global | In diesem Ordner können CSS-Anweisungen deklariert werden, welche außerhalb des Theme-Identifikators benötigt werden. Üblich sind hier Dateien mit @font-face Deklarationen. Wie auch bei Dateien aus dem Ordner mixin sind auch hier die Namen der Datei eindeutig. |
plugin | Hier können bspw. CSS-Anweisungen für Javascript-Plugins (Select2, jQueryUi, etc.) abgelegt werden, da diese meist keiner Komponente aus dem Styleguide zuzuordnen sind. Auch hier sind die Namen der Dateien eindeutig. |
scaffolding | CSS-Anwesungen für HTML-Elemente welche keiner Komponente aus dem Styleguide zuzuordnen sind (bspw. body ) können hier abgelegt werden. Auch hier sind die Dateinamen eindeutig. |
Komponenten und Elemente
In den Ordnern component
und element
befinden sich die einzelnen Komponenten des Styleguides. Hierbei ist zu beachten, dass der Ordner element
nur Bausteine für Komponenten in component enthalten darf und daher immer den Namen der Komponente als Unterordner enthalten muss (bspw. element/component-name/component-element/
). Beide Ordner enthalten ebenfalls eine enstprechende Konfigurationsdatei (component.config.json
bzw. element.config.json
).
Wie erstelle ich eine neue Komponente?
Wie überschreibe ich eine existierende Komponente?