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]
componentelement[example][javascript][scss][preview-custom-styleguide]preview-custom-styleguide.config.jspreview-custom-styleguide.hbs
composer.jsoncustom-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 |
|---|---|
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 (partials) 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 |
|---|---|
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 |
|---|---|
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.