Form Layout

Das Form Layout fasst die Eingabefelder einer fachlich zusammengehörenden Feldergruppe zusammen und richtet sie in einem einheitlichen Raster aus.

Overview

Nicht das Vaadin Form Layout verwenden

Für den Mate-Formularaufbau wird weder <vaadin-form-layout> noch Vaadins FormLayout aus com.vaadin.flow.component.formlayout verwendet. Die dort verfügbaren Spaltenmodi (Responsive Steps, Auto Responsive) sind keine Mate-Regel und dürfen nicht als solche angewendet werden.

Vorgesehen ist die Mate-Lösung: <div theme="form-layout"> innerhalb von <mate-form>. In Vaadin Flow stammt die Klasse FormLayout entsprechend aus de.mate_ds.flow.component.flexlayout und nicht aus com.vaadin.flow.component.formlayout.

Intro

Das Form Layout dient dazu ein einheitliches Aussehen aller Formulare sicherzustellen und die Bedienbarkeit der Formulare zu erleichtern. Die beschriebenen Regeln zum Form Layout gelten sowohl für ein einzelnes Formular, als auch für eine Formularseite.

Ein Form Layout entspricht dabei genau einer Feldergruppe, also einem fachlichen Abschnitt eines Formulars wie Person, Adresse oder Bankverbindung. Ein Formular besteht je nach Umfang aus einer oder aus mehreren solchen Feldergruppen.

Einordnung

Das Form Layout ist nur ein Baustein des Formularaufbaus. Die folgende Abgrenzung legt fest, welcher Baustein wofür zuständig ist:

Baustein	Aufgabe
Form	Das gesamte Formular. Übergreifender Container für formularweite Zustände wie Validierung und die Fehlerliste am Anfang des Formulars. Eine Form kann mehrere Form Layouts enthalten.
Form Layout	Eine Feldergruppe innerhalb der Form. Ordnet die Eingabeelemente dieser Gruppe an und sorgt für einheitliche Ausrichtung und Abstände.
Block Layout	Ordnet mehrere Form Layouts - und bei Bedarf einen Callout - nebeneinander an. Es strukturiert nicht die einzelnen Eingabefelder.
Callout	Hervorgehobener Informationsbereich, der neben den Formularspalten stehen kann. Er ist eine Kontextspalte und zählt nicht als weitere Formularspalte.

Daraus ergeben sich zwei übliche Aufbauten. Ein einspaltiges Formular enthält seine Form Layouts direkt: Form → Form Layout "Person", Form Layout "Adresse"; für sichtbare Abstände zwischen den Feldergruppen liegt dabei ein vertikal stapelndes Layout dazwischen (siehe Abstände ). Sollen mehrere Feldergruppen nebeneinander stehen, kommt ein Block Layout dazu: Form → Block Layout → Form Layout "Person", Form Layout "Adresse", Callout "Hinweis". Das Block Layout ist also kein Pflichtbestandteil, sondern der Baustein für die Anordnung nebeneinander.

Ein Block Layout trägt höchstens drei Bereiche

Das Block Layout blendet überzählige Kind-Elemente still über display: none aus: in der Standardkonfiguration mit drei gleich breiten Blöcken ab dem vierten Kind, in den Konfigurationen layout-6-6, layout-8-4 und layout-4-8 bereits ab dem dritten Kind, bei layout-12 ab dem zweiten Kind. Es gibt dafür keine Fehlermeldung, die betroffene Feldergruppe fehlt einfach in der Darstellung.

Mehr als drei Bereiche, also mehr als drei Feldergruppen beziehungsweise zwei Feldergruppen und ein Callout, passen deshalb nicht in ein einzelnes Block Layout. Ein Formular mit vier, fünf oder sechs Feldergruppen benötigt mehrere Block Layouts untereinander, die jeweils die Bereiche einer Zeile aufnehmen. Die Konfigurationen und ihre Grenzen sind auf der Seite Block Layout beschrieben.

Verwendung

👍 Do

👎 Don't

...wenn die Eingabeelemente einer fachlich zusammengehörenden Feldergruppe einheitlich ausgerichtet werden sollen. ...wenn innerhalb einer Formularspalte maximal zwei Eingabeelemente nebeneinander stehen sollen. ...wenn ein Formular aus mehreren Abschnitten besteht: je Abschnitt ein eigenes Form Layout.

...wenn mehrere Feldergruppen oder eine Feldergruppe und ein Callout nebeneinander angeordnet werden sollen. Nutze hierfür das Block Layout. ...wenn formularweite Zustände wie Validierung oder eine Fehlerliste am Anfang des Formulars benötigt werden. Nutze hierfür die Form. ...wenn ein dreispaltiger Eingabebereich entstehen würde. Mehr als zwei Formularspalten sind nicht zulässig. ...wenn beliebige Inhalte lediglich in einer Zeile angeordnet werden sollen. Nutze hierfür das Horizontal Layout oder das Flex Layout. ...wenn das Vaadin Form Layout verwendet werden soll. Es ist für den Mate-Formularaufbau nicht vorgesehen.

