Achtung!

Der Webbaukasten wird nicht mehr aktiv betreut und nicht mehr weiter entwickelt. Verwenden Sie stattdessen das CMS-Angebot des RRZE.
Die Dokumentation des CMS-Angebotes finden Sie auf der Website wordpress.rrze.fau.de.

Inhalt

1. Einleitung

Das Formular-Plugin dient zum Erstellen, Absenden, Validieren und Weiterverarbeiten von Formularen. Das Plugin hat eine Reihe von Einstellungsoptionen. Beim Absenden des Formulars, überprüft das Plugin die Vollständigkeit und die Richtigkeit der ausgefüllten Felder. Bei einem Fehler werden die fehlenden oder falsch ausgefüllten Felder markiert. Ist die Überprüfung erfolgreich, werden die Eingabedaten an den Besitzer des Webauftritts per E-Mail versendet ggf. bekommt der Nutzer eine vorkonfigurierte E-Mail-Nachricht.
Die Daten können je nach Bedarf in einer CSV-Datei gespeichert werden.

nach oben

2. Vorbereitung

Um das Formular-Plugin in eine shtml-Datei einbinden zu können ist es notwendig die folgende Zeile in die Datei websource/.htaccess hinzufügen. (Wenn die Datei noch nicht existiert, soll diese neu erstellt werden):

Options +Includes
                        

Optional werden die Formulareinträge in einer csv-Datei im Ordner vkdaten/tools/formular/eintraege/ gespeichert, z.B. vkdaten/tools/formular/eintraege/kontakt-2012.02.01.csv. Um die Auslieferung der csv-Dateien zu verhindern, folgende Zeilen müssen in die Datei websource/.htaccess geschrieben werden:

<Files ~ "\.csv$">
Order deny,allow
deny from all
</Files>
                        

Dieses Plugin unterstützt die Zeichenkodierung UTF-8. Deswegen werden die Konfigurations-, Vorlagen- u. CSV-Dateien vom Plugin UTF-8 kodiert.

nach oben

3. Download

Laden Sie sich die neueste Version des Formular-Plugins herunter und speichern Sie die entpackten Dateien anschließend im Ordner vkdaten/tools/formular/

nach oben

4. Einbindung

Fügen Sie folgende Zeile im Body-Bereich des HTML-Codes ein:

<!--#include virtual="/vkdaten/tools/formular/formular.php?referer=${DOCUMENT_URI}&conf=konfigurationsdateiname" -->
                        

Wobei "konfigurationsdateiname" der Name der Konfigurationsdatei ohne .conf-Endung bezeichnet.

Beispiel:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"  lang="de">
    <head>...</head>
    <body>
    ...
    <!--#include virtual="/vkdaten/tools/formular/formular.php?referer=${DOCUMENT_URI}&conf=kontakt" -->
    ...
    </body>
</html>
                        

nach oben

5. Vorlagendateien

Das Formular sowie auch die Bestätigungs- und Fehlermeldung des Formulars verfügen über verschiedenen Vorlagen.

Die Vorlagendateien müssen im Ordner vkdaten/tools/formular abgelegt werden.

Beispiel:

vkdaten/tools/formular/kontakt-form.html
vkdaten/tools/formular/kontakt-success.html
                        

Formularvorlage

Die Formularvorlagen sind flexibel und lassen sich leicht anpassen. Sie enthalten den HTML-Code und die Felder- oder Fehlervariablen.

Beispiel: Format

{form_open}
...
{Feldname1}
{Feldname1_error}
{Feldname2}
{Feldname2_error}
...
{form_submit}
{form_close}
                        

Beispiel: Format einer Feldvariable:

{Feldname}
                        

Beispiel: Format einer Fehlervariable zur fehlenden oder falschen Dateneingabe:

{Feldname_error}
                        

War das Absenden des Formulars erfolgreich, wird eine ensprechende Vorlage mit der Absendebestätigung gezeigt. Schlägt das Absenden der Formulardaten fehl, erscheint eine Vorlage mit entsprechenden Fehlermeldungen.

Um zu verhindern, dass das Formualar automatisiert zur Versendung von Spam-Mails verwendet wird, sollte unbedingt ein zusätzliches Captcha-Feld eingebunden werden (siehe Tabelle 1, form_field).

Von besonderem Interesse wird eine E-Mail-Vorlage für den Benutzer sein. In dieser Vorlage kann eine individuelle E-Mail-Ausgabe an den Empfänger/Absender angepasst werden.

Die E-Mail-Vorlagen werden im Ordner vkdaten/tools/formular abgelegt.

Beispiel:

vkdaten/tools/formular/kontakt-antwort.html
                        

nach oben

6. Konfigurationsdatei

