Formular-Widget: Auswahl mit parametrisierter Datenquelle

Geändert am Fr, 17 Okt um 3:43 NACHMITTAGS

INHALTSVERZEICHNIS

Funktionsbeschreibung
Installation
Konfiguration

Funktionsbeschreibung

Dieses Plugin stellt ein neues Auswahlfeld im Formular-Designer bereit, bei dem die Optionen aus einer Datenquelle mit 1 Abfrage-Parameter bezogen werden können. Der Wert für diesen Parameter wird vom Wert eines anderen Formularfelds referenziert. Bei Änderungen im referenzierten Formularfeld wird die Datenquelle erneut abgefragt und die Optionen des Auswahlfelds werden entsprechend aktualisiert.

Weiterhin stellt das Widget-Plugin ein Textfeld bereit, an dem ebenfalls eine Datenquellen mit 1 Parameter-Abfrage hinterlegt werden kann. Bei Änderungen am referenzierten Formularfeld wird nach Ausführung der Datenabfrage der 1. Ergebnis-Wert in das Textfeld geschrieben.

Installation

Das Plugin kann als Mandant- oder System-Plugin installiert werden. Eine Anleitung zur Installation von Plugins finden Sie hier.

Konfiguration

Nachfolgend werden die Konfigurationsmöglichkeiten für die einzelnen Widget-Elemente geschrieben.

Filterbare Auswahl

(Symbol für Formular-Element im Designer)

Die filterbare Auswahl bietet ähnlich wie die das normale Auswahlfeld im Bereich der Optionen die Möglichkeit eine Datenquelle auszuwählen. Dabei werden sowohl CSV-, Datenbank- und Plugin-Datenquellen zur Auswahl angezeigt.

Zusätzlich sind dort, unter dem Bereich Datenbankabfrage, alle Abfragen aufgeführt, die genau 1 Abfrage-Parameter beinhalten.

Achtung: Da das Aktualisieren der Elemente der filterbaren Auswahl im Browser, auf Seiten des Nutzers, stattfindet, müssen die dazu genutzten Datenquellen über das Web verfügbar und damit entsprechend der Öffentliche Zugriff an diesen Datenquellen aktiviert sein.

Optionen

Konfiguration im Bereich Optionen

Name	Beschreibung
Datenquelle	Die Auswahl Datenquelle verbindet das Formularelement mit einer Datenquelle. Es können CSV-Datenquellen und DB-Abfragen als Datenquelle verwendet werden. Dabei stehen auf DB-Abfragen mit genau 1 Abfrage-Parameter zur Auswahl.
Standard Option anzeigen	Auswahl, ob eine Standardoption Bitte auswählen immer angezeigt werden soll. Diese Option wird standardmäßig aktiviert, wenn das Auswahlelement zum Mussfeld geschalten wird, kann aber individuell wieder deaktiviert werden. Wenn dagegen das Auswahlelement so konfiguriert wird, dass es kein Mussfeld mehr ist, wird diese Option automatisch wieder deaktiviert und kann dann individuell wieder aktiviert werden.
Text Spalte	Auswahl, aus welcher Spalte der ausgewählten Datenquelle, die für den Benutzer sichtbaren Auswahltexte entnommen werden sollen.
Wert Spalte	Auswahl, aus welcher Spalte der ausgewählten Datenquelle, die zu übertragenden (technischen) Werte entnommen werden sollen.
Titel Spalte	Auswahl, aus welcher Spalte der ausgewählten Datenquelle, die für den Benutzer sichtbaren Hinweistexte beim "Hovern" über eine Option entnommen werden sollen.
Alle Attribute rendern	Für das Auslesen aller Spalten einer Datenquelle, die über mehr als nur Text- und Wertspalte verfügen oder für einen Zugriff mittels JavaScript auf alle Daten-Spalten, sollte diese Option aktiviert werden. Ohne diese Festlegung werden nur Text, Wert und Titel an der Auswahl-Option im Browser gerendert. Die Daten-Spalten werden als Attribut data-colX an die Auswahl-Optionen angehangen (Das X steht hierbei für den Spalten-Index). Bitte beachten sie auch, welche Daten in der Datenquelle enthalten sind, die Sie verwenden.
Doppelte Text-Wert Paare entfernen	Sollte eine Datenquelle doppelte Datensätze enthalten, welche für Wert und Text zugeordnet sind, werden als Duplikate angesehen und entfernt.

Datenquelle Filter Einstellungen

Konfiguration im Bereich Datenquellen Filter Einstellungen