Guidelines

Aufbau

Das Layout passt sich an die Breite des zur Verfügung stehenden Platzes an. Der verfügbare Platz beziehungsweise Container kann die Größen S, M oder L haben. Die Anzahl der Layout-Spalten ist abhängig von der Containergröße. Die Layout-Spalten dienen als Hilfestellung bei der Darstellung und sind nicht mit den Formular-Spalten gleichzusetzen! Eine Formularspalte nimmt mehrere Layout-Spalten in Anspruch.

Die hier beschriebenen Layout-Spalten (2, 4 oder 6 je Containergröße) gehören zum Formularraster und sind nicht mit dem allgemeinen Spaltenraster aus Grid & Spacing zu verwechseln, das mit 4, 8 beziehungsweise 12 Spalten arbeitet und vom Block Layout aufgespannt wird. Das Spaltenraster ordnet ganze Inhaltsbereiche, das Formularraster die Felder innerhalb einer Feldergruppe. Die Containergrößen S, M und L bezeichnen in beiden Rastern dieselben Breitenbereiche.

Als Maßstab für die Größe wird immer nur die Breite des Bereiches, beziehungsweise des Containers, in dem das Formular dargestellt werden soll, gezählt, alle anderen Bereiche (z.B. aufgeklapptes Menü, Sidebar, o.ä.) werden außer Acht gelassen.

Folge Grafik zeigt eine Übersicht über die möglichen Layout-Größen:

broken_image

Figma

Die 3 Layout-Größen L, M und S

Der verfügbare Platz wird gleichmäßig auf die Anzahl der Layout-Spalten aufgeteilt. Der Raum zwischen den Layout-Spalten beträgt bei allen Layout-Größen 48 Pixel.

Diese 48 Pixel sind der Abstand zwischen zwei Feldergruppen, die nebeneinander stehen – nicht der Abstand zwischen zwei Eingabefeldern innerhalb einer Feldergruppe. Formulare haben damit zwei Abstandsebenen, die nicht zu verwechseln sind:

Ebene	Abstand	Wodurch
Zwischen zwei Feldergruppen, die nebeneinander oder untereinander stehen	48 px	Das Block Layout , das die Feldergruppen im Spaltenraster anordnet
Zwischen zwei Eingabefeldern innerhalb einer Feldergruppe	16 px (Desktop), 20 px (Mobile) aus --mate-spacing-margin	Das Form Layout mit dem Theme-Namen spacing (siehe Abstände )

Ein Beispiel: Die Feldergruppe Person enthält Vorname und Nachname in einer Zeile, zwischen diesen beiden Feldern liegen 16 Pixel. Rechts daneben steht die Feldergruppe Personalverwaltung mit Personalnummer und Büro in einer Zeile, ebenfalls mit 16 Pixeln zwischen den beiden Feldern. Zwischen den Feldergruppen Person und Personalverwaltung liegen dagegen 48 Pixel.

Umsetzung im Block Layout weicht noch ab

Verbindlich sind 48 Pixel zwischen zwei Feldergruppen. Das implementierte Block Layout setzt zwischen seinen Blöcken derzeit noch --mate-spacing-margin, also 16 px auf dem Desktop und 20 px auf mobilen Geräten – denselben Wert, den das Form Layout innerhalb einer Feldergruppe verwendet. Die Anpassung ist entschieden und wird nachgezogen.

Bis dahin gilt: Für das Designlayout in Figma sind die 48 Pixel maßgeblich. Wo die Trennung der Feldergruppen in der Umsetzung schon jetzt sichtbar sein muss, ist der Abstand in der Anwendung zu ergänzen.

broken_image

Figma

Unterschied zwischen Layout-Spalten und Formularspalten

Spaltenbelegung einzelner Felder

Ein Form Layout füllt genau eine Formularspalte aus und unterteilt sie technisch in vier gleich breite Rasterspalten. Diese vier Rasterspalten sind eine feinere Unterteilung der Formularspalte und nicht mit den Layout-Spalten aus dem Abschnitt Aufbau zu verwechseln.

Jedes Kind-Element belegt standardmäßig zwei der vier Rasterspalten. Dadurch stehen zwei Eingabeelemente nebeneinander. Über die Attribute lässt sich die Belegung einzelner Felder gezielt ändern:

Element bzw. Attribut	Belegte Rasterspalten	Wirkung
Standard, ohne Attribut	2 von 4	Zwei Eingabeelemente stehen nebeneinander.
Überschriften h1 bis h6	4 von 4	Titel der Feldergruppe über die volle Breite.
cols="4"	4 von 4	Element über die volle Breite der Formularspalte.
colspan="2"	4 von 4	Gleichbedeutend mit cols="4".
cols="3"	3 von 4	Breiterer Teil einer 3:1-Aufteilung, zum Beispiel Straße.
cols="1"	1 von 4	Schmalerer Teil einer 3:1-Aufteilung, zum Beispiel Hausnummer.

Eine Textarea nimmt immer die volle Breite der Formularspalte ein und erhält deshalb cols="4".

Info für Dev

Ein Eingabeelement ohne Attribut belegt auch dann nur die halbe Breite, wenn es allein in seiner Zeile steht. Damit die Regel "ein einzelnes Eingabeelement füllt die gesamte Formularspalte" eingehalten wird, muss an diesem Element cols="4" gesetzt werden.

Die Attribute werden von der Theme-CSS direkt am Kind-Element des Form Layouts ausgewertet. Es ist kein zusätzliches Wrapper-Element nötig. Sie wirken nur an direkten Kindern des Form Layouts, nicht an tiefer verschachtelten Elementen.

Abstände

Die folgenden Angaben beschreiben die Abstände, die das implementierte Form Layout innerhalb einer Feldergruppe erzeugt. Sie sind nicht mit den 48 Pixeln zwischen zwei Feldergruppen aus dem Abschnitt Aufbau zu verwechseln.

Beide Einstellungen sind Opt-in und werden als zusätzliche Theme-Namen im selben theme-Attribut wie form-layout gesetzt, also zum Beispiel theme="form-layout spacing" oder theme="form-layout spacing padding". Ohne diese Namen erzeugt das Form Layout weder Abstände zwischen den Feldern noch einen Innenabstand.

Theme-Name	Token	Wert
spacing	--mate-spacing-margin	16 px Desktop, 20 px Mobile
padding	--mate-spacing-padding	16 px Desktop, 20 px Mobile

Mit spacing erhält das Form Layout einen einheitlichen Abstand zwischen den Feldern. Der Wert gilt sowohl waagrecht, also zwischen zwei nebeneinander stehenden Eingabeelementen, als auch senkrecht, also als Abstand unter den Feldern innerhalb der Feldergruppe. Mit padding erhält das Form Layout zusätzlich einen umlaufenden Innenabstand.

Ein Form Layout erzeugt selbst keinen Außenabstand. Auch die Form bringt keinen Abstand mit: Die Theme-CSS enthält für mate-form, ::part(top) und ::part(form-content) keine Regel für gap, row-gap oder margin. Zwei Form Layouts direkt untereinander in einer Form stehen deshalb ohne Abstand aneinander. Der Abstand zwischen mehreren Feldergruppen und zwischen Feldergruppe und Callout entsteht immer über das umgebende Layout:

Aufbau	Umgebendes Layout	Abstand
Einspaltig, mehrere Feldergruppen untereinander	<vaadin-vertical-layout theme="spacing"> um die Feldergruppen	16 px Desktop, 20 px Mobile (--mate-spacing-margin)
Mehrspaltig, die Feldergruppen stehen nebeneinander	Block Layout mit theme="spacing"	16 px Desktop, 20 px Mobile (--mate-spacing-margin)

Dasselbe gilt eine Ebene höher: Auch das Block Layout erzeugt keinen Außenabstand, sodass mehrere Block Layouts untereinander ebenfalls ohne Abstand aneinander stehen und über dasselbe umgebende Vertical Layout gestapelt werden.

Für das einspaltige Stapeln ist das Block Layout in der Konfiguration layout-12 nicht geeignet: Diese Konfiguration zeigt nur das erste Kind-Element an und blendet alle weiteren aus. Mehrere Feldergruppen untereinander werden deshalb über ein <vaadin-vertical-layout theme="spacing"> aus @vaadin/vertical-layout gestapelt. Die Grundlagen zu Rastern und Abständen sind unter Grid & Spacing beschrieben.

Layout Regeln

Die folgenden Regeln sind Design-Vorgaben des Mate Design Systems. Das Form Layout erzwingt sie technisch nicht: Es verteilt die Kind-Elemente lediglich auf sein Vier-Spalten-Raster. Ob ein Formular höchstens zwei Formularspalten nutzt, ob eine Feldergruppe die Formularspalte ausfüllt und ob die Kontextspalte frei von Eingabeelementen bleibt, liegt in der Verantwortung der Anwendung.

Allgemeingültige Regeln

Folgende Regeln sind verbindlich und unabhängig von der Layout-Größe gültig:

• Eine Feldergruppe nimmt immer die gesamte Breite der Formularspalte ein.
• In einer Formularspalte können sich maximal 2 Eingabe-Elemente (z.B. Eingabefeld, Dropdown, Combobox) nebeneinander befinden.
• Wenn ein Eingabe-Element allein in einer Formularspalte ist, füllt dieses immer die gesamte Breite der Formularspalte aus.
• Eine Textarea nimmt jedoch immer die gesamte Breite der Formularspalte ein. Es können nicht zwei Textareas in einer Spalte nebeneinander stehen.

Tab-Reihenfolge bei mehreren Feldergruppen

Die Tab-Reihenfolge folgt der Reihenfolge im Markup, also der Reihenfolge der Feldergruppen: Zuerst werden alle Felder der ersten Feldergruppe durchlaufen, dann die der zweiten und so weiter. Innerhalb einer Feldergruppe läuft die Reihenfolge zeilenweise von links nach rechts und anschließend nach unten, nicht spaltenweise von oben nach unten.

Bei zwei Formularspalten entspricht diese Reihenfolge nicht durchgehend dem visuellen Verlauf von oben nach unten. Beginnt die nächste Feldergruppe wieder in der linken Formularspalte, springt der Fokus aus der rechten Spalte zurück nach links. Im folgenden Bild ist das an der Nummerierung ablesbar: Die Felder 1 bis 8 liegen in der linken Formularspalte (Feldergruppe "Kundendetails"), die Felder 9 bis 12 in der rechten Formularspalte (Feldergruppe "Rechnungsdetails") und die Felder 13 bis 15 wieder in der linken Formularspalte (Feldergruppe "Zahlungsinformationen").

broken_image

Figma

Reihenfolge über drei Feldergruppen in zwei Formularspalten: 1 bis 8 links, 9 bis 12 rechts, 13 bis 15 wieder links

Die Reihenfolge der Feldergruppen im Markup ist deshalb eine fachliche Entscheidung: Sie legt fest, in welcher Reihenfolge die Feldergruppen mit der Tastatur ausgefüllt werden.

Allgemeine Empfehlungen

Folgende Empfehlungen sind nicht verbindlich, tragen jedoch zur besseren Bedienbarkeit des Formulars bei:

Wenn mehrere Eingabefelder zu einem bestimmten Thema (Z.B. Anschrift, Bezahldaten) vorliegen, sollten diese als Feldergruppe deklariert werden.

Die Feldergruppe, die mehr Zeilen hat, sollte in der linken Formularspalte platziert werden (wenn dies fachlich und inhaltlich sinnvoll und möglich ist).

Text-Eingabefelder sollten die ganze Breite der Formularspalte einnehmen (wenn dies inhaltlich sinnvoll ist).

Info für Dev

Mehrfachauswahlen-Gruppen (Checkbox Group) oder Alternativauswahl (Radio Button Group) können je nach Anzahl und Länge der Optionen horizontal oder vertikal angeordnet werden.

Es wird empfohlen diese Gruppen nicht neben weiteren Eingabefeldern dazustellen, sondern die gesamte Breite der Formularspalte dafür vorzusehen. Technisch wird die Gruppe dazu als ein Kind-Element in das Form Layout eingehängt und erhält cols="4".

Regeln für Layout-Größe S

Bei Layout-Größe S gibt es zwei Layout-Spalten. Da eine Formularspalte zwei Layout-Spalten einnimmt, gibt es nur eine Formularspalte. Wenn zwei Eingabe-Elemente nebeneinander platziert werden, nimmt jedes der Elemente eine Layout-Spalte ein.

Regeln für Layout-Größe M

Bei Layout-Größe M gibt es vier Layout-Spalten. Da eine Formularspalte zwei Layout-Spalten einnimmt, gibt es zwei Formularspalten. Wenn zwei Eingabe-Elemente nebeneinander platziert werden, nimmt jedes der Elemente eine Layout-Spalte ein.

Regeln für Layout-Größe L

Bei Layout-Größe L gibt es sechs Layout-Spalten. Eine Formularspalte nimmt zwei Layout-Spalten ein. Dies ermöglicht es, dass das Formular zweispaltig werden kann. Die zwei rechten Layout-Spalten bleiben immer frei von Eingabeelementen, sodass kein dreispaltiges Formular möglich ist. Sie können jedoch als Kontextspalte genutzt werden, etwa für einen Callout (siehe Erweiterte Hilfestellungen und Kontextinformationen ). Diese Kontextspalte gehört nicht zum Formularraster und zählt nicht als dritte Formularspalte. Ein Formular kann nur dann zweispaltig werden, wenn es aus mehreren Feldergruppen besteht. Die Feldergruppen werden dann nacheinander in die Formularspalten aufgeteilt. Das heißt die erste Feldergruppe ist in Spalte 1, die zweite Feldergruppe in Spalte 2, die dritte Feldergruppe in Spalte 1, die vierte Feldergruppe in Spalte 2, usw. Diese Aufteilung ist in nachfolgender Grafik veranschaulicht.