Das Formular-Plugin bietet zahlreiche Optionen, die in einer Konfigurationsdatei zeilenweise (Wichtig: Optionsname und Wert müssen jeweils mit einem Tabulator getrennt sein!) gespeichert werden können. Ein Wert kann ein oder mehrere Parameter (jeweils mit dem Zeichen | getrennt) enthalten. Mehrere Werte eines Parameters müssen mit einem Semikolon ( ; ) getrennt werden (Ausnahme Feld form_field, Option Extra: hier wird einfach der gesamte einzufügende Text, ggf. mit Leerstellen, angegeben).

Beispiel:

form_field	checkbox|interessen|Pop;Folk;Jazz;Schlager;Klassik|trim;required
                        

Die Konfigurationsdatei eines Formulars muss im Ordner vkdaten/tools/formular abgelegt werden.

Beispiel:

vkdaten/tools/formular/konfigurationsdateiname.conf
                        

nach oben

7. Optionen

Tabelle 1 - Übersicht der verfügbaren Optionen

Optionsname Optionswert

cvs_entries

1

Die Formulareinträge werden in einer CSV-Datei gespeichert, wenn nicht dann hat die Option den Wert 0.

Die CSV-Dateien werden im Ordner vkdaten/tools/formular/eintraege gespeichert.

email_receiver

Name|E-Mail-Adresse

Die Option E-Mail-Empfänger hat folgende Werte:
Name - Name des Empfängers
E-Mail-Adresse - E-Mail-Adresse des Empfängers
Beispielsweise:

email_receiver	Web-Abteilung|franz.musterman@rrze.fau.de

Mehreren Namen (z.B. Vor- und Nachname) werden mit einem Semikolon getrennt. Beispielsweise:

email_receiver	Franz;Musterman|franz.musterman@rrze.fau.de

email_subject

Betreff

E-Mail-Betreff, z.B.:

email_subject	Kontakt

email_sender

Absenderfeldname|E-Mail-Feldname

Die Option E-Mail-Absender hat folgende Werte:
Absenderfeldname - Feldname bzw. Semikolon getrennte Feldnamen
des Absenders
.
E-Mail-Feldname - Feldname der Absender-E-Mail-Adresse (Vorname und Nachname werden mit einem Semikolon getrennt).
Beispielsweise:

email_sender	name|email

Mehreren E-Mail-Feldnamen werden mit einem Semikolon getrennt. Beispielsweise:

email_sender	vorname;nachname|email

email_views

Eintragdateiname|Antwortdateiname

Die Option E-Mail-Vorlagendateien hat folgende Werte:
Eintragdateiname - Name der Eintragdatei (ohne .html-Endung). Enthält die E-Mail-Ausgabe an den Empfänger.
Antwortdateiname (optional) - Name der Antwortdatei (ohne .html-Endung). Enthält die E-Mail-Ausgabe an den Absender.
Beispielsweise:

email_views	kontakt-emaileintrag|kontakt-emailantwort

form_views

Formulardateiname|Success-Dateiname|Error-Dateiname|Lock-Dateiname

Die Option Formular-Vorlagendateien hat folgende Werte:
Formulardateiname - Name der Vorlagendatei des Formulars (ohne .html-Endung).
Success-Dateiname (optional) - Name der Vorlagendatei für die erfolgreiche Absendung-Bestätigung (ohne .html-Endung).
Error-Dateiname (optional) - Name der Vorlagendatei für die fehlgeschlagene Absendung-Meldung (ohne .html-Endung).
Lock-Dateiname (optional) - Name der Vorlagendatei für die schon bereits abgesendete Formularmeldung (ohne .html-Endung).
Beispielweise:

form_views     kontakt-form|kontakt-success

form_error

Präfix-Tag|Suffix-Tag

Fehlermeldungstil (optional). Beispielsweise:

form_error	<b>|</b>

form_field

Eingabeart|Feldname|Standardwert|Feldregeln|Extra

Mit dieser Option kann ein Formelement erstellt werden.
Die Option hat folgende Werte:
Eingabeart - Art des Formularelementes (hidden, input, textarea, checkbox, radio, dropdown, upload und captcha).
Feldname - Name des Formularelementes.
Standardwert - Werte, die angezeigt werden. Einzelwert (kann auch leer bleiben, z.B. bei input, textarea, upload) bzw. Semikolon getrennte Werte (z.B. bei checkbox, radio, dropdown). Bei dropdown wird der erste Wert nur angezeigt und nicht als gewählte Option gespeichert (hier z.B. "Bitte wählen..." eingeben)..
Feldregeln (optional) - Semikolon getrennte Feldregeln bzw. Vorverarbeitungsfunktionen (siehe Tabelle 2).
Extra (optional) - Text, der zusätzlich innerhalb des Formularelement-HTML-Codes eingefügt wird. Die Angaben sind daher abhängig vom Typ des Formularfeldes.
Beispielsweise:

