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ähnlich zu einer normalen App, welcher durch Composer installiert werden kann. Für einen Styleguide wird das vendor prefix auf brandbox-styleguide gesetzt und der Name des Pakets muss auf -styleguide enden. In diesem Tutorial wird als Name für den Styleguide custom genutzt. Die nachfolgende Ordnerstruktur ist für einen Styleguide erforderlich. In eckigen Klammern eingeschlossene Elemente sind optional.
custom-styleguide[asset]componentelement[example][javascript][scsstemplates][preview-custom-styleguide]preview-custom-styleguide.config.jspreview-custom-styleguide.hbs
composer.jsoncustom-styleguide.config.json
composer.json
| Codeblock |
|---|
| language | js |
|---|
| theme | RDark |
|---|
title | Wichtigste Elemente der
|
// composer.json |
| collapse | true |
|---|
{
"name": "brandbox-styleguide/custom-styleguide",
// ...
"autoload": {
"classmap": [
"component/",
"element/"
]
}
}
|
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 |
...
| Codeblock |
|---|
| language | js |
|---|
| theme | RDark |
|---|
| title | Struktur der custom-styleguide.config.json |
|---|
| collapse | true |
|---|
|
{
"label": "custom",
"order": 123,
"priority": 456,
"depends": ["framework-styleguide", "other-styleguide"],
"previewpriority": "@preview-framework-styleguide"1001
}
|
Eigenschaften der Styleguidedefinition
Die nachfolgenden Eigenschaften können in der custom-styleguide.config.json definiert werden.
| 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 (Partialspartials) 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. |
example | Hier können Beispiele für die in diesem Styleguide enthaltenene Komponenten und Layouts aufgebaut werden. Ein Beispiel ist technisch ähnlich zu einer Komponente, enthält allerdings kein PHP-Code. |
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. |
...
preview-[Styleguidename] | Definiert den für diesen Styleguide zu nutzenden Seitenrahmen innerhalb von Fractal. Wird dieser nicht definiert, wird der Seitenrahmen von framework-styleguide genutzt. Die Definition eines Seitenrahmens wird weiter unten besprochen. |
Globale Layoutdefinitionen
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 Anweisungen 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
...
Definition eines Seitenrahmens
Wird ein eigener Seitenrahmen für den Styleguide benötigt, dann kann dieser im Ordner preview-[Styleguidename] definiert werden. Der Platzhalter [Styleguidename] kann in unserem Beispiel durch custom-styleguide ersetzt werden, der Ordername wäre damit preview-custom-styleguide. Innerhalb dieses Ordner müssen die zwei Dateien preview-[Styleguidename].config.js sowie preview-[Styleguidename].hbs erstellt werden.
| Codeblock |
|---|
| language | js |
|---|
| theme | RDark |
|---|
| title | Struktur der Konfiguration |
|---|
| collapse | true |
|---|
|
{
"label": "Bezeichnung", // Komponenten für component und Elemente für element
"order": 123, // 2 für element und 3 für component
"status": "Status", // component für component und element für element
"prefix": "something" // [Name des Styleguide]-[component|element]
} |
...
// preview-custom-styleguide.config.js
'use strict'
module.exports = {
label: 'Seitenrahmen: custom-styleguide',
hidden: true,
context: {
domain: `http://${require('os').hostname()}.local.brandbox.de`
}
}
|
| Codeblock |
|---|
|
<!-- preview-custom-styleguide.hbs -->
<!doctype html>
<html lang="de">
<head>
<title>Seitenrahmen: custom-styleguide</title>
</head>
<body>
{{{ yield }}}
{{{ switcher }}}
</body>
</html>
|
Der Platzhalter {{{ yield }}} wird durch den darzustellenden HTML-Code ersetzt. Der Platzhalter {{{ switcher }}} platziert der Theme-Umschalter der Fractal-Oberfläche.