broken_image

Figma

Korrekte Aufteilung der Feldergruppen der Layout-Größen L, M und S

Wenn es fachlich, inhaltlich und visuell Sinn macht, kann die zweite Formularspalte neben einer Feldergruppe ausnahmsweise leer gelassen werden. Bei der Aufteilung der Feldergruppen wird die zweite Formularspalte an dieser Stelle sozusagen übersprungen. Folgende Grafik veranschaulicht die Aufteilung. Im folgendem Beispiel würde dies Sinn machen, wenn Feldergruppen 2 und 3, sowie Feldergruppen 4 und 5 inhaltlich zusammengehören.

broken_image

Figma

Darstellung: Mögliche korrekte Aufteilung der Feldergruppen bei Wechsel zwischen Layout-Größe L,M zu S asymmetrisch

Die erste Formularspalte darf nie leer gelassen oder übersprungen werden!

Regeln für mehrere Formulare auf einer Seite

Wenn sich mehrere Formulare auf einer Seite befinden, werden die Layout Regeln auf jedes Formular einzeln angewandt, während die Formulare immer untereinander dargestellt werden. Der Inhalt der zweiten Formularspalte muss also immer zum gleichen Formular gehören, wie der nebenstehende Inhalt der ersten Formularspalte.

broken_image

Figma

Korrekte Aufteilung der Feldergruppen bei mehreren Formularen auf einer Seite

Beispiele

Gegenüberstellung von Negativ- und Positiv-Beispielen

Folgende Beispiele zeigen Formulare, bei denen die Layoutregeln falsch oder gar nicht angewendet wurden, und jeweils die korrekte Anwendung der Regeln daneben.

broken_image Figma	Einzelnes Eingabe-Element in einer Formularspalte Ein Eingabe-Element muss immer die gesamte Formularspalte einnehmen und nicht, so wie hier links, alleine in einer Zeile stehen ohne die gesamte Breite zu nutzen.
broken_image Figma	Einzelne Feldergruppe bei zwei Formularspalten Eine einzelne Feldergruppe füllt immer nur eine Formularspalte aus, auch wenn die Layout-Größe zwei Formularspalten ermöglicht.
broken_image Figma	Größe von Formularspalten Die Formularspalten müssen immer die festgelegte Breite einhalten. Die zweite Formularspalte darf nicht breiter sein als die erste. Jede Formularspalte sollte, in der dargestellten Layout-Größe L, zwei Layout-Spalten einnehmen.
broken_image Figma	Eingabe-Elemente müssen sich an das Spalten-Layout halten Die Eingabe-Elemente müssen sich an das vorgegebene Spalten-Layout halten. Ein Eingabe-Element darf nicht über mehrere Formularspalten gehen.
broken_image Figma	Feldergruppen dürfen nie mehr als 2 Spalten nutzen

Anwendungsbeispiele

1-Spaltiges und 2-Spaltiges Layout

Nachfolgende Beispiele zeigen, wie man die Layout Regeln mit verschiedenen Arten von Eingabefeldern konkret in der Praxis anwenden kann. Die Entscheidung ob für ein Formular nur eine Spalte verwendet werden soll, oder ob zwei Spalten nebeneinander platziert werden sollten, obliegt dem Designer und hängt vom Anwendungsfall ab.

broken_image

Figma

Anwendungsbeispiele Formulare

Erweiterte Hilfestellungen und Kontextinformationen

Hilfe-Text

Siehe Hilfestellung in Formularen für weitere Informationen.

Regulärer Text Absatz

Es ist jederzeit möglich einfache Absätze in Formular-basierten Dialogen einzuführen um die Nutzer beim Ausfüllen zu unterstützen.

Tooltip

Einzelne Eingabefelder können durch Tooltips mit ergänzenden Erläuterungen etc. versehen werden.

Callouts

Um Erläuterungen oder Kontext-Informationen noch stärker hervorzuheben, können diese in einem Callout dargestellt werden. Ein Callout kann an zwei Stellen stehen: innerhalb einer Feldergruppe, dann nimmt er dort die volle Breite der Formularspalte ein, oder rechts neben den Formularspalten in einer eigenen Kontextspalte.

Die Kontextspalte ist keine Formularspalte und nicht Teil des Formularrasters. Sie belegt bei Layout-Größe L genau die beiden Layout-Spalten, die laut Abschnitt Regeln für Layout-Größe L frei von Eingabeelementen bleiben. Technisch entsteht sie als weiterer Block des umgebenden Block Layouts , nicht als weitere Spalte innerhalb eines Form Layouts. Solange dort ausschließlich erläuternde Inhalte stehen, bleibt das Formular zweispaltig. Sobald dort Eingabeelemente des Formulars platziert werden, entsteht ein dreispaltiges Formular, das nach den Mate-Regeln nicht zulässig ist.