Name	Beschreibung
filtern durch	Die Auswahl filtern durch verbindet das Formularelement mit einem anderen Formularelement, dessen Wert als Abfrage-Parameter für die (im Bereich Optionen) definierte Datenquelle angenommen wird.
'col'-Attribut für Filter nutzen	Wenn das festgelegte Element unter der Option filtern durch ein Auswahl-Element ist, kann über diese Einstellung festgelegt werden, ob der Wert einer Option oder der Wert eines data-colX Attributes an der gewählten Option, als Abfrage-Parameter verwendet werden soll. Die Nutzung dieser Option bedingt, dass die Option Alle Attribute rendern am Auswahl-Element, welches als Filter festgelegt ist, aktiviert ist.
'col'-Attribut Spalte	Diese Option steht nur zur Verfügung, wenn 'col'-Attribut für Filter nutzen aktiv ist. Über diese Einstellung wird festgelegt, welches data-colX Attribut von der jeweiligen Auswahl-Option als Wert-Quelle herangezogen wird.
Filter anwenden auf Datenquellen-Spalte	Diese Option steht nur zur Verfügung, wenn es sich bei der angebundenen Datenquelle um eine CSV-Datei handelt. Über diesen Wert wird festgelegt, auf welche Spalte in der zu filternden CSV-Datenquelle der Filter-Wert anzuwenden ist.

Filterbares Textfeld

(Symbol für Formular-Element im Designer)

Das filterbare Textfeld bietet zusätzlich zu den Konfigurationsmöglichkeiten eines Standard-Textfeldes die Option eine Datenquelle als Wertelieferant zu hinterlegen. Dazu gibt es unter den Element-Eigenschaften im Designer zusätzlich den Bereich Optionen. Ähnlich wie bei einem Auswahlfeld lassen sich hier Datenquellen hinterlegen.

Achtung: Da das Aktualisieren der Wertes des filterbaren Textfeldes im Browser, auf Seiten des Nutzers, stattfindet, müssen die dazu genutzten Datenquellen über das Web verfügbar und damit entsprechend der Öffentliche Zugriff an diesen Datenquellen aktiviert sein.

Optionen

Konfiguration im Bereich Optionen

Name	Beschreibung
Datenquelle	Die Auswahl Datenquelle verbindet das Formularelement mit einer Datenquelle. Es können CSV-Datenquellen und DB-Abfragen als Datenquelle verwendet werden. Dabei stehen zusätzlich auch DB-Abfragen mit genau 1 Abfrage-Parameter zur Auswahl.
Wert Spalte	Diese Option steht nur zur Verfügung wenn eine Datenquelle gewählt wurde: Auswahl, aus welcher Spalte der ausgewählten Datenquelle, der zu übertragende (technische) Wert entnommen werden sollen.

Sinnvollerweise sollte das Ergebnis der Datenabfrage für dieses Element genau einen Ergebnisdatensatz zurück liefern. Bei mehr als einem Datensatz im Abfrageergebnis wird der 1 Datensatz aus Ergebnismenge für die Anzeige herangezogen.

Datenquellen Filter Einstellungen

Konfiguration im Bereich Datenquellen Filter Einstellungen

Name	Beschreibung
filtern durch	Die Auswahl filtern durch verbindet das Formularelement mit einem anderen Formularelement, dessen Wert als Abfrage-Parameter für die (im Bereich Optionen) definierte Datenquelle angenommen wird.
'col'-Attribut für Filter nutzen	Wenn das festgelegte Element unter der Option filtern durch ein Auswahl-Element ist, kann über diese Einstellung festgelegt werden, ob der Wert einer Option oder der Wert eines data-colX Attributes an der gewählten Option, als Abfrage-Parameter verwendet werden soll. Die Nutzung dieser Option bedingt, dass die Option Alle Attribute rendern am Auswahl-Element, welches als Filter festgelegt ist, aktiviert ist.
'col'-Attribut Spalte	Diese Option steht nur zur Verfügung, wenn 'col'-Attribut für Filter nutzen aktiv ist. Über diese Einstellung wird festgelegt, welches data-colX Attribut von der jeweiligen Auswahl-Option als Wert-Quelle herangezogen wird.

Anwendungsbeispiel mit CSV-Datenquellen

Das nachfolgende Beispiel skizziert ein Beispiel anhand von zwei CSV-Datenquellen.

Die erste Datenquelle definiert Abteilungen innerhalb einer Organisation:

CSV-Datenquelle mit möglichen Abteilungen einer Organisation

Die CSV-Datenquelle definiert 2 Spalten

Id: Eine Nummer, welche die Abteilung innerhalb der Liste eindeutig identifiziert.
Name: Die Bezeichnung der Abteilung, welche dem Nutzer im Formular angezeigt werden soll.

Die zweite Datenquelle definiert Mitarbeiter einer Organisation und deren Zugehörigkeit zu einer Abteilung:

CSV-Datenquelle mit Mitarbeitern und deren Zugehörigkeit zu einer Abteilung

Die CSV-Datenquelle definiert 3 Spalten

Id: Eine Nummer, die den Mitarbeiter innerhalb der Liste eindeutig identifiziert.
Name: Der Name des Mitarbeiters, welcher dem Nutzer im Formular angezeigt werden soll.
Abteilung: Die Id der Abteilung, welcher der Mitarbeiter zugeordnet ist. (Referenziert auf die Id der ersten CSV-Datenquelle Abteilung)

Diese 2 Datenquellen bilden den Ausgangspunkt für ein Anwendungsbeispiel. In diesem sollen auf Grundlage der Auswahl einer Abteilung, in einem zweiten Auswahlfeld, alle zur Abteilung zugehörigen Mitarbeiter zur Auswahl angeboten werden.

Konfiguration der Abteilungsliste

Als Formular-Element für das Feld selAbteilung wird im Beispiel eine Filterbare Auswahl gewählt. Es kann an dieser Stelle auch ein einfaches Auswahl-Element verwendet werden, da für die Anzeige der Abteilungsliste kein Filter definiert werden muss. Das heißt, es werden dem Nutzer immer alle Elemente der CSV-Datenquelle Abteilung zur Auswahl angeboten.

Konfigurationsbeispiel für Anbindung CSV-Abteilungsliste

Einstellungen im Bereich Optionen

Nachfolgend werden die einzelnen Optionen und deren Auswirkungen auf die referenzierte Datenquelle erläutert.

(Einige Optionen enthalten den Vermerk optional und sind für die Sicherstellung der Funktionsweise in diesem Beispiel nicht unbedingt notwendig.)

Datenquelle: Definiert die anzubindende Datenquelle. Im Beispiel die CSV-Datenquelle Abteilung.
Standard Option anzeigen (optional): Bedingt im Zusammenspiel mit der Mussfeld-Bedingung, dass der Nutzer vor dem Absenden des Formulars (bei aktivierter Validierung) eine Abteilung auswählen muss.
Text Spalte: Hier wird die Spalte innerhalb der angebunden Datenquelle definiert, die den für den Nutzer anzuzeigenden Text innerhalb der Auswahlliste enthält. Im Beispiel soll die Bezeichnung der Abteilung verendet werden, deshalb ist die Nummer 2 für die 2 Spalte Name in der CSV-Datenquelle Abteilung festgelegt.
Wert Spalte: Hier wird die Spalte innerhalb der angebunden Datenquelle definiert, die den Wert, welcher beim Absenden des Formulars an den Server übermittelt wird definiert. Im Beispiel soll die Bezeichnung der Abteilung verwendet werden, deshalb ist die Nummer 2 für die 2 Spalte Name in der CSV-Datenquelle Abteilung festgelegt.
Titel Spalte (optional): Hier wird die Spalte innerhalb der angebunden Datenquelle definiert, die den Anzeigewert, der beim "Hovern" über die Auswahl-Option angezeigt werden soll, festlegt. Im Beispiel soll hier ebenfalls die Bezeichnung der Abteilung verwendet werden, deshalb ist die Nummer 2 für die 2 Spalte Name in der CSV-Datenquelle Abteilung festgelegt.
Alle Attribute rendern: Diese Option bewirkt, das alle Werte aus der CSV-Datenquelle als 'col'-Attribute an der jeweiligen Auswahl-Option hinterlegt werden. Die Aktivierung dieser Einstellung ist im Beispiel wichtig, da nicht auf den Options-Wert für die Angabe des Filter-Parameters für die Mitarbeiter CSV-Datenquelle referenziert wird, sondern auf die Id. Damit diese im Formular an den Auswahl-Optionen verfügbar gemacht wird, muss diese Einstellung aktiviert werden.
Doppelte Text-Wert Paare entfernen (optional): Diese Einstellung wird im Beispiel nicht benötigt, da wird bei der Definition der CSV-Datenquelle sichergestellt haben, dass keine Abteilungs-Bezeichnung doppelt definiert wurde.

Einstellungen im Bereich Datenquellen Filter Einstellungen

In diesem Bereich ist keine Einstellung vorzunehmen, da dem Nutzer alle Elemente der angebunden CSV-Datenquelle angezeigt werden sollen.

Konfiguration der Mitarbeiterliste

Als Formular-Element für das Feld selMitarbeiter muss eine Filterbare Auswahl gewählt werden, da für die Anzeige der Mitarbeiter der jeweiligen Abteilung eine Filterung nach der aktuellen Auswahl im Element selAbteilung stattfinden soll. Das heißt, es sollen dem Nutzer nur die Mitarbeiter zur Auswahl angeboten werden, die der zuvor ausgewählten Abteilung angehören.

