Fast jeder Admin-Bildschirm in Magento 2 - die Produktliste, die Kundenverwaltung, die Bestellübersicht, aber auch die meisten Bearbeitungsformulare - basiert auf demselben Framework: den UI Components. Wer eigene Admin-Bereiche baut, kommt an diesem Framework nicht vorbei. Diese Serie zeigt es von Grund auf: von der ersten leeren Tabelle bis zu Custom-Renderern, Inline-Edit und Export - demonstriert an einer durchgehenden Kundenstimmen-Verwaltung ab Block 4.

Zwei verschiedene Welten: Storefront und Admin

In diesem Projekt ersetzt Hyvä im Frontend KnockoutJS und die UI-Components vollständig (siehe die Hyvä-Tutorial-Serie) - im Adminbereich gilt das nicht. Das Backend nutzt weiterhin ganz regulär UI Components mit KnockoutJS-Templates, genau wie der Magento-Core selbst. Das ist kein Widerspruch: Hyvä ist ein Frontend-Theme-Ersatz, keine Admin-Alternative. Für Admin-Grids und -Formulare bleibt UI Components schlicht der Standard-Weg - und das ist auch gut so, denn es ist ein mächtiges, deklaratives Framework.

Die zwei Hauptbausteine: Listing und Form

UI Components ist ein Oberbegriff für ein ganzes Familien von Komponenten, aber im Admin-Alltag begegnen dir fast ausschließlich zwei Spielarten:

• Listing (Grid) - eine tabellarische Übersicht mit Spalten, Filtern, Sortierung, Paginierung und Massenaktionen. Deklariert in einer {name}_listing.xml-Datei.
• Form - ein Bearbeitungsformular mit Fieldsets, Feldern, Validierung und Speichern-Button. Deklariert in einer {name}_form.xml-Datei.

Beide leben unter view/adminhtml/ui_component/ im jeweiligen Modul, beide werden über eine ganz normale Layout-XML-Datei (view/adminhtml/layout/) in eine Controller-Seite eingebunden, und beide folgen demselben grundsätzlichen Aufbau: eine PHP-Klasse liefert die Daten (der DataProvider), die XML-Datei beschreibt Struktur und Darstellung, und im Browser übernimmt JavaScript (KnockoutJS-Templates plus ein uiComponent-Registry) die eigentliche Darstellung und Interaktivität.

Der Datenfluss im Überblick

Grob läuft es für ein Grid so ab: Der Controller ruft die Layout-XML auf, die ein uiComponent mit dem Namen der Listing-Datei einbindet. Magento lädt {name}_listing.xml, liest darin unter anderem den Verweis auf eine DataProvider-Klasse. Diese Klasse baut eine Collection, wendet Filter/Sortierung aus dem Request an und liefert die Daten als Array zurück. Das Array wird zu JSON serialisiert und an die JavaScript-Seite übergeben, wo KnockoutJS-Templates (aus dem Modul Magento_Ui) daraus die eigentliche Tabelle rendern - inklusive Filterleiste, Paginierung und Massenaktions-Dropdown.

Für ein Formular ist der Ablauf fast identisch, nur dass die DataProvider-Klasse genau einen Datensatz (per request_field_name, meist die ID aus der URL) statt einer Liste liefert, und die XML-Datei statt Spalten Fieldsets und Felder beschreibt.

die xml-datei als vertrag

Ein wichtiger Denkanstoß für den Einstieg: Die XML-Datei ist kein reines Konfigurationsformat, sondern ein Vertrag zwischen PHP und JavaScript. Jedes <item>-Element mit einem component-Attribut referenziert ein RequireJS-Modul (zum Beispiel Magento_Ui/js/grid/columns/date für eine Datumsspalte). Die PHP-Seite liefert nur Rohdaten - wie diese Rohdaten aussehen (Datumsformat, Dropdown-Optionen, Bildvorschau), entscheidet die JavaScript-Komponente, auf die im XML verwiesen wird.

Warum dieses Framework - und nicht eine eigene Lösung?

Man könnte theoretisch jeden Admin-Bildschirm mit einem klassischen Block plus eigenem Template und eigenem Controller bauen. Der Grund, warum UI Components sich trotzdem lohnt: Filter, Sortierung, Paginierung, Massenaktionen, Bestätigungsdialoge, Inline-Validierung und Export sind bereits fertig implementiert und getestet - man deklariert sie nur, statt sie neu zu schreiben. Der Preis dafür ist eine gewisse Einarbeitungszeit in die XML-Struktur und die PHP-Basisklassen, die dieses Tutorial systematisch abbaut.

Ehrlicher Blick: ViewModels vs. UI-Components-Klassen

Die Coding-Konventionen dieses Projekts bevorzugen ViewModels (ArgumentInterface) gegenüber klassischen Block-Klassen, weil ViewModels reine Datenversorgung sauber von Darstellungslogik trennen. Für UI Components gilt das nur eingeschränkt: DataProvider-, Column-, Modifier- und Button-Klassen müssen jeweils eine feste Magento-Basisklasse bzw. ein festes Interface implementieren (AbstractDataProvider, Column, ModifierInterface, ButtonProviderInterface), weil das UI-Components-Framework sie über genau diese Verträge aufruft. Ein ArgumentInterface-ViewModel passt hier architektonisch nicht - das Framework erzwingt seine eigenen Konventionen. Wo immer eine dieser Klassen zusätzliche, wiederverwendbare Geschäftslogik braucht, wird diese Logik in dieser Serie trotzdem in ein separates, injizierbares Service-Objekt ausgelagert - die UI-Components-Klasse selbst bleibt ein dünner Adapter zum Framework.

Was in dieser Serie entsteht

Die ersten drei Blöcke bauen Grid- und Formular-Grundlagen an einem einfachen Übungsmodul auf (Mironsoft\Announcement, Ankündigungen). Ab Block 4 entsteht ein vollständiges, eigenständiges Admin-Modul für Kundenstimmen (Mironsoft\Testimonial) - mit eigener Datenbanktabelle, Grid, Formular mit Bild-Upload, Delete-Controller und Store-View-Sichtbarkeit. Block 5 erweitert genau dieses Modul um fortgeschrittene Techniken, Block 6 rundet mit ACL-Details, Troubleshooting und einem Spickzettel ab.