broken_image

Figma

Form Layout mit Hilfestellungen und Kontextinformationen

Barrierefreiheit

Das Form Layout selbst ist kein semantischer Bereich. Die zugängliche Struktur eines Formulars entsteht über die enthaltenen Überschriften, Beschriftungen und Formularelemente.

Jede Feldergruppe erhält eine sichtbare Überschrift, die über h1 bis h6 ausgezeichnet wird und im Form Layout die volle Breite einnimmt. Die Überschriftenebene muss zur Überschriftenhierarchie der Seite passen; Ebenen dürfen nicht übersprungen werden. Dadurch können Screenreader-Nutzende die Feldergruppen gezielt ansteuern.

Jedes Eingabeelement benötigt eine dauerhaft sichtbare Beschriftung, die programmatisch mit dem Feld verknüpft ist. Ein Platzhaltertext ersetzt keine Beschriftung. Zusammengehörende Felder, die gemeinsam ein Datum ergeben, zum Beispiel Straße und Hausnummer, behalten jeweils ihre eigene Beschriftung.

Zusammengehörende Auswahlmöglichkeiten benötigen zusätzlich eine Gruppensemantik. Eine Mehrfachauswahl (Checkbox Group) und eine Alternativauswahl (Radio Button Group) werden als Gruppe ausgezeichnet und erhalten eine eigene Gruppenbeschriftung, damit Screenreader beim Betreten der Gruppe deren Zweck ansagen und die Zugehörigkeit der einzelnen Optionen erkennbar bleibt. Die Gruppenkomponenten bringen diese Semantik selbst mit; das Form Layout ordnet die Gruppe nur an. Eine solche Gruppe wird als ein Kind-Element in das Form Layout eingehängt und sollte nach der Empfehlung im Abschnitt Allgemeine Empfehlungen die volle Breite der Formularspalte erhalten.

Pflichtfelder werden dauerhaft sichtbar gekennzeichnet und die Kennzeichnung muss auch programmatisch verfügbar sein, damit sie von Screenreadern angesagt wird. Eine rein visuelle Kennzeichnung, zum Beispiel nur über Farbe oder nur über ein Sternchen im Beschriftungstext, reicht nicht aus. Die Bedeutung der Kennzeichnung wird einmal pro Formular in Textform erläutert.

Die Fokusreihenfolge folgt der Reihenfolge im Markup, also der Reihenfolge der Feldergruppen, und innerhalb einer Feldergruppe zeilenweise von links nach rechts. Bei zwei Formularspalten weicht sie damit vom visuellen Verlauf von oben nach unten ab: Der Fokus kann aus der rechten Formularspalte zurück in die linke springen, wenn dort die nächste Feldergruppe beginnt. Der Abschnitt Tab-Reihenfolge bei mehreren Feldergruppen zeigt das an einem Beispiel. Die Reihenfolge wird ausschließlich über die Reihenfolge im Markup gesteuert; eine abweichende Reihenfolge über positive Werte von tabindex ist nicht vorgesehen.

Feldbezogene Fehlermeldungen stehen direkt am jeweiligen Eingabeelement, damit sie beim Fokussieren des Feldes vorgelesen werden. Formularweite Fehler werden nicht im Form Layout, sondern in der Form am Anfang des Formulars ausgegeben.

Develop Web Components

Installation, Import und die Grundvarianten des Form Layouts stehen in den Beispielen am Ende dieser Seite. Das Layout selbst kommt aus @mate/theme und benötigt keinen eigenen Import; verwendet wird ein Div mit dem Theme-Namen form-layout.

Das folgende Beispiel geht über die Grundvarianten hinaus und zeigt den vollständigen Aufbau einer zweispaltigen Formularseite: die Form als äußerer Container, das Block Layout für die Anordnung nebeneinander, je Feldergruppe ein Form Layout und einen Callout als Kontextspalte.

Das Beispiel setzt neben dem Theme weitere Pakete voraus; die letzte Zeile betrifft den einspaltigen Aufbau aus dem Abschnitt Abstände und wird im Beispiel selbst nicht verwendet:

Paket	Wofür	Import
@mate/theme	theme="block-layout", theme="form-layout", class="block-container"	kein eigener Import nötig
@mate/form	das Element mate-form	import '@mate/form';
@mate/callout	das Element mate-callout	import '@mate/callout';
@vaadin/text-field, @vaadin/date-picker	die Eingabeelemente des Beispiels	import '@vaadin/text-field'; usw.
@vaadin/vertical-layout	das Element vaadin-vertical-layout, das mehrere Feldergruppen einspaltig mit Abstand stapelt	import '@vaadin/vertical-layout';

