Das Community-AddOn YCom setzt das Formular-AddOn YForm voraus, denn es baut auf dessen Funktionen auf und erweitert diese. Man sollte also zunächst das Prinzip von YForm verstanden haben, um mit YCom sinnvoll zu arbeiten.
YForm dient vor allem zur Generierung von Formularen. Formulare sind komplex und ziehen oft umfangreiche Nacharbeit mit sich. YForm versucht, durch flexible Verzahnung der Komponenten möglichst viele dieser Aufgaben zu übernehmen.
YForm bringt nicht nur alle gängigen Feldtypen mit, sondern stellt auch vielfältige Validierungen bereit, Funktionen zum Versand von E-Mails sowie Aktionen, die zum Beispiel Daten in eine Datenbank schreiben oder Weiterleitungen ausführen.
YForm kann aber nicht nur Formulare für das Frontend generieren sowie Formulareingaben per E-Mail versenden oder in eine Datenbank speichern.
Der Admin kann mit Hilfe des Table Managers auch Datenbank-Tabellen "zusammenklicken" und diese - ergänzt z.B. durch Validierungen - im Backend samt Eingabemaske zur Verfügung stellen. Diese automatisch erzeugten Daten-Verwaltungen können dann wiederum den Code für ein dazu passendes Frontend-Formular generieren.
Sehen wir uns zunächst die Verzeichnisstruktur des AddOns an. Die wichtigsten Ordner sind:
lib
yform
action
validate
value
...
ytemplates
bootstrap
classicIm Verzeichnis values sind die PHP-Klassen für die einzelnen Feldtypen abgelegt, z.B. Textarea, Selectfeld, etc. Wenn Du ein ganz individuelles Feld benötigst, kannst Du eine Datei mit der ähnlichsten Felddefinition kopieren und diese Klasse nach Umbenennung für ein eigenes Feld nutzen.
Das Verzeichnis validate enthält – wie der Name schon sagt – Klassen zur Überprüfung von Feldeingaben. Zum Beispiel: Ein Feld darf nicht leer sein, die Mailadresse ist nicht valide, die PLZ muss fünf Ziffern haben, ein eingebener Name ist schon der Datenbank vorhanden, etc.
Die im Verzeichnis actions versammelten Dateien können verschiedenste Aktionen nach dem Abschicken des Formulars ausführen: einen Bestätigungstext anzeigen, Datenbanken anlegen, Daten speichern, SQL-Befehle ausführen, E-Mails versenden, Werte verschlüsseln u.v.m.
Zu fast jeder Value-Datei existiert eine korrespondierende Template-Datei, die das HTML-Markup für das Formularfeld enthält. Durch diese Trennung von Verarbeitungslogik und HTML-Output kann man "Themes" für YForm nutzen und auch eigene erstellen.
YForm kommt mit einem Default-Skin und einem Bootstrap-Skin, wobei letzteres gleich das von Bootstrap benötige Markup ausliefert. Möchte man das Bootstrap-Skin für ein Formular nutzen, kann man dieses so zuweisen:
objparams|form_skin|bootstrap
Wenn man sich die Ordnerstruktur ansieht, so erkennt man, dass man Yform flexibel selbst erweitern kann: Man legt einen eigenen Theme-Ordner an und erstellt für die gewünschten Felder eigene Template-Dateien an. Bei allen Feldern, die keine eigene Template-Datei bekommen, wird das Template des Default-Themes (classic) verwendet.
Außer der Möglichkeit, einem Formular ein Theme zuzuweisen, kann man mit den objparams noch viele weitere, das ganze Formular betreffende Einstellungen vornehmen. Sie alle folgen dem Schema:
objparams|key|newvalue
Einige Beispiele:
submit_btn_show | default=1 / mit “0” wird der Standard-Submitbutton versteckt, wenn man z.B. eigene Buttons definiert hat
form_method | default=post, kann auf “get” gesetzt werden
form_anchor | default="" / man kann einen Anker in der Formular-Aktion definieren, damit der Browser nach dem Abschicken zur Position des Formulars springt
form_show | default=1 / Formular anzeigen oder nicht
real_field_names | default = 0. Mit dem Wert auf 1 werden exakt die Feldnamen der Formulardefinition im Formular gesetztEine Übersicht der zur Verfügung stehenden Objparams findest Du hier:
Wiki des Xform-Repos auf Github
Nach der Installation von YForm kann man im AddOn mit einem Mausklick ein YForm-Modul anlegen, in das man lediglich die Values, Validierungen und Aktionen tippen muss. Die genaue Syntax findest Du im Modul.
So könnte man ein Textfeld anlegen, in der Zeile darunter wird ein Selectfeld definiert, danach folgt eine Aktion, um die Daten in die Datenbank "adressen" zu speichern:
text|name|Nachname
select|anrede|Anrede|Anrede=,Frau=w,Herr=m
action|db|adressen|Man sieht, dass die einzelnen Optionen jeweils durch ein Pipe-Symbol (vertikaler Strich) abgetrennt sind. Die vollständigen Optionen für jedes Feld kann man direkt im YForm-Modul ersehen. Beim Textfeld findet man beispielsweise folgende Optionen:
text|name|label|defaultwert|[no_db]|cssclassnameMan muss nicht das YForm-Modul verwenden, sondern kann auch die PHP-Schreibweise verwenden:
action|db|adressen|
$yform = new rex_yform();
$yform->setValueField('text', array("name","Nachname"));
$yform->setValueField('select', array("anrede","Anrede","Anrede=,Frau=w,Herr=m"));
$yform->setActionField('db', array('adressen'));
echo $yform->getForm();Tipp: Bei einer mit dem Table Manager angelegten Tabelle kann man sich den Formular-Code in den Versionen PHP (hilfreich bei eigenen Anpassungen), Pipe (im YForm-Modul verwendet) und E-Mail (für den Versand mit Email-Templates) generieren lassen.
Der zweite der folgenden Screenshots zeigt Beispieleingaben für ein Formular.