form_field     input|name||trim;required;xss_clean|size="40"
form_field     radio|schon_gekauft|Ja;Vielleicht;Nein, noch nie|trim;required
form_field     dropdown|liebling|Louis Armstrong;Heino;Sting|trim;required
form_field     textarea|zusatz||trim;required;xss_clean|cols="50" rows="10"
form_field     checkbox|interessen|Pop;Folk;Jazz;Schlager;Klassik|trim;required
form_field     upload|datei||required
form_field     captcha|captcha||trim;required;valid_captcha;xss_clean|autocomplete="off"

Wichtig: Wenn die Eingabeart upload genutzt wird, dann müssen die Optionen file_allowed_types und file_max_size festgelegt werden. Die hochgeladene Dateien werden im Ordner vkdaten/tools/formular/anlagen gespeichert.

file_max_size

n > 0

Max. Größe der Datei in kB. Beispielsweise:

# 102400 kB (100 MB)
file_max_size	102400
                                    

file_allowed_types

Dateitype-1|Dateitype-2|Dateitype-3 ...

Erlaubte Dateitypen. Beispielsweise:

file_allowed_types	png|jpg|zip

rules_messages

Feldregel-1;Feldregelmeldung-1|Feldregel-2;Feldregelmeldung-2 ...

Ändert die Standard-Feldregelmeldungen. Beispielsweise:

rules_messages	required;Bitte beantworten Sie diese Frage.

email_notification

0

Diese Option ist für Umfrageformulare gemeint um die Befragung anonym durchführen können, wenn nicht dann hat die Option den Wert 1.

cookie_lock

1

Diese Option ist für Umfrageformulare gemeint um Mehrfachsendungen des Formulars zu verhindern, wenn nicht dann hat die Option den Wert 0.

nach oben

Tabelle 2 - Liste der verfügbaren Feldregeln

Regel Parameter Beschreibung Beispiel
required Nein Das Feld wird benötigt.
not_empty Nein Das Feld muss einen nicht-leeren und von 0 verschiedenen Wert enthalten.
valid_email Nein Das Feld muss eine gültige E-Mail Adresse enthalten.
allowed_emails Ja Die angegebene E-Mail-Adresse muss die zugelassene E-Mail-Domäne bzw. -Adressen stimmen. allowed_emails[rrze.fau.de, erika.musterman@mustersite.de]
min_options Ja Das Feld muss eine mindeste Anzahl von ausgewählte Optionen enthalten (für Dropdown-Listen geeignet). min_options[2]
max_options Ja Das Feld darf eine maximal Anzahl von ausgewählte Optionen enthalten (für Dropdown-Listen geeignet). max_options[4]
min_length Ja Das Feld muss eine mindeste Anzahl von Zeichen enthalten. min_length[6]
max_length Ja Das Feld darf eine maximal Anzahl von Zeichen enthalten. max_length[12]
exact_length Ja Das Feld muss eine genaue Anzahl von Zeichen enthalten. exact_length[8]
alpha Nein Das Feld darf nur Buchstaben enthalten.
alpha_numeric Nein Das Feld darf nur Buchstaben und/oder Zahlen enthalten.
alpha_space Nein Das Feld darf nur Buchstaben, Zahlen und/oder Leerzeichen enthalten.
numeric Nein Das Feld darf nur Zahlen enthalten.
is_numeric Nein Das Feld darf nur numerische Zeichen enthalten.
integer Nein Das Feld darf nur eine Ganzzahl enthalten.
is_natural Nein Das Feld darf nur positive Zahlen enthalten.
is_natural_no_zero Nein Das Feld muss eine Zahl größer als 0 enthalten.
matches Ja Das Feld muss mit dem Feld des Parameters übereinstimmen. matches[Feldname]
valid_captcha Nein Das Feld muss mit dem Wert im angezeigten Captcha-Bild übereinstimmen.

nach oben

Tabelle 3 - Liste verfügbaren Vorverarbeitungsfunktionen

Funktion Parameter Beschreibung
trim Nein Entfernt Leerzeichen am Anfang und Ende der Zeichenkette-Eingabe.
xss_clean Nein Durchführung der Daten durch die XSS-Filter-Funktion

Beispiel der Nutzung der Vorverarbeitungsfunktionen:

form_field	input|vorname||trim;required;xss_clean
form_field	dropdown|liebling|Louis Armstrong;Heino;Michael Jackson;Tom Waits;Nina Hagen;Marianne Rosenberg|trim,required
                        

nach oben