Einleitung
Hinweis: Diese Feature sind Teil der Visforms Subscription und in der freien Visforms Version nicht enthalten.
Manchmal wollen Sie in Ihren Formularen Listboxen (oder Radio Buttons oder Checkbox-Gruppen) anzeigen, deren Auswahllisten dynamisch während der Laufzeit des Formulars aus der Datenbank bezogen werden. Wenn sich der Inhalt der Datenbank ändert, so hat das entsprechende Feld bei der nächsten Anzeige automatisch auch die geänderten Auswahloptionen. Bei diesem Vorgang kann auch auf die aktuellen Benutzereingaben und die Änderung der Benutzereingaben in anderen Feldern im Formular Bezug genommen werden.
Die Visforms Subscription bietet Ihnen drei neue Feldtypen, deren Auswahllisten mit Hilfe von SQL-Select-Statements dynamisch aus der Datenbank erzeugt werden.
Die SQL-Feldtypen mit Optionenlisten sind:
- Listbox SQL,
- Radio SQL,
- Checkbox Gruppe SQL.
Systemvoraussetzungen
Die Visforms Subscription muss installiert sein.
Das SQL-Select Statement muss die Felder value und label zurückgeben
Die Auswahllisten der SQL-Feldtypen können durch ein SQL-Statement aus der Datenbank erzeugt werden. Erstellen Sie ein valides SQL-Select Statement und tragen Sie dieses in der Feldkonfiguration in die Option “SQL” ein.
Sie können ein beliebiges valides SQL-Select-Statement verwenden. Die einzige Bedingung ist, dass das Statement die beiden Ergebnis-Felder “value” und “label” zurückliefert. Diese werden dann als Optionswert und als Optionslabel der jeweiligen Option verwendet.
Ein kleines Beispiel:
select id as value, title as label from #__content limit 10
Hinweis: Das SQL-Select-Statement darf keine Zeilenschaltungen oder Tabulatoren enthalten. Auch mehrfache Leerzeichen führen zu einer Fehlermeldung.
Das SQL-Select Statement kann weitere Felder zurückgeben
Sie können in Ihrem SQL-Select-Statement folgende weitere Ergebnis-Felder zurückliefern:
- redirecturl,
- mail,
- mailcc,
- mailbcc.
Diese Ergebnis-Felder sind den beiden Visforms-Plugins “Optionsabhängige Erfolgsseiten” und “Optionsabhängige Empfängermail” bekannt. Beide Visforms-Plugins verwenden diese Ergebnis-Felder in gewohnter Weise.
Hinweis: Das jeweilige Plugin muss aktiviert sein, um funktionieren zu können.
Der Tabellenname
Der Tabellenname kann komplett ausgeschrieben werden:
select id as value, title as label from j4_content limit 10
oder unter Verwendung des Joomla Platzhalters #__ für den Tabellen-Prefix:
select id as value, title as label from #__content limit 10
Aufgepasst
Das SQL-Statement wird in einer Textarea eingegeben. Der Inhalt von Textareas wird aber von Joomla beim Speichern prozessiert und gefiltert.
Daher müssen Sie unbedingt folgende Punkte beachten. Das Statement darf:
- An keiner Stelle die Kombination von < > enthalten.
Selbst dann nicht, wenn eine Menge Text zwischen den beiden Klammern steht. - Kein Zeichen < enthalten.
Formen Sie Ihr Statement notfalls um, sodass Sie > anstelle von < verwenden können.
Aus where F5 < 100 wird etwa where 100 > F5. - Keine Zeilenschaltung enthalten.
- Keine Tabulatoren enthalten.
- Keine 2 oder mehr direkt aufeinanderfolgende Leerzeichen enthalten.
Platzhalter im SQL
Sie können in Ihrem SQL-Select-Statement Platzhalter verwenden, die zur Laufzeit mit realen Werten ersetzt werden.
Die Platzhalter können aus den folgenden Joomla-Objekten sein:
- aus dem Joomla User-Objekt, das unter anderem die Informationen über den Joomla Benutzers enthält oder
- aus dem Joomla Input-Objekt, das unter anderem die aktuellen Formulardaten enthält.
Platzhalter des Joomla User-Objekts
Das Joomla User-Objekt enthält unter anderem die Informationen des aktuellen Benutzers.
Die Platzhalter des Joomla User Objects haben das Format: ${user:parametername}.
Zum Beispiel ${user:id} für die ID des aktuellen Benutzers.
Die Platzhalter des Input-Objekts
Das Joomla Input-Objekt enthält unter anderem alle Daten, die mit dem POST-Request an das Backend übergeben werden. Ein POST-Request wird durch den Web-Browser gesendet, wenn durch das Formular ein sogenannter AJAX-Aufruf erfolgt oder das Formular abgeschickt wird. Der POST-Request enthält unter anderem alle aktuellen Formulardaten.
Hinweis: Das Joomla Input-Objekt enthält alle aktuellen Formulardaten.
Die Platzhalter des Input-Objekts haben das Format ${input:parametername}.
Sie müssen “parametername” mit dem Namen des Input-Parameters ersetzen, den Sie verwenden wollen.
Die Platzhalter des Input-Objekts für ein Formularfeld
Um den Platzhalter für ein Formularfeld zu schreiben, verwenden Sie das Input-Objekt mit einem Feldnamen: ${input:fieldname}.
Dabei ist <span class="code"fieldname der Name des Feldes dessen Wert sie eingesetzt haben möchten.
Platzhalter für Listen-Felder, die als Array übergeben werden
Formularfelder vom Typ Listbox und Checkbox Gruppe übergeben die Benutzereingaben im POST-Request als ein Array.
Wenn Sie im SQL-Statement einen Platzhalter für einen solchen Parameter verwenden wollen, so müssen Sie eine spezielle Format-Eingabe beachten: ${input:fieldname[]}.
Visforms konvertiert dann automatisch alle Werte dieses Parameters in einen String, sodass sie in der MySql in() Aggregat-Funktion verwendet werden können.
Beispiel
Der Input Parameter select[]=value1 select[]=value2 wird konvertiert zu (“value1”,“value2”).
Er kann folgendermaßen direkt in einer SQL-Where-Bedingung verwendet werden: where fieldname in ${input:select[]}
Moderner Texteditor oder Entwicklungsumgebung
Wir empfehlen Ihnen, das SQL-Statement in einem guten modernen Texteditor oder besser noch, in einer dezidierten Entwicklungsumgebung zu schreiben und auch gründlich zu testen. Möglich ist auch, das SQL-Statement etwa in einer MySql Konsole zu entwickeln und zu testen.
Entfernen Sie ganz am Ende alle Zeilenschaltungen und Tabulatoren und Mehrfach-Leerstellen, die aus Gründen der sehr viel besseren Lesbarkeit bei großen Statements eingefügt sind.
Ersetzen Sie alle gewünschten dynamischen Stellen im Statement mit dem Visforms-eigenen Format für Platzhalter.
Ersetzen Sie das hart-kodierte Tabellen-Prefix mit dem Joomla Platzhalter #__ für den Tabellen-Prefix.
Überführen Sie nun den bereinigten Ausdruck mit Copy&Paste in das Visforms Konfigurationsfeld und testen Sie, ob das SQL-Statement im laufenden Formular wie erwartet funktioniert.
Heben Sie sich den originalen SQL-Ausdruck an geeigneter Stelle auf, um eine spätere Nacharbeit zu erleichtern.
Hinweis: Die Platzhalter für Formularfelder werden nur im laufenden Formular ersetzt. Denn es stehen ohne ein laufendes Formular gar keine Formulardaten zum Ersetzen zur Verfügung.
Hinweis: Das Joomla User-Objekt und das Joomla Input-Objekt haben während Sie das SQL-Feld in der Administration konfigurieren andere Inhalte, als wenn das Formular im Frontend dem Benutzer angezeigt wird. Denn es ist ein Administrator angemeldet und es handelt sich um die Darstellung einer Seite innerhalb der Administration.
Bei der Nutzung des Test-Buttons für das SQL-Statement müssen Sie diesen Umstand beachten und mit festen Werten anstelle der Platzhalter arbeiten.
Der Test Button
Sie können den Test Button direkt neben dem SQL-Eingabefeld verwenden, um Ihr SQL-Statement zu testen.
Bitte beachten Sie aber unbedingt das Folgende.
Wenn Sie Platzhalter in Ihrem Statement verwenden, kann das Ergebnis des Tests in der Administration vermutlich andere Werte oder oft auch eine Fehlermeldung liefern, als während der Verwendung des Feldes im laufenden Formular. Verwenden Sie daher zum Testen in der Administration nicht die finalen Platzhalter im Visforms-Format im SQL-Statement, sondern an deren Stelle sinnvolle konkrete Werte.
Hinweis: Erst bei der Nutzung des laufenden Formulars sollten die finalen Platzhalter enthalten sein.
Joomla ACL
Sie können prinzipiell jedes beliebige SQL-Select-Statement in diesen Feldtypen verwenden und jede Art von Daten selektieren. Damit ist es möglich, auch äußerst sensible Daten anzuzeigen, sofern solche irgendwo in der Datenbank existieren.
Wir haben deshalb eine zusätzliche Benutzerberechtigung geschaffen. Mit dieser Benutzerberechtigung können Sie das Recht ein SQL-Statement anzulegen, auf bestimmte Benutzergruppen begrenzen. Standard für diese Benutzerberechtigung ist nur die Benutzergruppe “Super User”.
Auswirkungen auf gespeicherte Formulardaten
Die Auswahllisten dynamisch zu erzeugen hat Auswirkungen darauf, was mit SQL-Feldtypen gemacht werden kann.
Keine Steuerung der Sichtbarkeit anderer Felder
Es ist nicht möglich, diese Felder dazu zu verwenden die Sichtbarkeit anderer Felder zu steuern. Sie werden daher auch in der Liste “Bedingte Anzeige” in anderen Feldern nicht angezeigt.
Die alte Option ist nicht mehr vorhanden
Angenommen Sie speichern die übermittelten Formulardaten. Dann kann es natürlich passieren, dass die Zuordnung von bereits gespeicherten alten Werten zu der aktuellen neuen Auswahlliste des Feldes nicht mehr möglich ist.
Dies ist insbesondere dann der Fall, wenn sich die Auswahlliste zwischenzeitlich geändert hat und die entsprechende alte Option nicht mehr existiert. Dies wirkt sich beim Editieren von Daten im Frontend aus. Oder, wenn die Benutzereingaben in PDF-Dokumenten verwendet werden sollen.
Wenn Sie übermittelte Daten in der Datenbank speichern, dann speichert Visforms allein den Optionswert. Das Optionslabel wird nicht in der Datenbank gespeichert, sondern in der Feldkonfiguration. Die Information über das Optionslabel wird aber dem Benutzer für seine Auswahl angezeigt. Es ist dann für alte Werte aus der Datenbank eventuell nicht mehr vorhanden, wenn die betreffende Option in der Feldkonfiguration gelöscht oder geändert wurde. Dies kann in der Datenanzeige im Frontend zu unerwarteten Effekten führen.
Hinweis: Deshalb kann es bei SQL-Feldern sehr sinnvoll sein, denselben Wert für Optionswert und Optionslabel zu verwenden.
Zusätzliche Optionen für “Listbox SQL”
Optionenliste nachladen, nachdem der Benutzer eine Eingabe gemacht hat
Angenommen der Benutzer macht gerade Eingaben im Formular im Frontend. Die Auswahlliste eines “Listbox SQL” Feldes kann dynamisch nachgeladen werden, abhängig von den gerade erfolgten Benutzereingaben.
Hinweis: Wenn Sie dieses Feature nutzen, können Sie das entsprechende Feld nicht mehr per "Bedingte Anzeige" ein und ausblenden. Sie können entweder die Option "Relaod erlauben" oder die Option "Bedingte Anzeige" verwenden, aber nicht beide gleichzeitig.
Wenn Sie die Option “Reload erlauben” aktivieren, wird Ihnen eine Listbox eingeblendet. In dieser Liste können Sie festlegen, welche Benutzereingaben ein Nachladen auslösen sollen. Das Nachladen einer Auswahlliste einzustellen, ist vor allem dann sehr sinnvoll, wenn Sie im SQL-Statement des nachgeladenen Feldes die Benutzereingabe als Parameters auswerten.
Mögliche Trigger-Felder
Trigger-Felder sind Felder, bei deren Änderung der Benutzereingabe ein anderes Feld zum Nachladen oder Neuberechnen veranlasst wird. Im Falle von SQL-Feldern wird das hinterlegte SQL erneut ausgeführt. Trigger-Felder werden in der Konfiguration des nachzuladenden Feldes ausgewählt.
Folgende Feldtypen können als Trigger-Felder ausgewählt werden, sofern sie nicht als “Edit Only” Felder konfiguriert sind:
- “Listbox”, “Radiobutton”, “Checkbox Gruppe”
- “Listbox SQL”, “Radiobutton SQL”, “Checkbox Gruppe SQL”.
Beispiel
Sie haben in Ihrer Datenbank Daten zu Urlaubsregionen und für jede Region eine Liste von Hotels. Nachdem der Benutzer sich für eine Urlaubsregion entschieden hat, soll ihm eine Liste der Hotels aus dieser Region zur Auswahl angeboten werden. Dies kann einfach mit 2 “Listbox SQL” Feldern und der Optionen des Nachladens erreicht werden. Nachgeladen wird also die Liste des “Hotel”-Feldes nach jeder Änderung der Auswahl der Urlaubsregion.
Feld verstecken, wenn die Optionenliste leer ist
Es gibt in der Feldkonfiguration von Feldern vom Typ “Listbox SQL” eine zusätzliche Option. Mit dieser Option können Sie das Feld verstecken, wenn die Auswahlliste leer ist. Diese Option gibt es nur, wenn es sich um ein Feld handelt, dessen Auswahlliste nachgeladen wird.
So können Sie sicherstellen, dass die Listbox zur Hotelauswahl aus obigem Beispiel erst angezeigt wird, nachdem der Benutzer eine Urlaubsregion gewählt hat. Denn die Hotel-Listbox enthält nur dann Optionen, wenn eine Auswahl der Urlaubsregion getroffen ist.
Feld als Datenliste anzeigen
Es gibt in der Feldkonfiguration von Feldern vom Typ “Listbox SQL” eine zusätzliche Option “Als Datenliste anzeigen”. Mithilfe dieser Option können Sie erreichen, dass die Daten, die das SQL-Statement zurückliefert, nicht dazu verwendet werden, um eine Listbox daraus zu erzeugen. Die Daten werden in diesem Fall einfach in einer kleinen Datenliste angezeigt.
In diesem Fall kann der Benutzer keine Auswahl treffen. Das Feld hat einen rein informativen Wert und bietet die Möglichkeit, Informationen aus der Datenbank dynamisch zu laden und im Formular anzuzeigen. Angezeigt werden die Werte, die das SQL-Statement für “label” zurückgibt.
Die Option “Reload erlauben” steht Ihnen auch bei der Anzeige dieser Datenliste zur Verfügung.
Keine Feldwert-Neuberechnung beim Daten-Editieren
Wird das SQL-Statement beim Editieren des Datensatzes erneut ausgeführt, verändert sich dadurch eventuell der Feldwert. Wenn Sie diese automatische Neu-Ausführung des SQL-Statements und eine eventuelle Änderung des Feldwertes verhindern möchten, setzen Sie die Option SQL im Form Edit ausführen auf Nein.
Hinweis: Insbesondere SQL-Statements, die mit dem aktuellen Tagesdatum oder aktuellen Mengen/Werten (Auto-Inkrement) arbeiten, können zu ungewollten Ergebnissen führen, falls diese zu einem späteren Zeitpunkt erneut ausgeführt werden.
