Zum Ende der Metadaten springen
Zum Anfang der Metadaten

Sie zeigen eine alte Version dieser Seite an. Zeigen Sie die aktuelle Version an.

Unterschiede anzeigen Seitenhistorie anzeigen

« Vorherige Version anzeigen Version 12 Nächste Version anzeigen »

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

Wichtigste Elemente der composer.json
{
    "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

Struktur der custom-styleguide.config.json
{
	"label": "custom",
	"order": 123,
	"priority": 456,
	"depends": ["framework-styleguide", "other-styleguide"],
	"preview": "@preview-framework-styleguide"
}
EigenschaftBeschreibung
labelDer Name des Styleguides welcher innerhalb der Fractal-Oberfläche dargestellt wird.
orderDie 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.
priorityDie 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.
dependsLegt 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.
previewDie 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.

OrdnerBeschreibung
assetHier 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.
javascriptHier 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.
scssZusä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.
templatesManche 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.

OrdnerBeschreibung
variableDurch 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.
mixinHier 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.
globalIn 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.
pluginHier 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.
scaffoldingCSS-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).

Struktur der Konfiguration
{
	"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]
}

Wie erstelle ich eine neue Komponente?
Wie überschreibe ich eine existierende Komponente?

  • Keine Stichwörter