Lookup

Das Lookup ist ein Eingabefeld, das eine Combo Box mit einem Dialog verbindet, in dem die Optionen mit weiteren Informationen dargestellt werden.

Overview

Intro

Die Lookup Komponente unterstützt den Nutzer bei der Auswahl einer oder mehrerer Optionen. Im Vergleich zur Combo Box bietet die Lookup Komponente durch ihren dazugehörigen  Dialog  mehr Platz für weitere Informationen, die für eine richtige Auswahl notwendig sind.

Bei Bedarf kann bei einer bereits ausgewählten Option der Dialog erneut geöffnet werden, um sich erneut die weiteren dazugehörigen Informationen einzublenden oder falls eine Mehrfachauswahl möglich ist weitere Einträge auszuwählen.

Lookups können in verschiedenen Kontexten auftreten, z. B. in  Formularen oder der  Filter Panel .

broken_image Figma	Lookup ohne Eingabe und ohne geöffneten Dialog
broken_image Figma	Lookup Dialog (multi-select)
broken_image Figma	Lookup Dialog (single-select, filter-panel)

Verwendung

👍 Do	👎 Don't
...wenn für eine richtige Auswahl einer Option mehr als 3 Kriterien in Betracht gezogen werden müssen. ...wenn einzelne Kriterien sehr viel Platz einnehmen, wie z. B. Texte	...wenn die Optionen aus 3 oder weniger Kriterien bestehen. Verwende dazu die ComboBox und stelle die Optionen ggf. 2-zeilig dar.

Guidelines

Aufbau

Das Lookup besteht aus einer Combo Box als Eingabefeld, einer Suchen-Schaltfläche unmittelbar rechts daneben und dem Dialog , den diese Schaltfläche öffnet. Der Dialog enthält immer eine Tabelle mit den Auswahloptionen und eine Fußzeile mit den Schaltflächen zum Übernehmen und Abbrechen. Das Zusammenspiel besteht aus folgenden Bestandteilen:

• Combo Box — das Eingabefeld des Lookups. Sie bringt Label, Eingabefeld, Auswahlliste, Clear button und Ausklappen-Schaltfläche mit; diese Bestandteile sind unter Combo Box beschrieben. Für die Mehrfachauswahl tritt an ihre Stelle eine Multi-Select Combo Box .
• Suchen-Schaltfläche — ein Button im Icon-Stil mit einer Lupe, der bündig an das Feld anschließt und den Dialog öffnet. Er ist eigenständig fokussierbar und trägt ein aria\-label , weil er keine sichtbare Beschriftung hat. Ist das Feld Read Only oder Disabled, ist auch die Schaltfläche Disabled.
• Dialog — nimmt Suchfeld, Tabelle und Fußzeile auf und trägt einen eigenen Titel. Aufbau und Verhalten des Dialogs selbst sind unter Dialog beschrieben.
• Suchfeld — Eingabefeld oberhalb der Tabelle, mit dem die Tabelle gefiltert wird. Es hat einen Clear button und ein Lupen-Icon am Ende des Feldes.
• Tabelle — ein Grid mit den Auswahloptionen. Über mehrere Spalten lassen sich je Option mehr Informationen darstellen als in der Auswahlliste der Combo Box.
• Fußzeile — enthält die primäre Schaltfläche zum Übernehmen der Auswahl und eine Schaltfläche zum Abbrechen. Die Übernehmen-Schaltfläche bleibt Disabled, solange nichts ausgewählt ist.
• Anlegen-Schaltfläche (optional) — zusätzliche Schaltfläche am linken Rand der Fußzeile, über die ein neuer Eintrag angelegt werden kann. Sie ist standardmäßig ausgeblendet.

Der  Dialog  kann in den Größen  Small ,  Medium  und  Large  angezeigt werden. Die Größe sollte sich nach der Anzahl an Spalten in der Tabelle richten.

Im Dialog befindet sich ein Eingabefeld mit dem die darunter positionierte Tabelle gefiltert werden kann. Siehe Verhalten für weitere Informationen.

Die Anordnung des Feldes im Formular und seine Spaltenbelegung regelt das Form Layout .

Info für Dev

