Frontend-Workflow von Magento 2 einrichten

Auf dem letzten Firegento Hackathon in Paderborn haben wir uns in einer Gruppe mit den Neuerungen im Bereich des Frontends von Magento 2 auseinandergesetzt. Trotz der umfangreichen Dokumentation hatten wir mit einigen Startschwierigkeiten zu kämpfen. Um zukünftig leichter in die Entwicklung des Frontends von Magento 2 einsteigen zu können, zeigt dieser Beitrag, wie man Schritt für Schritt einen Frontend-Workflow einrichtet - und dabei die Stolpersteine, mit denen wir auf dem letzten Hackathon zu kämpfen hatten, zu umgehen.

Dieser Beitrag soll nicht die Funktionsweise der Frontend-Mechanismen von Magento 2 im Einzelnen beleuchten (dies wird Bestandteil eines separaten Blogbeitrags sein), sondern Frontend-Entwicklern, die sich (wie ich) gerade in der Transition befinden, beim Herstellen eines funktionierenden Ausgangszustands behilflich sein.

Da es bereits bei der Installation einige Varianten und Fallstricke gibt, empfehlen wir, zunächst unseren Blogbeitrag zur Installation von Magento 2 zu lesen und anhand dessen die Installation aufzubauen.

Wichtig dabei: Es sollte der Developer Mode aktiviert werden. Magento 2 sollte auf keinen Fall im Default Mode betrieben werden, einem wenig nützlichen Hybrid-Modus. Weitere Informationen dazu finden sich auch in der Dokumentation, Erläuterungen der Modes bietet erneut Alan Storm.

bin/magento deploy:mode:set developer

Wir können nun in unserem Browser das Frontend öffnen und bekommen das Luma Theme präsentiert.

Allgemeine Projektstruktur

Der in diesem Fall gewählter Installationstyp "Integrator/Packager" nutzt die Vorzüge von Composer. Alle Magento-Module liegen Composer-typisch unter

<installation directory name>/vendor/magento

Eigene Module bzw. Themes können auf zwei Arten hinzugefügt werden:

Über die composer.json
Klassisch in den Verzeichnissen app/code bzw. app/design

Grunt-Umgebung einrichten

Ist die Installation abgeschlossen, folgt als nächster Schritt die Einrichtung der Grunt-Umgebung. Alle beschriebenen Schritte sind grundsätzlich auch in der offiziellen Dokumentation zu finden, wenn auch nicht derart kompakt.

Zunächst benötigen wir node.js für unseren Stack.

Dann können wir die Grunt CLI installieren

npm install -g grunt-cli

und anschließend die projektspezifischen Abhängigkeiten initialisieren

cd <installation directory name> && npm install

Ob alles korrekt installiert wurde, können wir durch folgenden Aufruf testen:

$ grunt
Running "default" task

I'm default task and at the moment I'm empty, sorry :/

Done, without errors.


Execution Time (2016-02-01 08:54:44 UTC)
loading tasks  393ms  â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡â–‡ 98%
default          5ms  â–‡â–‡ 1%
Total 400ms

Theme Dateien erstellen und in Magento 2 verwenden

In Magento 2 werden Themes nach folgendem Schema im Dateisystem angelegt:

app/design/frontend/<Vendor>/<Theme>/

Wir erstellen für ein minimales Setup ein Theme, das von Luma erbt. Dafür legen wir folgende Dateien an:

// app/design/frontend/<Vendor>/<Theme>/registration.php
<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::THEME,
    'frontend/<Vendor>/<Theme>',
    __DIR__
);

<!-- app/design/frontend/<Vendor>/<Theme>/theme.xml -->
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Vendor: Theme Name</title>
    <parent>Magento/luma</parent>
</theme>

Zwei Kleinigkeiten passen wir auch direkt an, damit wir gleich auf den ersten Blick sehen, dass wir nicht mehr das Original Luma Theme nutzen:

// app/design/frontend/<Vendor>/<Theme>/web/css/source/_theme.less
@navigation__background: @color-blue1;
@navigation-desktop-level0-item__color: @color-white;