Konfigurationsbeispiel für Anbindung CSV-Mitarbeiterliste

Einstellungen im Bereich Optionen

Nachfolgend werden die einzelnen Optionen und deren Auswirkungen auf die referenzierte Datenquelle erläutert.

(Einige Optionen enthalten den Vermerk optional und sind für die Sicherstellung der Funktionsweise in diesem Beispiel nicht unbedingt erforderlich.)

Datenquelle: Definiert die anzubindende Datenquelle. Im Beispiel die CSV-Datenquelle Mitarbeiter.
Standard Option anzeigen (optional): Bedingt im Zusammenspiel mit der Mussfeld-Bedingung, dass der Nutzer vor dem Absenden des Formulars (bei aktivierter Validierung) einen Mitarbeiter auswählen muss.
Text Spalte: Hier wird die Spalte innerhalb der angebunden Datenquelle definiert, die den für den Nutzer anzuzeigenden Text innerhalb der Auswahlliste enthält. Im Beispiel soll der Mitarbeitername verendet werden, deshalb ist die Nummer 2 für die 2 Spalte Name in der CSV-Datenquelle Mitarbeiter festgelegt.
Wert Spalte: Hier wird die Spalte innerhalb der angebunden Datenquelle definiert, die den Wert, welcher beim Absenden des Formulars an den Server übermittelt wird definiert. Im Beispiel soll der Mitarbeitername verwendet werden, deshalb ist die Nummer 2 für die 2 Spalte Name in der CSV-Datenquelle Mitarbeiter festgelegt.
Titel Spalte (optional): Hier wird die Spalte innerhalb der angebunden Datenquelle definiert, die den Anzeigewert, der beim "Hovern" über die Auswahl-Option angezeigt werden soll, festlegt. Im Beispiel soll hier ebenfalls der Mitarbeitername verwendet werden, deshalb ist die Nummer 2 für die 2 Spalte Name in der CSV-Datenquelle Mitarbeiter festgelegt.
Alle Attribute rendern (optional): Diese Option bewirkt, das alle Werte aus der CSV-Datenquelle als 'col'-Attribute an der jeweiligen Auswahl-Option hinterlegt werden. Diese Einstellung wird im Beispiel nicht benötigt und ist deshalb deaktiviert.
Doppelte Text-Wert Paare entfernen (optional): Diese Einstellung wird im Beispiel nicht benötigt, da wird bei der Definition der CSV-Datenquelle sichergestellt haben, dass keine Mitarbeiternamen doppelt definiert wurden.

Einstellungen im Bereich Datenquellen Filter Einstellungen

filtern durch: Definiert ein Formularelement welches den Wert für eine Filterung liefert. Im Beispiel ist dies das Element selAbteilung und dessen aktuell durch einen Nutzer ausgewählte Option.
'col'-Attribute für Filter nutzen: Mit diesem Feld kann festgelegt werden, ob der Filter-Parameter dem Wert der Auswahl-Option (Eigenschaft nicht aktiviert) oder einem 'col'-Attribut an der Auswahl-Option entnommen wird.
Im Beispiel wird ein 'col'-Attribut genutzt, da dort die notwendige Id der Abteilung abgebildet wird, während der Wert der Auswahl-Option die Bezeichnung der Abteilung enthält, welche als Filter-Parameter nicht dienen kann.
Gerenderte HTML-Code für die selAbteilung Auswahlliste
'col'-Attribut Spalte: Wenn die Eigenschaft 'col'-Attribute für Filter nutzen aktiv ist, muss mit dieser Eigenschaft die genaue Spalte aus der CSV-Datei, welche über die Eigenschaft filtern durch referenziert wird, angegeben werden.
Im Beispiel wird durch das Element selAbteilung die CSV-Datenquelle Abteilung referenziert. Als Filter-Parameter ist die Id der Abteilung zu verwenden. Diese ist in der CSV-Datenquelle in Spalte 1 hinterlegt.
Filter anwenden auf Datenquellen-Spalte: Diese Option ist nur dann verfügbar, wenn es sich bei der angebundenen Datenquelle, um eine CSV-Datenqelle handelt. Anders als bei Datenbank-Abfragen, wo die definierte Abfrage die Verwendung des Filter-Parameters definiert, gibt es dies bei der Anbindung von CSV-Datenquellen nicht. Deshalb muss an dieser Stelle die Spalte in der zugrundeliegenden CSV-Datenquelle definiert werden, auf die der Filter-Parameter angewendet wird.
Im Beispiel ist dies die Spalte Abteilung in der CSV-Datenquelle Mitarbeiter. Die Spalte befindet sich an der 3. Stelle, deshalb wird der Wert 3 hinterlegt.