Das Lookup ist keine Vaadin-Kernkomponente, sondern stammt von der Vaadin Component Factory.

In Web Components ist es das Element <vcf-lookup-field> aus dem Paket @vaadin-component-factory/vcf-lookup-field. Das Paket ist Bestandteil von @mate/bundles. Die Combo Box wird in den Slot field gelegt, das Grid in den Slot grid; ohne eigenes Feld erzeugt die Komponente selbst eine <vaadin-combo-box>.

In Vue heißt die Komponente MateLookup und stammt aus dem Paket @mate-vue/lookup. Die Vue-Fassung ist derzeit nicht voll funktionsfähig und für den produktiven Einsatz noch nicht freigegeben.

In Flow sind es die Klassen LookupField und MultiSelectLookupField aus dem Paket com.vaadin.componentfactory.lookupfield, Maven-Artefakt com.vaadin.componentfactory:lookup-field.

Varianten/Typen

Standard

Das Standard Lookup wird verwendet, wenn eine einzige Option ausgewählt werden soll. Die Auswahl ist sowohl über die Combo Box als auch über den Dialog, der über den rechten Button geöffnet werden kann, möglich. Die beiden Elemente sind miteinander verknüpft.

broken_image

Figma

Lookup Standard

Combo Box, in der eine einzige Option ausgewählt wurde (bei geöffneter Listbox)

Dialog bei Einfachauswahl

Wird aus einer Combo Box der Dialog aufgerufen, ermöglicht dieser ebenfalls die Auswahl eines Eintrags. Der Dialog ermöglicht die Darstellung von mehr Informationen in Form von mehreren Tabellenspalten sowie das Suchen nach Einträgen.

broken_image

Figma

Dialog single-select

Einfachauswahl im Dialog.

Mehrfachauswahl

Das Mehrfachauswahl Lookup wird verwendet, wenn mehrere Optionen ausgewählt werden sollen. Die Auswahl ist sowohl über die Combo Box (Listbox) als auch über den Dialog, der über den rechten Button geöffnet werden kann, möglich. Die beiden Elemente sind miteinander verknüpft.

broken_image Figma	Lookup multi-select Mehrfachauswahl-Combo-Box, in der mehrere Optionen ausgewählt wurden (bei geöffneter Listbox)
broken_image Figma	Lookup multi-select closed Mehrfachauswahl-Combo-Box, in der mehrere Optionen ausgewählt wurden (bei geöffneter Listbox), die überfließenden Elemente werden als Anzahl links indiziert (Overflow-Indikator)

Dialog bei Mehrfachauswahl

Wird aus einer Combo Box mit Mehrfachauswahl der Dialog aufgerufen, ermöglicht dieser ebenfalls die Mehrfachauswahl von Einträgen. Der Dialog ermöglicht die Darstellung von mehr Informationen in Form von mehreren Tabellenspalten sowie das Suchen nach Einträgen.

broken_image

Figma

Dialog multi-select

Mehrfachauswahl im Dialog.

Suchfunktion und Suchleiste im Dialog

Das Suchen von Einträgen im Dialog ist entweder durch ein einfaches Suchfeld oder als weitere Variante mittels des Musters (Patterns) des  Filter Panel  möglich.

broken_image

Figma

Dialog mit Suchleiste

Suchleiste im Dialog.

Verhalten

1. Das Eingabefeld des Lookups verhält sich wie eine  Combo Box und kann genutzt werden, um auf dieser Ebene eine Auswahl zu treffen. Die Optionen im Dropdown Fenster der  Combo Box  können bei Bedarf zweizeilig dargestellt werden.
2. Die Suche im Dialog verhält sich analog zur  Combo Box . Der Vorteil für die Nutzer: In der Tabelle können mehr Informationen dargestellt werden als im Dropdown Fenster der  Combo Box .
3. Falls sich im Eingabefeld ein Suchbegriff befindet, dann wird dieser beim Öffnen vom Dialog übernommen.
4. Falls sich im Eingabefeld eine Auswahl befindet, wird die Auswahl in den Dialog übernommen.
5. Ausgewählte Optionen lassen sich jederzeit zurücksetzen.
6. Suchkriterien lassen sich jederzeit zurücksetzen.
   broken_image
   Figma