Dann wählen wir das Theme im Backend aus:

Stores > Configuration > Design > Design Theme

Frontend-Workflow mit Grunt beginnen

Bevor wir richtig loslegen können, müssen wir zunächst Grunt mitteilen, dass wir soeben ein neues Theme erstellt haben. Das tun wir mit folgendem Dateieintrag:

// dev/tools/grunt/configs/themes.js
// Add following to config array:
<grunt theme name>: {
        area: 'frontend',
        name: 'Vendor/Theme',
        locale: 'de_DE',
        files: [
            'css/styles-m',
            'css/styles-l'
        ],
        dsl: 'less'
    }

Danach sollten folgende Schritte einmal zu Beginn der Arbeiten ausgeführt werden:

Statische Dateien u. Caches bereinigen:
```
grunt clean
```
Sammeln der Ressourcen und Aufbau statischer Dateien für unser Theme:
```
grunt exec:<grunt theme name>
```
Anstoßen des Preprocessing:
```
grunt less:<grunt theme name>
```
Anschließend die Seite im Frontend aktualisieren!

Der erste Seitenaufruf kann exzessive Ladezeiten mit sich bringen, da Magento 2 im Hintergrund das Preprocessing anstößt und dabei eine große Anzahl an Dateien zu verarbeiten hat.

Voilà! Wir haben erfolgreich mit dem Magento-eigenen Workflow die Hintergrund- und Schriftfarbe der Menüleiste angepasst. Um jetzt produktiv zu starten, brauchen wir nur noch den Watch Task zu starten:

grunt watch

Ändern wir eine LESS Datei, so aktualisiert Grunt die erforderlichen Dateien und wir brauchen nur das Frontend neuzuladen (Bei mit installiertem LiveReload-Plugin im Browser ist selbst das nicht mehr notwendig).

Fragen zur Magento-2-Frontendentwicklung

Der Einstieg in die Entwicklung des Magento-2-Frontends kann viele Fragen aufwerfen: Warum haben wir ausgerechnet diese LESS-Datei angepasst? Was sind das für komische Variablen? Was fange ich jetzt produktiv damit an? Die Beantwortung dieser Fragen würde den Rahmen dieses Beitrags sprengen. Hinterlasst bei konkreten Fragen gerne einen Kommentar, dann gibt es dazu vielleicht bald einen eigenen Blog-Beitrag.

Wir befinden uns alle noch am Anfang der Arbeit mit Magento 2. Das von Magento 2 eingeführte Templating- und Preprocessing-System mit seiner eigenen LESS-Bibliothek ist extrem komplex. Während des Schreibens dieser Zeilen bin ich selbst noch damit beschäftigt, die Hintergründe und Abhängigkeiten umfänglicher zu erschließen. Für den tieferen Einstieg lege ich das gründliche Studium der offiziellen Dokumentation nahe.

Eine Dokumentation zu Aufbau, Inhalt, Coding Standards etc. der Frontend Library findet sich auch in den Sourcen selbst in folgender Datei: lib/web/css/docs/source/README.md

Trouble Shooting

Änderungen an Dateien

In einigen Fällen (z.B. dem Hinzufügen neuer Dateien) kann es nötig sein, das Ganze noch einmal neu zu initialisieren:

grunt clean
grunt exec:<grunt theme name>
grunt less:<grunt theme name>

Generelle "unidentifizierte" Probleme

Folgende Checkliste sollte das System wieder zurücksetzen und Änderungen sichtbar machen:

Löschen der für das Theme relevanten statischen Dateien unter: pub/static/frontend/ var/view_preprocessed/less/ var/view_preprocessed/source/
Löschen des Magento Caches (Backend, bin/magento CLI oder n98-magerun2)
bin/magento setup:static-content:deploy <lang_LANG>
Grunt Workflow starten

Credits

Mein herzlicher Dank gilt Maria Kern für das freundliche Zurechtrücken einiger fehlgeleiteter Gedanken.

B2B E-Commerce mit System

Service

integer_net

Ressourcen

Schritt für Schritt: Frontend-Workflow von Magento 2 einrichten