Dokumentation FormBuilder
Aus DeDi-Help
Der FormBuilder ist ein Modul für das Open Source CMS "Der Dirigent" und ermöglicht es, auf einfache Weise Formulare mit beliebigen Elementen zu erstellen, diese auszuwerten und die eingegebenen Daten an eine E-Mail Adresse oder eine andere url zu versenden. Die folgenden Seiten beschäftigen sich mit der grundsätzlichen Konfiguration des Moduls, weitergehenden einzelnen Einstellungsmöglichkeiten und ausgewählten Anwendungsbeispielen.
[bearbeiten] Grundlegende Einstellungen
Zuerst werde ich auf die Konfiguration des Moduls eingehen. Ich gehe davon aus, dass folgende Vorraussetzungen gegeben sind.
- installiertes, lauffähiges DeDi System
- php 4.1 oder höher
- mit mcrypt Unterstützung
Wenden wir uns nun der Erstellung der einzelnen Formularfelder zu.
[bearbeiten] Die Konfiguration der Formularelemente
Hier gehe ich kurz auf die vorhandenen Felder uns Ihre Bedeutung ein.
[bearbeiten] Nummer
Hier wird die laufende Nummer des Feldes angezeigt, welches bearbeitet wird.
[bearbeiten] mögliche Elemente
Es stehen folgende Elemente zur Verfügung.
- Textzeile
- Textarea
- Checkboxen (Mehrfachauswahl möglich)
- Radiobutton
- Liste
- Dropdown-Liste
- multiple Liste (Mehrfachauswahl möglich)
- verstecktes Feld
Auf eine weitergehende Erklärung der Elemente verzichte ich an dieser Stelle.
[bearbeiten] Name und id
Vergeben Sie hier einen eindeutigen(!) Namen für das Formularfeld. Dieser wird später für die Templateerstellung benötigt und gleichzeitig als name und id des Formularelements verwendet. Der Wert emp_mail sollte nur mit Bedacht verwendet werden (siehe 2.1.2.). Der Wert fbantispamcheck ist dem Anti-Spam Schlüssel zugeordnet und sollte daher nicht benutzt werden.
[bearbeiten] Default
Hier kann der default-Wert des Formulars eingetragen werden. Dieser wird bei Aufruf immer ausgewählt. Bei Auswahlelementen ist hier stets der value-Wert (siehe 1.1.4.) einzutragen. Bei Formularelementen mit multipler Auswahl (multiple Liste und Checkboxen) können auch mehrere default-Werte in der Form
a|b|c
angegeben werden.
[bearbeiten] Option / Value
Hier sind bei Auswahlelementen die verschiedenen Wahlmöglichkeiten zu definieren. Dies geschieht in der Form
option1=value1|option2=value2
Im Value-Teil sollten keine Sonderzeichen verwendet werden.
[bearbeiten] Validierung
Hier können Sie festlegen, ob die Eingaben des Users auf bestimmte Kriterien hin überprüft werden sollen. Es stehen folgende Möglichkeiten zu Wahl:
- nicht leer > Es muss eine Eingabe erfolgen.
- Postleitzahl > Es wird geprüft, ob eine fünfstellige Zahl eingegeben wurde.
- E-Mail > Es wird geprüft, ob eine syntaktisch korrekte E-Mail Adresse eingetragen wurde. Möglich ist hier auch eine Überprüfung darauf, ob ein entsprechender MX, A oder CNAME Eintrag für die angegebene Domain existiert. Dazu mehr unter Punkt 1.2.6.
[bearbeiten] Attribute
Hier können Sie den einzelnen Formularelementen weitere Attribute wie z.B. maxlength, size, etc. hinzufügen. Dies ist insbesondere interessant, wenn Sie das Formular barrierefrei gestalten wollen. Einträge erfolgen durch Leerzeichen getrennte in der Form maxlenght=40 size=40
[bearbeiten] CSS
Hier können Sie den einzelnen Elementen eine CSS-Klasse(!) zuweisen. Diese müssen im Vorfeld erstellt worden sein. Die Formatierung der Beschriftung der Elemente erfolg später.
[bearbeiten] Die Moduleinstellungen
Nun werde ich die Einstellungen und Möglichkeiten des Modul näher beschreiben.
[bearbeiten] versenden an
Hier können Sie festlegen, was mit den Daten nach absenden des Formulars geschehen soll. Es gibt folgende Optionen:
- E-Mail > Die Daten werden per E-Mail an eine später angegebene (1.2.2.) E-Mail Adresse versendet.
- idcatside > Die Daten werden an eine Seite innerhalb Ihres DeDi Projekts versendet. Die idcatside der jeweiligen Seite finden sie im Menü unter Redaktion > Seiten im Info-PopUp
- url > Die Daten werden an eine url außerhalb ihres DeDi Projekts versendet. Zu beachten ist darüber hinaus, das die Daten aus Formularelementen mit multipler Auswahlmöglichkeit (Checkboxen und multiple Listen) immer als numerisches Array übergeben werden. Dies ist besonders für das Auslesen der Daten auf einer anderen Seite von Bedeutung.
[bearbeiten] E-Mail Adresse, idcatside oder url
Hier definieren Sie bitte das genaue Ziel, an das die Daten gesendet werden sollen. Beachten Sie, dass Ihre Angabe mit den unter Punkt 1.2.1. gemachten vereinbar sein muss. Die Angaben erfolgen in der den unter Punkt 1.2.1. vorgenommen Einstellungen entsprechenden Form:
- E-Mail mail@domain.de
- idcatside 99
- url http://www.meinedomain.de
[bearbeiten] Kontrollseite gewünscht
Hier können Sie festlegen, ob der User die Möglichkeit haben soll nach Eingabe der Daten diese noch einmal zu sehen und ggf. Änderungen vorzunehmen.
Wenn die Kontrollseite nicht aktiviert ist, kann das Formular ohne Inhalt oder mit ungeprüftem Inhalt verschickt werden.
[bearbeiten] Absenderadresse
Hier können Sie festlegen, aus welchem Formularelement die Absenderadresse der versendeten E-Mail entnommen werden soll.
[bearbeiten] Titel der E-Mail
Hier können Sie den Titel / Betreff definieren, den die versendete E-Mail tragen soll.
[bearbeiten] Domain der Absendermail prüfen
Hier können Sie die Überprüfung von E-Mail Adressen einschränken, so dass eine eingegebene Adresse lediglich auf korrekte Syntax überprüft wird. Sollte Sie eine Windows Server verwenden wird die Deaktivierung einer weitergehenden Prüfung wohl unumgänglich sein, da diese Funktion bisher nur für Linux-Systeme integriert ist.
Nehmen Sie hier die Einstellung "aktiviert" vor, werden alle Eingaben in Formularelemente für die eine E-Mail Validation definiert ist auf die Existenz eines MX, A oder CNAME Eintrags für die entsprechende Domain überprüft.
[bearbeiten] Anti-Spam Key und Wert
Um Missbrauch des Formular vorzubeugen wurde hier eine Methode implementiert, die sicherstellen soll, dass das komplette Formular Seite für Seite abgearbeitet wurde, und nicht lediglich der Teil, welcher abschließend die E-Mail versendet direkt aufgerufen wird. Da der FormBuilder - wie später klar werden sollte - auch mit variablem Empfängeradressen umgehen kann besteht ansonsten die Gefahr des Missbrauchs des Formulars für Spamming.
Bitte gegen Sie in beiden Feldern einen zufälligen(!) Wert aus Buchstaben, Zahlen und Sonderzeichen ein. Beim Aufruf des Formulars wird der von Ihnen eingegebene Anti-Spam Wert zusammen mit dem aktuellen Timestamp verschlüsselt, und zusammen mit einem 10 stelligen Schlüssel in der Datenbank (prefix_content_external) abgelegt. Dieser Schlüssel wird nun im Formular versteckt mit gesendet. Direkt vor dem eigentlichen Versenden der E-Mail wird nun geprüft, ob es einen zu dem Schlüssel passenden Wert in der Datenbank gibt. Dies ist nur der Fall, wenn das eigentliche Formular besucht wurde.
Nach dem Versenden der E-Mail wird der zugehörige Schlüssel wieder gelöscht, so dass für eine erneute E-Mail wieder die Startseite besucht werden muss. Damit sich nicht etliche Schlüssel von Besucher die das Formular angesehen aber letztendlich keine E-Mail geschrieben haben in der Datenbank sammeln werde diese nach 24 Stunden beim nächsten E-Mail Versand automatisch gelöscht.
[bearbeiten] Schriftarten zur Templategestaltung
Hier können Sie CSS-Klassen auswählen, mit denen Sie später die Anzeigetemplates gestalten möchten
[bearbeiten] Schriftart für Fehlermeldungen
Hier wird die CSS-Klasse definiert, die auf Fehler- bzw. Warnmeldungen des FormBuilder (fehlerhafte Eingaben / falsche Anti-Spam Wert) angewandt werden soll
[bearbeiten] Schriftart für Checkboxen / Radiobutton
Definieren Sie hier eine CSS-Klasse für die Beschriftung von Radiobutton und Checkboxen. Die Beschriftung wird entsprechend des angegebenen Option-Wertes für das zugehörige Element angezeigt.
[bearbeiten] CSS-Klasse für Button
Hier können Sie eine CSS-Klasse für die Button "Daten senden", "Daten ändern" und "Daten zurücksetzen" definieren.
[bearbeiten] Die Konfiguration der Templates
Wenden wir uns nun der Bedeutung und Konfiguration der einzelnen Templates zu.
[bearbeiten] Template für Formulardesign
Hier müssen einfach die vorher definierten Elementnamen eingeschlossen in {} an die gewünschten Stellen im HTML Code gesetzt werden. Zusätzlich noch die Button
- {bs} => Button zum senden
- {br} => Button zum zurücksetzen der Daten einbinden.
Hier können Sie auch Fieldsets bestimmen, wenn dies gewünscht ist. Eine Vorlage für ein mögliches Design finden Sie direkt in den Standardeinstellungen des Moduls.
[bearbeiten] Template für Design der Kontrollseite
Hier müssen ebenfalls die vorher definierten Elementnamen eingeschlossen in {} an die gewünschten Stellen im HTML Code gesetzt werden. Diese Einstellungen werden natürlich nur benötigt, wenn die Kontrollseite aktiviert ist. Zusätzlich noch den
- {bs} => Button zum senden
- {bb} => Button zum ändern der Daten
einbinden. Auch hier finden Sie ein Beispiel direkt in den Standardeinstellungen des Moduls.
[bearbeiten] Template für Design der E-Mail
Auch hier alle zu senden Elementnamen eingeschlossen in {} positionieren. In diesem Template bitte kein HTML verwenden, da die E-Mail als Textmail versendet wird. Zeilenumbrüche und sonstige Einträge im Template werden in den Text der E-Mail übernommen. Auch hier finden Sie ein Beispiel direkt in den Standardeinstellungen des Moduls.
[bearbeiten] Template für Erfolgsmeldung nach E-Mail Versand
Hier definieren Sie eine Meldung für den Fall des erfolgreichen Versands der E-Mail in HTML. Auch hier finden Sie ein Beispiel direkt in den Standarteinstellungen des Moduls.
[bearbeiten] Spezielle Möglichkeiten und Beispiele
Neben den beschriebenen grundlegenden Funktionen bietet das Modul einige Features, die einen vielseitigeren und dynamischeren Einsatz ermöglichen. Auf einige solche Funktionen geht diese Dokumentation im Folgenden näher ein.
[bearbeiten] Dynamische Erstellung von Formularinhalten
Besonders bei der Verwendung von Formularelementen mit umfangreichen und wechselnden Auswahlmöglichkeiten (Checkboxen, Listen etc.) kann es hilfreich sein die zur Auswahl stehenden Optionen dynamisch erzeugen zu lassen. Hierzu zwei praktische Bespiele:
[bearbeiten] Erstellung einer Datumsauswahl
Möchte man zum Beispiel eine Datumsauswahl erzeugen, wäre es relativ aufwendig alle Tage und Monate als Optionen von Hand einzutragen. Einfacher ist es die gewönschten Daten durch PHP Code im Sourcecode Feld der Modulkonfiguration erstellen zu lassen. Der in diesem Feld eingetragene Code wird vor dem Aufbau des eigentlichen Formulars ausgeführt. Er darf nicht von <?php ?> eingeschlossen sein.
[bearbeiten] Textarea Sourcecode vor Modulausführung
Im Konfigurationsbereich "Sourcecode vor Modulausführung" notieren wir unseren php-Code, der die entsprechenden Werte generiert. In der for-Schleife werden die einzelnen Angaben aneinandergereiht. Anschließend wird das unnötige | Zeichen am Ende des Strings entfernt.
Die jeweiligen Variablen werden dann einfach anstelle der Eingaben in der Definition des Elements eingesetzt. Auf diese Weise lassen sich leicht auch umfangreichere Auswahlmöglichkeiten schaffen. Natürlich ist auch jeder andere PHP Code in der Sourcecode Textarea erlaubt.
[bearbeiten] Elementdefinition
Nun müssen wir noch die Elementdefinitionen anpassen. Hierzu tragen wir einfach bei "Option / Value" die entsprechende Variable ein und vergeben eindeutige Namen für die Elemente.
for($t=1;$t<32;$t++)
{
$tage .=''.$t.'='.$t.'|';
}
$tage = substr($tage,0,strlen($tage)-1);
for($m=1;$m<13;$m++)
{
$monate .=''.$m.'='.$m.'|';
}
$monate = substr($monate,0,strlen($monate)-1);
for($j=2004;$j<2020;$j++)
{
$jahre .=''.$j.'='.$j.'|';
}
$jahre = substr($jahre,0,strlen($jahre)-1);
Der Formbuilder kann auf diese Weise auch mit Daten aus einer Datenbank versorgt werden. Dies hat den Vorteil, dass die Elementdefinitionen auch bei sich schnell ändernden Daten nicht ständig angepasst werden muss.
[bearbeiten] Das Ergebnis
Nachdem wir nun noch die Templates angepasst haben könnte das ganze im Frontend so aussehen.
[bearbeiten] Variabler E-Mail Empfänger
Im nächsten Beispiel soll der Empfänger der E-Mail vom Benutzer gewählt werden können. Die E-Mail Adresse, an die die Daten versendet werden ist in der Variable $emp_mail gespeichert. Die zur Wahl stehenden Empfänger sind in diesem Beispiel Benutzer aus der Tabelle dedi_users. In der Sourcecode Textarea muss also die Datenbank hierauf hin abgefragt werden.
[bearbeiten] Textarea Sourcecode vor Modulausführung
Im Konfigurationsbereich "Sourcecode vor Modulausführung" notieren wir unseren php-Code, der die entsprechenden Werte auslesen soll.
$sql = "SELECT name, surname, email FROM ". $dedi_
db[users] ." WHERE is_deletable = 1 ORDER BY surname";
$db->query($sql);
while ($db->next_record())
{
$daten .= "".$db->f("surname").",".$db-
>f("name")."=".$db->f("email")."|";
}
$daten = substr($daten,0,strlen($daten)-1);
[bearbeiten] Elementdefinitionen
Im der Elementdefinition wird die Liste der potentiellen Empfänger mit emp_mail benannt. Ist dieser Elementname vergeben, wird die in der Templatekonfiguration eingegebene Einstellung automatisch überschrieben.
Die Variable $daten, welche die Auswahl der Liste enthält, wird wie gewohnt in die Elementdefinition eingebunden.
[bearbeiten] Das Ergebnis
Nach Anpassung der Templates sieht das ganze dann zum Beispiel so aus. Nun kann der Benutzer festlegen, an wen die E-Mail gehen soll.
[bearbeiten] weiteres Wissenswertes
Nun noch eine kleine Ergänzung zur Benutzung der Sourcecode Textarea. Soll der PHP Code nur an bestimmten Stellen des Ablaufs ausgeführt werden kann dies durch folgende if - Abfragen beeinflusst werden.
- if (!$validate && !$back && !$submit){ /* bei Aufruf des Formulars */ }
- if ($validate){ /* auf der Kontrollseite */ }
- if ($back){ /* bei Änderung der Daten */ }
- if ($submit){ /* auf der Seite der Erfolgsmeldung */ }
Alle anderen Möglichkeiten sollten sich hieraus ergeben. Ich hoffe, ich konnte mit dieser kleinen Anleitung die Funktionsweise des FormBuilders ein wenig transparenter gestalten. Vielleicht kann der Eine oder Andere ihn ja gebrauchen?
Wer Fragen oder Anregungen zum Formbuilder hat kann sich gerne per PM im Forum bei mir melden. Viel Spaß mit dem Modul!
Stand: 08.11.2004 (bearbeitet von mika am 06.04.05)
für FormBuilder: v1.21
Doku-Version: v1.21.01