<mate-form>
  <div class="block-container">
    <div theme="block-layout spacing">
      <div theme="form-layout spacing">
        <h5>Person</h5>
        <vaadin-text-field label="Vorname"></vaadin-text-field>
        <vaadin-text-field label="Nachname"></vaadin-text-field>
        <vaadin-text-field label="Personalnummer"></vaadin-text-field>
        <vaadin-date-picker label="Einstellungsdatum"></vaadin-date-picker>
      </div>
      <div theme="form-layout spacing">
        <h5>Adresse</h5>
        <vaadin-text-field label="Straße" cols="3"></vaadin-text-field>
        <vaadin-text-field label="Hausnummer" cols="1"></vaadin-text-field>
        <vaadin-text-field label="Postleitzahl"></vaadin-text-field>
        <vaadin-text-field label="Ort"></vaadin-text-field>
      </div>
      <mate-callout theme="info" title-text="Hinweis">
        Erfassen Sie hier die aktuellen Personal- und Adressdaten der Person.
      </mate-callout>
    </div>
  </div>
</mate-form>

Info für Dev

Das Block Layout wertet Container Queries aus. Es muss deshalb von einem Element mit der Klasse block-container umschlossen sein, denn nur diese Klasse setzt den benannten Container. Fehlt dieser Container, bleibt das Block Layout in der Konfiguration für kleine Container und die Feldergruppen stehen immer untereinander. Details siehe Block Layout.

Für das Form Layout selbst wird kein solcher Container benötigt: Es arbeitet mit einem festen Raster aus vier Spalten und ohne Container Query.

Zwei Schreibweisen im Umlauf

Die Doku-Seiten verwenden durchgängig <div theme="form-layout">. In den angehängten Beispielen der Seite Form steht dagegen <mate-form-layout>.

Die Theme-CSS erfasst beide Schreibweisen: Ihr Selektor spricht sowohl das Element mate-form-layout als auch ein Div mit dem Theme-Namen form-layout an. Ein registriertes Custom Element mate-form-layout existiert im Repository allerdings nicht; der Elementname wird ausschließlich von der CSS gestylt.

Zu verwenden ist deshalb die Div-Schreibweise. Die Vereinheitlichung der Beispieldateien ist ein offener Punkt.

Develop Vue

npm i @mate-vue/form-layout @mate-vue/text-field

import { MateFormLayout } from '@mate-vue/form-layout';
import { MateTextField } from '@mate-vue/text-field';

Das Form Layout heißt in Vue MateFormLayout. In Vue liegt jede Komponente in einem eigenen Paket, auch die Eingabeelemente: Je Feldtyp kommt das passende Paket dazu, zum Beispiel @mate-vue/date-picker für eine Datumsauswahl.

Die Attribute zur Spaltenbelegung einzelner Felder werden wie bei den Web Components am jeweiligen Kind-Element gesetzt:

<template>
  <MateFormLayout>
    <h5>Adresse</h5>
    <MateTextField label="Straße" cols="3"></MateTextField>
    <MateTextField label="Hausnummer" cols="1"></MateTextField>
    <MateTextField label="Postleitzahl"></MateTextField>
    <MateTextField label="Ort"></MateTextField>
  </MateFormLayout>
</template>

Spacing und Padding werden auch in Vue über das Attribut theme gesetzt, es nimmt dieselben Theme-Namen entgegen wie in Web Components. Angegeben wird dabei nur die zusätzliche Konfiguration, den Basisnamen des Layouts bringt der Wrapper selbst mit. Belegt ist das allerdings ausschließlich für MateBlockLayout: Dessen offizielle Vue-Beispiele in Version 25 schreiben theme="spacing" beziehungsweise theme="spacing layout-6-6" ohne den Basisnamen block-layout. Für MateFormLayout zeigen die offiziellen Vue-Beispiele dagegen überhaupt keine Verwendung von theme, sondern nur die Standardvariante. Dieselbe Einschränkung ist unter Flex Layout für MateFloatingLayout beschrieben.

Das folgende Beispiel überträgt die Schreibweise von MateBlockLayout deshalb lediglich analog auf MateFormLayout. Es ist im Projekt zu verifizieren, ob der Wrapper das Attribut theme durchreicht und den Basisnamen form-layout selbst ergänzt. Bis dahin ist offen, wie der Abstand zwischen den Feldern einer Feldergruppe in Vue gesetzt wird.

<template>
  <MateFormLayout theme="spacing">
    <h5>Person</h5>
    <MateTextField label="Vorname"></MateTextField>
    <MateTextField label="Nachname"></MateTextField>
  </MateFormLayout>
</template>