Lookup Verhalten

Validierung

Die Validierung erfolgt an der Combo Box des Lookups: sobald ein Wert übernommen wird und spätestens beim Verlassen des Feldes. Ist der Wert ungültig, wird das Lookup Feld rot hervorgehoben und eine Fehlermeldung erscheint unterhalb des Feldes.

Die Prüfung läuft in zwei Stufen. Die Pre-Submit-Validierung prüft das einzelne Feld, sobald es den Fokus verliert, und zeigt den Fehler unmittelbar unterhalb des Feldes. Die Post-Submit-Validierung läuft, nachdem der Nutzer das Formular abgeschickt hat: Sie prüft alle Felder erneut, markiert die fehlerhaften und setzt den Fokus auf das erste davon. Beide Stufen und die Formulierung der Fehlermeldungen sind unter Validierung unter Formulare beschrieben.

Die allgemeinen Regeln der Combo Box gelten unverändert und sind unter Combo Box beschrieben. Für das Zusammenspiel mit dem Dialog gilt zusätzlich:

• Die Combo Box eines Lookups ist auf benutzerdefinierte Eingaben eingestellt. Eine Texteingabe, die keiner Option entspricht, wird deshalb als Wert übernommen und nicht auf den zuletzt gültigen Wert zurückgesetzt. Ob ein solcher Wert fachlich zulässig ist, prüft die Anwendung.
• Der Dialog prüft nicht selbst. Er weist der Combo Box die bestätigte Auswahl zu; geprüft wird, sobald die Combo Box den Fokus verliert. Das geschieht bereits beim Öffnen des Dialogs. Wird der Dialog abgebrochen, bleibt der bisherige Wert erhalten.
• Als Constraint steht ausschließlich Required zur Verfügung. Er wirkt an der Combo Box: Das Feld wird ungültig, wenn kein Wert gesetzt ist.

States

Enabled

Ein Lookup Feld im State Enabled kann vom Nutzer fokussiert werden und die Eingabe kann auf zwei Wegen erfolgen. Eine Möglichkeit ist es, per Tastatur eine Eingabe zu tätigen, wonach sich das Dropdown öffnet und eine Auswahl getroffen werden kann. Dazu ist es noch möglich das Dropdown über einen Klick auf das Chevron Icon oder in das Feld zu öffnen. Der zweite Weg ist, eine Eingabe über den Dialog zu tätigen, in dem eine Tabelle dargestellt wird. Dieser öffnet sich durch einen Klick auf die Lupe. 

broken_image

Figma

Enabled

Disabled

Ein Lookup Feld kann Disabled sein, wenn es sich durch bestimmte Vorbedingungen (noch) nicht ändern lässt. Es wechselt erst in den State Enabled, wenn die Vorbedingungen erfüllt sind. Ein Lookup Feld im State Disabled lässt sich nicht durch den Nutzer ändern.

broken_image

Figma

Disabled

Read Only

Ein Lookup Feld kann für den Nutzer auf Read Only gesetzt sein. In diesem Fall dient das Feld lediglich als Anzeige der evtl. vorhandenen eingegebenen Daten. Die Daten können nicht durch den Nutzer geändert werden. Im Unterschied zum Eingabefeld im State Disabled, kann ein Feld im State Read Only nicht unter bestimmten Bedingungen in den State Enabled wechseln.

broken_image

Figma

Read Only

Hover

Ein Lookup Feld im State Enabled wird hervorgehoben, wenn der Nutzer den Mauszeiger über das Feld bewegt.

broken_image Figma	Hover
broken_image Figma	Hover im State Error

Error

Lookup Felder können validiert werden. Je nach Ergebnis der Validierung wird das Lookup Feld hervorgehoben. Im State Error erscheint die Fehlermeldung unterhalb vom Lookup Feld und das Feld wird rot hervorgehoben. Die Fehlermeldung sollte so formuliert werden, dass dem Nutzer klar ist, wie der entstandene Validierungsfehler behoben werden kann, siehe dazu auch Validierung unter  Formulare .

broken_image

Figma

Error

