Erstellen einer neuen Komponente
- Dominik Hisler
- Sebastian Schulz
Eine Komponente in den Styleguides von brandbox ist ein einfach per PHP-Code aufbaubares Element, welches entweder in brandbox oder dem Browser in HTML-Code übersetzt wird. Jede Komponente darf eigenes SCSS sowie Javascript enthalten. Diese Anleitung befasst sich mit dem Erstellen einer einfachen Komponente mit dem Namen article und zusätzlichen Bausteinen innerhalb des Styleguides custom. Eine andere Anleitung befasst sich mit dem Überschreiben einer existierenden Komponente.
Namenskonvention
Der Name einer Komponente muss innerhalb des definierenden Styleguides eindeutig sein und muss den Namen des Styleguides vorangestellt haben. Als Trennzeichen zwischen Wörten sollte der Bindestrich verwendet werden. Die Nutzung von CamelCase ist, mit Ausnahme der PHP-Dateien, nicht erwünscht. In diesem Tutorial wird custom-article als Definitionsname der Komponente und Brandbox\CustomStyleguide\Entity\CustomArticle als der vollständige PHP-Klassenname für die Komponentdefinition genutzt.
Unterscheidung zwischen Komponenten und Elementen
Eine Komponente ist eine alleinstehende Einheit, welche mit anderen Komponenten kombiniert werden darf. Eine Komponente ist bspw. der Container einer Navigationsleiste oder Toolbar. Ein Element ist immer einer Komponente zugeordnet und darf auch nur in dieser Komponente platziert werden. Ein Element ist bspw. das Logo oder eine Verlinkung innerhalb einer Navigationsleiste. Ein Element darf ebenfalls Komponenten darstellen, bspw. darf die Komponente framework-button innerhalb eines Elements der fiktiven Navigationseliste dargestellt werden.
Dateistruktur für Komponenten und Elemente
Die nachfolgende Dateistruktur wird für Elemente und Komponenten genutzt. Ein Element muss zusätzlich innerhalb eines Unterordners mit dem Namen der Komponente erstellt werden (bspw. element/custom-article/custom-article-element/). In eckingen Klammern eingeschlossene Elemente sind optional und müssen nicht existieren.
custom-articlecustom-article.hbs[custom-article.js]custom-article.config.js[_layout.scss][_default.scss]CustomArticle.php
Vorlagendefinition
Die Vorlage von Styleguidekomponenten wird mithlfe von Handlebars definiert. Handlebars ist eine HTML-Template-Sprache welche viele nützliche Aspekte wie Variablen, Schleifen und Bedingungen ermöglicht um HTML-Code zu erzeugen. Weitere Informationen zu Handlebars sind unter https://handlebarsjs.com/guide/ verfügbar.
<!-- custom-article.hbs -->
{{#> framework-element this }}
<!-- Der Helper "framework-element" erstellt ein HTML-Element, somit muss hier nur der innere HTML-Code geschrieben werden -->
{{/framework-element}}Styleguidedefinition
Damit die neue Komponente auch in der Fractal-Oberfläche dargestellt und von Beispielen eingebunden werden kann, muss eine Javascript-Definition erstellt werden.
// custom-article.config.js
'use strict'
/**
* @param {string[]} [variants]
* @param {object} [attributes]
*
* @return {object}
*/
function _generate_element(variants, attributes) {
const element = include('framework-styleguide/component/framework-element/framework-element.config')
return Object.assign({}, element.context, {
partial: 'custom-article',
tag: 'article', // Definiert den zu nutzenden HTML-Tag für den Helper "framework-element". Standardmäßig wird "div" genutzt.
variants: variants || ['standard'], // Entweder werden die übergeben Varianten (Modifier in BEM) oder die Standardvariante genutzt.
attributes: Object.assign({
'data-module': 'styleguide/custom-article'
}, attributes || {}), // Das Tutorial wird ein Javascript enthalten, daher müssen dieses ebenfalls definieren und zusätzlich mögliche externe Attribute berücksichtigen.
})
}
module.exports = {
label: 'Komponentenbezeichnung',
context: _generate_element(),
generator: _generate_element, // Stellt die Generatorfunktion für bspw. Beispiele bereit.
}PHP-Definition
Neben der Styleguidedefinition für Fractal muss auch eine PHP-Definition für brandbox vorhanden sein damit die Komponente über brandbox erstellt und erzeugt werden kann. Die PHP-Definition sollte deckungsgleich mit der Styleguidedefinition sein.
<?php
declare(strict_types=1);
namespace Brandbox\CustomStyleguide\Entity {
use Brandbox\FrameworkStyleguide;
class CustomArticle extends FrameworkStyleguide\Entity\FrameworkElementAbstract
{
public string $partial = 'custom-article';
public string $tag = 'article'; // Auch hier wird standardmäßig "div" genutzt.
public array $variants = ['standard'];
public array $attributes = [
'data-module': 'styleguide/custom-article'
];
}
}Optionales Javascript
Die Javascriptdatei für ein Element oder eine Komponente ist optional uns muss nur bei Bedarf erstellt werden. Hierbei muss beachtet werden, dass requirejs genutzt wird.
Layoutdefinition
Jede Komponente und jedes Element können mithilfe von SCSS ein Layout für die entsprechende Komponete oder Element erstellen. In der Datei _layout.scss wird hierbei das Layout für die Komponenten oder das Element definiert, in der Datei _default.scss die SCSS-Variablen für das Layout. Es dürfen weitere Dateien erstellt werden, welche allerdings manuell in den beiden genannten eingebunden werden müssen. Die Trennung zwischen Layout und Variablen ist für die fehlerfreie Funktion der Styleguides erforderlich und muss eingehalten werden. Die Konventionen für SCSS-Code können unter https://konmedia.atlassian.net/wiki/x/C4BqAg nachgelesen werden. Weitere Information zu SCSS-Variablen sind unter https://sass-lang.com/documentation/variables zu finden. Alle SCSS-Variablen aus der _default.scss sollten zudem mit dem Kennzeichen !default versehen werden, damit diese überschrieben werden können.