Mehrere Feldergruppen werden als mehrere MateFormLayout nacheinander geschrieben; das offizielle Beispiel "Multiple Sections" zeigt genau diesen Aufbau ohne umgebendes Element. Wie bei den Web Components erzeugt ein Form Layout dabei keinen Außenabstand: Die Feldergruppen stehen ohne Abstand untereinander (siehe Abstände ). Ein Wrapper eines Vertical Layouts ist für Vue nicht dokumentiert, die Komponentenliste der Version 25 enthält keinen solchen Eintrag. Der Abstand zwischen mehreren Feldergruppen untereinander muss deshalb aus dem umgebenden Layout der Anwendung kommen; welche Vue-Komponente das übernimmt, ist ein offener Punkt.

Sollen die Feldergruppen nebeneinander stehen, übernimmt das Block Layout die Anordnung und den Abstand. Es heißt in Vue MateBlockLayout und stammt aus @mate-vue/block-layout; für dieses Layout ist die Schreibweise ohne Basisnamen belegt:

npm i @mate-vue/block-layout

<script setup>
import { MateBlockLayout } from '@mate-vue/block-layout';
import { MateFormLayout } from '@mate-vue/form-layout';
import { MateTextField } from '@mate-vue/text-field';
</script>

<template>
  <MateBlockLayout theme="spacing layout-6-6">
    <MateFormLayout>
      <h5>Person</h5>
      <MateTextField label="Vorname"></MateTextField>
      <MateTextField label="Nachname"></MateTextField>
    </MateFormLayout>
    <MateFormLayout>
      <h5>Adresse</h5>
      <MateTextField label="Postleitzahl"></MateTextField>
      <MateTextField label="Ort"></MateTextField>
    </MateFormLayout>
  </MateBlockLayout>
</template>

Ob MateBlockLayout den benötigten Container selbst setzt, ist nicht dokumentiert; der offene Punkt dazu steht auf der Seite Block Layout .

Develop Flow

<dependency>
    <groupId>de.mate_ds</groupId>
    <artifactId>mate-flex-layout-flow</artifactId>
</dependency>

Richtige FormLayout-Klasse verwenden

Die Klasse FormLayout stammt aus de.mate_ds.flow.component.flexlayout und wird über das Artefakt de.mate_ds:mate-flex-layout-flow bereitgestellt.

Sie ist nicht identisch mit com.vaadin.flow.component.formlayout.FormLayout. Ein versehentlich importiertes Vaadin FormLayout erzeugt ein anderes Spaltenverhalten und entspricht nicht den Mate-Regeln.

import de.mate_ds.flow.component.flexlayout.FormLayout;

FormLayout person = new FormLayout();
person.setSpacing(true);
person.add(
    new H5("Person"),
    new TextField("Vorname"),
    new TextField("Nachname"));

FormLayout adresse = new FormLayout();
adresse.setSpacing(true);
adresse.add(
    new H5("Adresse"),
    new TextField("Postleitzahl"),
    new TextField("Ort"));

setSpacing(true) entspricht dem Theme-Namen spacing der Web Components und erzeugt denselben Abstand aus --mate-spacing-margin. Es wirkt jeweils nur innerhalb einer Feldergruppe: Werden person und adresse wie oben erzeugt und anschließend direkt nacheinander in die Form gehängt, stehen die beiden Feldergruppen ohne Abstand untereinander (siehe Abstände ). Den Abstand zwischen ihnen erzeugt erst das umgebende Layout.

Sollen die beiden Feldergruppen nebeneinander stehen, werden sie in ein Block Layout mit setSpacing(true) gelegt, das mit BlockLayout.createContainer in seinen Container gehängt wird (siehe Block Layout ); dieses Block Layout setzt dann auch den Abstand zwischen ihnen.

Beim einspaltigen Aufbau übernimmt diese Aufgabe das VerticalLayout aus com.vaadin.flow.component.orderedlayout. Es ist die Flow-Entsprechung des <vaadin-vertical-layout theme="spacing"> aus dem Abschnitt Abstände :

import com.vaadin.flow.component.orderedlayout.VerticalLayout;

VerticalLayout feldergruppen = new VerticalLayout();
feldergruppen.setSpacing(true);
feldergruppen.setPadding(false);
feldergruppen.add(person, adresse);

setSpacing(true) setzt am gerenderten vaadin-vertical-layout den Theme-Namen spacing; die Vaadin-Dokumentation zu Version 25.0 führt spacing als Theme-Variante des VerticalLayout. Genau diesen Theme-Namen erfasst die Mate-Theme-Datei size/base/flex-layout.css für vaadin-vertical-layout und setzt gap: var(--mate-spacing-margin), also 16 px auf dem Desktop und 20 px auf mobilen Geräten.

Info für Dev

Bei Vaadins VerticalLayout sind spacing und padding voreingestellt. setSpacing(true) macht die Voreinstellung nur ausdrücklich sichtbar.

Das voreingestellte padding wirkt unter dem Mate-Theme über --mate-spacing-padding als Innenabstand. Ist an dieser Stelle kein Innenabstand gewünscht, wird er mit setPadding(false) abgeschaltet.