YForm

Die Basis

YForm
Formular-Framework und Tabellenverwaltung

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.


Einsatzmöglichkeiten von YForm

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.

Die Struktur von YForm

Ordnerstruktur und Komponenten

Sehen wir uns zunächst die Verzeichnisstruktur des AddOns an. Die wichtigsten Ordner sind:

lib
   yform
      action
      validate
      value
...
ytemplates
   bootstrap
   classic
Felder definieren

Values

Im 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.

Felder überprüfen

Validates

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.

Aktionen nach dem Versand

Actions

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.

Objparams
Formular-Templates und andere Parameter

form_skin

Templates

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.

form_id, form_wrap_class

Klassen, IDs und mehr

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 gesetzt
Eine vollständige Übersicht

Objparams-Referenz

Eine Übersicht der zur Verfügung stehenden Objparams findest Du hier:
Wiki des Xform-Repos auf Github

Feld-Optionen

Grundlegende Syntax

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]|cssclassname
  • text: Dies definiert den Feldtyp
  • name: der interne Feld-Name
  • label: das vor dem Feld sichtbare Label (Feldbeschriftung)
  • defaultwert: Damit kann man einen Standardwert in das Feld setzen
  • no_db: Speichert eine Aktion die Felddaten in die Datenbank, so gibt es hin und wieder Felder, die man nicht gespeichert haben will, z.B. den Wert eines Submit-Buttons
  • cssclassname: Damit kann man dem Feld eine individuelle CSS-Klasse zuweisen

Verschiedene Schreibweisen

Man 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.

Ein Beispielformular mit YForm


Checkbox

Radio-Button

Weitere Felder
//
// - : Uhr
CAPTCHA

User dynamisch als Checkboxen darstellen