Barrierefreiheit

Tastaturbedienung

Über Tabulatortaste ("Tab") oder Hochstell- und Tabulatortaste ("Shift" + "Tab") ist das Lookup Feld fokussierbar. Zunächst wird der linke Teil fokussiert, der eine Combo Box darstellt. Hier lassen sich einzelne Optionen mit den Pfeiltasten ansteuern. Ist eine Option im Fokus, kann diese mittels Wagenrückholtaste ("Return"), Eingabetaste ("Enter") und auch per Leerzeichentaste ("Space") ausgewählt werden. Über das erneute Betätigen der Tabulatortaste ("Tab") kann die Taste zum Öffnen des Dialogs, die sich rechts befindet, fokussiert werden. Der Dialog, der die einzelnen Optionen zur Auswahl übersichtlicher darstellt, kann durch das Drücken der Wagenrückholtaste ("Return"), der Eingabetaste ("Enter") und auch per Leerzeichentaste ("Space") aufgerufen werden. Die im Dialog enthaltene Tabelle kann durch Tastatureingaben im Filter Eingabefelder gefiltert werden. Die Navigation zur Tabelle im Dialog erfolgt via Tabulatortaste ("Tab"). Die Auswahl einer Option in der Tabelle erfolgt dadurch, dass man mit den Pfeiltasten zur richtigen Option navigiert und die Auswahl mit der Leerzeichentaste ("Space") bestätigt. Danach muss man mit der Tabulatortaste ("Tab") oder Hochstell- und Tabulatortaste ("Shift" + "Tab") zur "Auswahl übernehmen" Taste navigieren und den Vorgang mit der Wagenrückholtaste ("Return"), der Eingabetaste ("Enter") oder der Leerzeichentaste ("Space") bestätigen, woraufhin sich der Dialog schließt.

Spezifische Hinweise

Das Lookup setzt sich aus einer Combo Box und einem Dialog zusammen; was diese beiden von sich aus mitbringen, ist unter Combo Box und Dialog beschrieben. Das Lookup selbst führt den Fokus zwischen beiden: Beim Öffnen erhält das Suchfeld im Dialog den Fokus, beim Schließen kehrt er auf die Combo Box zurück. Label, Pflichtfeld-Kennzeichnung und State Error werden an die Combo Box durchgereicht und dort mit dem Eingabefeld verknüpft. Nichts davon wird nachgebaut. Das Produktteam verantwortet die Inhalte:

• Da jedes Eingabefeld ein Label haben muss, ist kein zusätzliches aria\-label nötig. Ein am Feld gesetztes aria\-label ersetzt den Namen aus dem sichtbaren Label und darf deshalb nur bei Feldern ohne sichtbares Label verwendet werden.
• Der Platzhalter ist kein Ersatz für das Label und wird nicht zuverlässig vorgelesen. Formathinweise gehören in das Label oder in den Helper text.
• Ein Feld, das dauerhaft nur der Anzeige dient, wird auf Read Only gesetzt: Es bleibt fokussierbar, für Screenreader sichtbar und sein Wert kopierbar. Ein Feld, das im Laufe des Prozesses wieder bearbeitbar werden kann, wird auf Disabled gesetzt: Es ist nicht fokussierbar und für Screenreader unsichtbar und eignet sich deshalb nicht zur Anzeige von Informationen. Siehe States .
• Fehlermeldung: Die Verknüpfung mit dem Eingabefeld stellt die Komponente her. Das Produktteam verantwortet den Text — er muss sagen, wie der Fehler zu beheben ist (z.B. "Eintrag aus der Trefferliste auswählen" , nicht nur "Fehler" ), und der Fehler darf nicht ausschließlich über Farbe kommuniziert werden.
• Pflichtfeld-Kennzeichnung: Wie Pflichtfelder gekennzeichnet und erklärt werden, regelt Formulare .
• Die Beschriftungen der Dialog-Buttons und des Suchfeldes liefert @mate/i18n auf Deutsch. Nicht abgedeckt sind die Meldung, die beim Bestätigen ohne Auswahl erscheint, und der Name des Such-Buttons für Screenreader — diese beiden Texte verantwortet die Anwendung.