Version:

Vaadin Flow ​

Das Mate Design System stellt eine Flow-Komponentenbibliothek bereit, die vollständig in Java-basierte Vaadin-Flow-Projekte integriert werden kann. Die Komponenten folgen den Designprinzipien des Mate Design Systems und sind so konzipiert, dass sie konsistent, zugänglich und wiederverwendbar sind – direkt aus Java heraus nutzbar, ohne Frontend-Kenntnisse vorauszusetzen.

Voraussetzungen ​

Bevor du mit der Integration beginnst, stelle sicher, dass folgende Voraussetzungen erfüllt sind:

  • Java 17 oder höher für Mate 24 und Java 21 oder höher für Mate 25
  • Maven oder Gradle als Build-System
  • Zugang zum AKDB GitLab (exklusiv für Mitglieder des AKDB-Verbunds)
  • Ein bestehendes Vaadin-Flow-Projekt oder die Bereitschaft, eines anzulegen
  • Konfiguration des internen Maven-Repositorys (Nexus/Artifactory)

Falls du noch keinen Zugang zum GitLab oder Maven-Repository hast, wende dich an das Mate-Team oder tritt der Usergroup bei (Einladung via Giesbrecht.Tim@akdb.de).

Installation ​

Konfiguriere zunächst den Zugang zum internen Maven-Repository. Füge die Repository-Konfiguration in deine pom.xml oder settings.xml ein. Wie das genau funktioniert, erfährst du in Installation im Flow-Beispiel.

Füge anschließend die Mate-Abhängigkeit in deine pom.xml ein:

xml
<dependency>
    <groupId>ds.mate_ds</groupId>
    <artifactId>mate-flex-layout-flow</artifactId>
    <version>25.0.0</version>
</dependency>

Erste Schritte ​

Nach der Installation werden die Komponenten automatisch von Vaadin registriert – ein explizites Einbinden der Web Components oder CSS-Dateien ist nicht notwendig, da Flow das vollständig übernimmt. Das zugehörige Stylesheet wird beim ersten Start der Anwendung automatisch geladen. Weitere Hinweise zur Theme-Einbindung findest du in Theme.

Anschließend kannst du Mate-Komponenten direkt in deinen Views verwenden:

java
import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.textfield.TextField;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import de.mate_ds.flow.component.formlayout.FormLayout;
import com.vaadin.flow.router.Route;

@Route("login")
public class LoginView extends VerticalLayout {

    public LoginView() {
        FormLayout form = new FormLayout();

        TextField username = new TextField("Benutzername");
        TextField password = new TextField("Passwort");
        password.setType("password");

        Button loginButton = new Button("Anmelden");
        loginButton.setVariant("primary");

        form.add(username, password, loginButton);
        add(form);
    }
}

Internationalization (i18n) ​

Um die Barrierefreiheit gewährleisten zu können, sollte überall, wo möglich das i18n Property gesetzt werden. Im Flow sind standardmäßig Deutsche Texte voreingestellt.

Das war es im Wesentlichen. Vaadin übernimmt die Kommunikation zwischen Java und den Web Components im Browser – du arbeitest vollständig auf der Serverseite.

Arbeiten mit dem Design System ​

Die Flow-Komponenten des Mate Design Systems sind Java-Wrapper um die zugrundeliegenden Web Components. Vaadin überträgt Property-Änderungen und Events automatisch zwischen Server und Client. Du interagierst ausschließlich mit der Java-API, ohne direkten Zugriff auf das DOM.

Events und Listener ​

Events werden in Flow als server-seitige Listener registriert. Mate-Komponenten folgen dabei dem Vaadin-üblichen Muster mit addValueChangeListener oder komponentenspezifischen Methoden:

java
TextField searchField = new TextField("Suche");
searchField.addValueChangeListener(event -> {
    String query = event.getValue();
    // Suche ausführen
    performSearch(query);
});

Für Klick-Events auf Buttons:

java
Button saveButton = new Button("Speichern");
saveButton.addClickListener(event -> {
    saveData();
    Notification.show("Gespeichert");
});

Formulare und Binder ​

Das Mate Design System lässt sich nahtlos mit Vaadins Binder-API kombinieren. So kannst du Validierungen und Datenbindung direkt auf Mate-Eingabefelder anwenden:

java
Binder<Person> binder = new Binder<>(Person.class);

TextField firstNameField = new TextField("Vorname");
binder.forField(firstNameField)
    .asRequired("Pflichtfeld")
    .bind(Person::getFirstName, Person::setFirstName);

TextField lastNameField = new TextField("Nachname");
binder.forField(lastNameField)
    .bind(Person::getLastName, Person::setLastName);

Zugänglichkeit ​

Die Komponenten des Mate Design Systems bringen eine solide Basis für barrierefreie Anwendungen mit: ARIA-Rollen, Tastaturnavigation und Screenreader-Unterstützung sind in die Web Components eingebaut und wirken auch im Flow-Kontext. Das bedeutet aber nicht, dass eine Anwendung automatisch barrierefrei ist – das hängt entscheidend davon ab, wie die Komponenten verwendet werden.

Konkret: Ein Button ohne lesbaren Text, ein Eingabefeld ohne Label oder eine Pflichtangabe, die nicht als solche markiert ist, sind auch mit Mate-Komponenten nicht zugänglich. Nutze die Java-API konsequent – also setLabel(), setRequired(), setErrorMessage() und ähnliche Methoden – und befülle sie mit aussagekräftigen Inhalten.

Darüber hinaus gibt es Aspekte der Barrierefreiheit, die grundsätzlich kontextabhängig sind und nicht von einer Komponentenbibliothek gelöst werden können: Fokus-Management nach Navigation, Live-Regionen für dynamisch aktualisierte Inhalte oder die Reihenfolge von Überschriften im Seitenaufbau. Diese liegen in der Verantwortung der Anwendungsentwicklung – ergänzende Hinweise dazu finden sich in der Vaadin-Dokumentation zu Accessibility.

Best Practices ​

Komponentengrenzen respektieren. Versuche nicht, über getElement() oder JavaScript-Execution direkt in die Web Component einzugreifen, solange es einen offiziellen Java-API-Weg gibt. Direkte DOM-Manipulation umgeht die Abstraktionsschicht von Vaadin und kann zu unvorhersehbarem Verhalten führen.

Konsistenz durch das Design System sicherstellen. Verwende ausschließlich Mate-Komponenten für UI-Elemente, die im Design System definiert sind. Eigenentwicklungen für Buttons, Eingabefelder oder Dialoge führen zu Inkonsistenzen und erhöhen den Wartungsaufwand.

Binder für Formulare nutzen. Vaadins Binder-API ist die empfohlene Methode zur Datenbindung und Validierung. Sie arbeitet gut mit Mate-Komponenten zusammen und hält den Code wartbar.

Updates im Blick behalten. Das Design System entwickelt sich weiter. Halte Ausschau nach Changelog-Einträgen, wenn du die Abhängigkeit aktualisierst – Breaking Changes werden dort kommuniziert.

Troubleshooting ​

Komponenten werden unstyled dargestellt. Überprüfe, ob die Abhängigkeit korrekt aufgelöst wurde und das Maven-Repository erreichbar ist. Führe mvn dependency:resolve aus, um zu prüfen, ob die Artefakte heruntergeladen werden können.

Klassen werden nicht gefunden. Stelle sicher, dass die korrekte Version der Abhängigkeit eingetragen ist und dass das Projekt nach dem Hinzufügen neu gebaut wurde. Gelegentlich hilft ein mvn clean install, um den Build-Cache zu leeren.

Vaadin meldet Komponentenfehler beim Start. Prüfe, ob die Vaadin-Version deines Projekts mit der Mate-Version kompatibel ist. In der Komponentendokumentation oder im Changelog ist die unterstützte Vaadin-Version angegeben.

Formulare validieren nicht korrekt. Wenn Binder-Validierungen nicht ausgelöst werden, stelle sicher, dass du binder.validate() oder binder.writeBeanIfValid() explizit aufrufst und dass die Felder korrekt registriert sind.

Das Artefakt wird nicht gefunden. Überprüfe deine Maven-Repository-Konfiguration in settings.xml und stelle sicher, dass die Credentials aktuell sind. Bei Zugangsproblemen wende dich an das Mate-Team.

Weitere Informationen ​