DB-Abfragen
Datenbankabfragen verhalten sich ähnlich wie Datenquellen (XML, CSV, JSON), werden jedoch nicht statisch hinterlegt, sondern dynamisch aus einer Datenbank ausgelesen.
Anlegen einer SQL-Abfrage
- Öffnen Sie das Modul "DB-Abfragen" und klicken Sie auf die Schaltfläche "Neu" in der Kopzeile der Liste (siehe Abbildung).
- Für die Datenbank-Abfrage werden folgende Daten benötigt:
- Name: Ein eindeutiger Name der Datenbank-Abfrage
- Beschreibung: Eine optionale Beschreibung der Datenbank-Abfrage
- Verbindung: Die DB-Verbindung, die verwendet werden soll
- Die eigentliche SQL-Abfrage wird im Editor in der Mitte einegeben (siehe Abbildung).
Das eingegebene Statement wird als Prepared-Statement ausgeführt, so dass keine sogenannte SQL-Injection moglich ist. Verwenden Sie daher auch keine Hochkommas. Prinzipiell können auch Übergabeparameter verwendet werden. In der Abfrage setzen Sie an die Stelle des Übergabeparameters ein Fragezeichen ?.
Verwenden der Abfrage
Die Datenbankabfrage ist innerhalb und außerhalb eines Formulars über das hierfür vorgesehene Servlet unter Verwendung der entsprechenden Parameter abrufbar. Die URL zur Datenbankabfrage lautet wie folgt:
Die Servlet-URL wird unterhalb der Einstellungen angezeigt (siehe Abbildung).
Folgende URL-Parameter sind hierbei möglich:
| Parametername | Beschreibung | Erforderlich |
|---|---|---|
| name | Muss dem Namen der Datenbank-Abfrage entsprechen. | Ja |
| mandantName | Muss dem Namen des Mandanten entsprechen, unter welchen diese Datenquelle erstellt wurde. | Ja, wenn projektId nicht gegeben |
| projektId | Muss der ID des Formulars entsprechen. Diese Information kann über XFC_METADATA.currentProject.id abgerufen werden. | Ja, wenn mandantName nicht gegeben |
| sqlParameter | Synonym für queryParameter. Sollte nicht mehr verwendet werden ab Version 6 und wird es in späteren Versionen nicht mehr geben. | |
| queryParameter | Nur erforderlich, wenn innerhalb der Datenbank-Datenquelle Platzhalter in Form eines Fragezeichens verwendet werden. Ist dies der Fall, so entspricht dieser der komma-separierten Listen der zu verwendeten Parameter. (ab Version 6) | Nein |
| varName | Gibt den Namen des JSON-Response-Objektes an. Ist dieser nicht gesetzt, so besitzt das JSON-Objekt keinen expliziten Namen. | Nein |
| delimiter | Trennzeichen, welches die einzelnen Werte des queryParameter trennt. Standardmäßig ein Komma ,. | Nein |
Bei Zugriff aus einem Formular verwenden Sie bitte immer das globale Variablenobjekt XFC_METADATA, siehe hierzu auch die Metadaten. In diesem Objekt stehen alle relevanten URLs von Xima® Formcycle zur Verfügung, sodass diese Beispielhaft wie folgt ermittelt werden kann: XFC_METADATA.urls.datasource_db.
Ferner empfehlen wir, innerhalb des Formulars die Skriptfunktion getDataQuery zu verwenden, die das manuelle Aufbauen der Servlet-Abfrage erspart.
Die Rückgabe des Abfrage-Ergebnisses erfolgt im JSON-Format und kann somit innerhalb des Formulars direkt genutzt werden.
Testen der Abfrage
Datenbank-Abfragen können direkt in der Konfigurationsoberfläche getestet werden. Hierzu steht eine Testkonsole unterhalb des SQL-Editor zur Verfügung (siehe Abbildung).
Im Header der Testkonsole befindet sich eine Reihe von Buttons zur Steuerung der Abfrage:
- Abfrage ausführen
Führt die Datenbank-Abfrage aus. Werden Abfrageparameter (?) verwendet, wird der Nutzer aufgefordert Werte für diese Parameter einzugeben. Ist dies nicht der Fall wird das Ergebnis der Abfrage direkt in der Tabellenansicht dargestellt.
- Abfrageparameter
Maske zum Eingeben von Werten für Abfrageparameter. Diese Option steht nur zur Verfügung, wenn Abfrageparameter (?) in der SQL-Abfrage verwendet werden. Die einzelnen Abfrageparameter werden nummeriert im SQL-Query dargestellt. Ein Klick auf "Parameter für Abfrage verwenden" führt die Abfrage mit den eingebenen Parametern aus. Das Ergebnis wird in der Tabellenansicht dargestellt.
- Tabellenansicht
Abfrageergebnis in Tabellenform
- Quellcodeansicht
Abfrageergebnis im JSON-Format
- Generiertes SQL
Zeigt das generierte SQL-Statement mit eingefügten Parameterwerten
Sonderfall Auswahlelement
Soll das Ergebnis einer Datenbankabfrage direkt in ein Auswahlelement geladen werden, erfolgt dies über die Eigenschaften des Auswahlelements im Xima® Formcycle-Designer.
Der Inhalt der SQL-Datenbankabfrage wird in einem Auswahlelement in folgender Reihenfolge verwendet.
Sichtbarer Wert, Übertragener Wert, Optionaler Wert 1, Optionaler Wert 2, ...
Alle übertragenenen Werte werden als Wert des HTML-Attribut col0 (sichtbarer Wert), col1 (übertragener Wert), col2 (optionaler Wert 1), col3 (optionaler Wert 2) usw. an das jeweilige option-Element angefügt.
Der sichtbare Wert wird in der Auswahlliste im Formular angezeigt. Der übertragene Wert wird als Wert des HTML-Attributs value beim Absenden des Formulars übertragen.
Werden zudem noch ein oder mehrere optionale Werte von der SQL-Datenbankabfrage zurückgegeben, so können diese per Javascript über den folgenden jQuery-Selector abgerufen werden.
Beipiele
Diese SQL-Abfrage liefert die Namen aller Personen zurück, die einen bestimmten Vornamen haben. Nach welchem Vornamen gesucht werden soll, kann über einen URL-Parameter angegeben werden.
Abfrage per Servlet: http://meinserver/formcycle/datenquelledb?mandantName=ich&name=demo&sqlParameter=Mustermann
Diese SQL-Abfrage liefert die Person mit einer bestimmten ID zurück. Die ID wird als URL-Parameter übergeben.
Abfrage per Servlet: http://meinserver/formcycle/datenquelledb?mandantName=ich&name=demo&sqlParameter=100
Diese SQL-Abfrage liefert die Namen aller Personen zurück, die an einem bestimmten Ort wohnen. Der Ort mit Postleitzahl wird über URL-Parameter übergeben.
Abfrage per Servlet: http://meinserver/formcycle/datenquelledb?mandantName=ich&name=demo&sqlParameter=Entenhausen,02442