Ein Styleguide in brandbox ist ä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]
  - [images]
  - [fonts]
- component
- element
- [example]
- [javascript]
- [scss]
- [preview-custom-styleguide]
  - preview-custom-styleguide.config.js
  - preview-custom-styleguide.hbs
- composer.json
- custom-styleguide.config.json

// composer.json
{
    "name": "brandbox-styleguide/custom-styleguide",
    "autoload": {
        "classmap": [
            "component/",
            "element/"
        ]
    }
}

// custom-styleguide.config.json
{
	"label": "custom",
	"depends": ["framework-styleguide"],
	"priority": 1001
}

Eigenschaften der Styleguidedefinition

Die nachfolgenden Eigenschaften können in der custom-styleguide.config.json definiert werden.

Eigenschaft	Beschreibung

Eigenschaft	Beschreibung
`label`	Der Name des Styleguides welcher innerhalb der Fractal-Oberfläche dargestellt wird.
`priority`	Die Priorität des Styleguides bestimmt die Ladereihenfolge der HBS-Dateien (p`artials`) und Überschreibungsreihenfolge der SCSS-Dateien. Es wird mindestens `1001` als Priorität empfohlen.
`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.

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

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.
`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

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-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.

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.

// preview-custom-styleguide.config.js
'use strict'

module.exports = {
	label: 'Seitenrahmen: custom-styleguide',
	hidden: true,
	context: {
		domain: `http://${require('os').hostname()}.local.brandbox.de`
	}
}

<!-- 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.

brandbox – Eine Plattform, unendliche Möglichkeiten

Erstellen eines neuen Styleguides

Eigenschaften der Styleguidedefinition

Optionale Ordner

Globale Layoutdefinitionen

Definition eines Seitenrahmens