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.

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.

3. Download

Laden Sie sich die Datei Formular-Plugin Version 1.12.0330 herunter und speichern Sie die entpackten Dateien anschließend im Ordner vkdaten/tools/formular/

4. Einbindung

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

<!--#include virtual="/vkdaten/tools/formular/formular.php?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" xml:lang="de" lang="de">
    <head>...</head>
    <body>
    ...
    <!--#include virtual="/vkdaten/tools/formular/formular.php?conf=kontakt" -->
    ...
    </body>
</html>

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.

Von besonderem Interesse wird eine E-Mail-Vorlage für den Benutzer sein. In dieser Vorlage kann 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

6. Konfigurationsdatei

Das Formular-Plugin bietet zahlreiche Optionen, die in einer Konfigurationsdatei zeilenweise (Optionsname und Wert jeweils mit Tabulator getrennt) 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.

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

7. Optionen

Übersicht der verfügbaren Optionen

Optionsname Optionswert Beschreibung/Erklährung

cvs_entries

1

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

cookie_locked

1

Mehrfachabsendungen des Formulars werden verhindert, wenn nicht dann hat die Option den Wert 0.

email_receiver

Name|E-Mail-Adresse

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

email_receiver	Web-Abteilung|franz.musterman@rrze.uni-erlangen.de

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

email_receiver	Franz;Musterman|franz.musterman@rrze.uni-erlangen.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|Locked-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).
Locked-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

Mit dieser Option kann ein Formelement erstellt werden.
Die Option hat folgende Werte:
Eingabeart - Art des Formularelementes (input, textarea, checkbox, radio, dropdown).
Feldname - Name des Formularelementes.
Standardwert - Einzelwert (kann ein Leerzeichen sein) bzw. Semikolon getrennte Werte, z.B. für ein dropdown-Formularelement.
Feldregeln (optional) - Semikolon getrennte Feldregeln bzw. Vorverarbeitungsfunktionen (siehe Tabelle "Feldregeln" unten!).

rules_messages

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

Ändert die Standard-Feldregelmeldungen. Beispielsweise:

rules_messages	required;Bitte beantworten Sie diese Frage.

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.
valid_url Nein Das Feld muss eine gültige URL enthalten.
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]

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

8. Beispiel 1: Kontaktformular

Erstellung der Konfigurationsdatei (vkdaten/tools/formular/kontakt.conf)

# Kontaktformular

# Formulareinträge in einer CSV-Datei speichern
csv_entries	1

email_receiver	Web-Abteilung|franz.musterman@rrze.uni-erlangen.de
email_subject	Kontakt
email_sender	name|email
email_views	kontakt-emaileintrag|kontakt-emailantwort

form_views	kontakt-form|kontakt-success
form_submit	Absenden|id="submit"
form_error	<p style="font-style:italic; color: red">|</p>

form_field	input|name||trim;required;xss_clean
form_field	input|email||trim;required;valid_email;xss_clean
form_field	textarea|text||trim;required;xss_clean

Erstellung der Vorlagendatei des Formulars (vkdaten/tools/formular/kontakt-form.html)

{form_open}
    <div>
        <fieldset>
            <legend>Kontaktformular</legend>
            <div class="abstand">
                <div class="zeile">
                    <div class="datenart">
                        <label for="name">Name</label>
                        {name_error}
                    </div>
                    <div class="eingabe">
                        {name}
                    </div>
                </div>
                <div class="zeile">
                    <div class="datenart">
                        <label for="email">E-Mail-Adresse</label>
                        {email_error}
                    </div>
                    <div class="eingabe">
                        {email}
                    </div>
                </div>
                <div class="zeile">
                    <div class="datenart">
                        <label for="text">Nachricht</label>
                        {text_error}
                    </div>
                    <div class="eingabe">
                        {text}
                    </div>
                </div>
            </div>
        </fieldset>
        <p>
            {form_submit}
        </p>
    </div>
{form_close}

Erstellung der Formularvorlagen für die erfolgreiche Absendung-Bestätigung (vkdaten/tools/formular/kontakt-success.html)

<div class="hinweis">
    <p>Erfolgreich abgesendet.</p>
    <p>Vielen Dank, für Ihre Anfrage. Wir melden uns bei Ihnen baldmöglichst.</p>
</div>

Erstellung der E-Mail-Vorlagendatei für die E-Mail-Ausgabe des Eintrags (vkdaten/tools/formular/kontakt-emaileintrag.html)

-- Kontaktformular --
Name: {name}
E-Mail-Adresse: {email}
Nachricht: {text}

E-Mail-Ausgabe des Eintrags (Beispiel)

-- Kontaktformular --
Name: Frank Musterman
E-Mail-Adresse: frank.musterman@rrze.uni-erlangen.de
Nachricht: Hallo Welt!

Erstellung der E-Mail-Vorlagendatei für die E-Mail-Ausgabe des Antworts (vkdaten/tools/formular/kontakt-emailantwort.html)

Vielen Dank {name}, für Ihre Anfrage. Wir melden uns bei Ihnen baldmöglichst.

E-Mail-Ausgabe des Antworts (Beispiel)

Vielen Dank Frank Musterman, für Ihre Anfrage. Wir melden uns bei Ihnen baldmöglichst.

9. Beispiel 2: Standardformular

Erstellung der Konfigurationsdatei (vkdaten/tools/formular/standard.conf)

# Standardformular

# Formulareinträge in einer CSV-Datei speichern
csv_entries	1

email_receiver	Franz;Musterman|franz.musterman@rrze.uni-erlangen.de
email_subject	Standardformular
email_sender	vorname;familienname|email
email_views	standard-emaileintrag

form_views	standard-form
form_submit	Absenden|id="submit"
form_error	<p>|</p>

#Angaben zur Person
form_field	input|vorname||trim;required;xss_clean
form_field	input|familienname||trim;required;xss_clean
form_field	input|email||trim;required;valid_email;xss_clean
form_field	input|wohnort||trim;required;xss_clean

# Hast du Schon bei uns gekauft?
form_field	radio|schon_gekauft|Im vergangenen Monat;Im vergangenen Jahr;Nein, noch nie|trim;required

# Deine Musikinteressen
form_field	dropdown|liebling|Louis Armstrong;Heino;Michael Jackson;Tom Waits;Nina Hagen;Marianne Rosenberg|trim;required
form_field	checkbox|interessen|Pop;Folk;Jazz;Schlager;Klassik|trim;required
form_field	textarea|zusatz||trim;required;xss_clean

Erstellung der Vorlagendatei des Formulars (vkdaten/tools/formular/standard-form.html)

{form_open}
    <div>
        <fieldset>
            <legend>Angaben zur Person</legend>
            <div class="abstand">
                <div class="zeile">
                    <div class="datenart">
                        <label for="vorname">Vorname</label>
                        {vorname_error}
                    </div>
                    <div class="eingabe">
                        {vorname}
                    </div>
                </div>
                <div class="zeile">
                    <div class="datenart">
                        <label for="familienname">Familienname</label>
                        {familienname_error}
                    </div>
                    <div class="eingabe">
                        {familienname}
                    </div>
                </div>
                <div class="zeile">
                    <div class="datenart">
                        <label for="email">E-Mail-Adresse</label>
                        {email_error}
                    </div>
                    <div class="eingabe">
                        {email}
                    </div>
                </div>
                <div class="zeile">
                    <div class="datenart">
                        <label for="wohnort">Wohnort</label>
                        {wohnort_error}
                    </div>
                    <div class="eingabe">
                        {wohnort}
                    </div>
                </div>
            </div>
        </fieldset>
        <fieldset>
            <legend>Hast du Schon bei uns gekauft?</legend>
            <div class="abstand">
                <div class="zeile">
                    <p>
                        {schon_gekauft}
                    </p>
                    {schon_gekauft_error}
                </div>
            </div>
        </fieldset>
        <fieldset>
            <legend>Deine Musikinteressen</legend>
            <div class="abstand">
                <div class="zeile">
                    <p>Hier musst Du Dich für einen Star entscheiden</p>
                    <p>
                        {liebling}
                    </p>
                    {liebling_error}
                </div>
                <div class="zeile">
                    <p>Hier kannst Du mehrere Möglichkeiten ankreuzen</p>
                    <p>
                        {interessen}
                    </p>
                    {interessen_error}
                </div>
                <div class="zeile">
                    <label for="zusatz">Wenn du uns sonst noch etwas über Deine Wünsche und Erwartungen an unser Programm mitteilen willst, kannst du dies hier tun</label>
                    <p>
                        {zusatz}
                    </p>
                    {zusatz_error}
                </div>
            </div>
        </fieldset>
        <p>
            {form_submit}
        </p>
    </div>
{form_close}

Erstellung der E-Mail-Vorlagendatei für die E-Mail-Ausgabe des Eintrags (vkdaten/tools/formular/standard-emaileintrag.html)

-- Angaben zur Person --
Vorname: {vorname}
Familienname: {familienname}
E-Mail-Adresse: {email}
Wohnort: {wohnort}

-- Hast du Schon bei uns gekauft? --
{schon_gekauft}

-- Deine Musikinteressen --
Star: {liebling}
Musik: {interessen}
Wünsche und Erwartungen: {zusatz}

E-Mail-Ausgabe des Eintrags (Beispiel)

-- Angaben zur Person --
Vorname: Frank
Familienname: Musterman
E-Mail-Adresse: frank.musterman@rrze.uni-erlangen.de
Wohnort: Erlangen

-- Hast du Schon bei uns gekauft? --
Im vergangenen Monat

-- Deine Musikinteressen --
Star: Marianne Rosenberg
Musik: Pop, Jazz, Klassik
Wünsche und Erwartungen: Hallo Welt!

10. Beispiel 3: Umfrage

Erstellung der Konfigurationsdatei (vkdaten/tools/formular/umfrage.conf)

# Umfrageformular

# Formulareinträge in einer CSV-Datei speichern
csv_entries	1

# Mehrfachabsendungen verhindern
cookie_locked	1

email_receiver	PR-Abteilung|franz.musterman@fau.de
email_subject	Umfrage: Studium und Universität
email_sender	name|email
email_views	umfrage-emaileintrag

form_views	form_views	umfrage-form|umfrage-success||umfrage-locked
form_submit	Absenden|id="submit"
form_error	<p style="font-style:italic; color: red">|</p>

form_field	hidden|name|Umfrage
form_field	hidden|email|umfrage@fau.de

# An welche Fakultät studieren Sie?
form_field	dropdown|fakultaeten|Bitte wählen;Philosophische Fakultät und Fachbereich Theologie;Rechts- und Wirtschaftswissenschaftliche Fakultät;Medizinische Fakultät;Naturwissenschaftliche Fakultät;Technische Fakultät|trim;not_empty

# In welchem Studienjahr bzw. Studienniveau befinden Sie sich?
form_field	radio|studienjahr|Erstes;Zweites;Drittes;Viertes;Magister|trim;required

# Wie würden Sie die Zufriedenheit mit Ihrer Uni angeben?
form_field	radio|zufriedenheit|sehr zufrieden;zufrieden;weder noch;eher nicht zufrieden;unzufrieden|trim

# Bekommen Sie jetzt ein Stipendium?
form_field	radio|stipendium|ja;nein|trim
form_field	checkbox|stipendium_ausgeben|zur Finanzierung der Studiengebühren; zur Finanzierung anderer Kosten;für den Lebensunterhalt;für Hobbys;Sonstiges|trim;max_options[2]
form_field	textarea|stipendium_zusatz||trim;xss_clean

rules_messages	required;Bitte beantworten Sie diese Frage.|not_empty;Bitte beantworten Sie diese Frage.

Erstellung der Vorlagendatei des Formulars (vkdaten/tools/formular/umfrage-form.html)

<p>
    Lieber Studierender, vielen Dank, dass Sie sich für die Umfrage kurz Zeit nehmen.
    Sie werden ungefähr x Minuten dafür benötigen. Herzliche Grüße von der Universität.<br/>
    Diese Umfrage enthält 4 Fragen.
</p>
<p>
    Hinweise zum Datenschutz:<br/>
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat.
</p>
{form_open}
    {name}
    {email}
    <div>
        <fieldset>
            <legend>An welche Fakultät studieren Sie?</legend>
            <div class="abstand">
                <div class="zeile">
                    {fakultaeten_error}
                    <p>
                        {fakultaeten}
                    </p>
                </div>
            </div>
        </fieldset>
        <fieldset>
            <legend>In welchem Studienjahr bzw. Studienniveau befinden Sie sich?</legend>
            <div class="abstand">
                <div class="zeile">
                    {studienjahr_error}
                    <p>
                        {studienjahr}
                    </p>
                </div>
            </div>
        </fieldset>
        <fieldset>
            <legend>Wie würden Sie die Zufriedenheit mit Ihrer Uni angeben?</legend>
            <div class="abstand">
                <div class="zeile">
                    {zufriedenheit_error}
                    <p>
                        {zufriedenheit}
                    </p>
                </div>
            </div>
        </fieldset>
        <fieldset>
            <legend>Bekommen Sie jetzt ein Stipendium?</legend>
            <div class="abstand">
                <div class="zeile">
                    {stipendium_error}
                    <p>
                        {stipendium}
                    </p>
                </div>
                <div class="zeile">
                    <p>
                        Wenn ja: Wofür geben Sie das Geld aus? (bitte maximal 2 Antworten auswählen!)
                    </p>
                    {stipendium_ausgeben_error}
                    <p>
                        {stipendium_ausgeben}
                    </p>
                    <p>
                        {stipendium_zusatz}
                    </p>
                </div>
            </div>
        </fieldset>

        <p>
            {form_submit}
        </p>
    </div>
{form_close}

Erstellung der Formularvorlagen für die erfolgreiche Absendung-Bestätigung (vkdaten/tools/formular/umfrage-success.html)

<div class="hinweis" style="width: 75%">
    <p>
        Vielen Dank, dass Sie an der Umfrage teilgenommen haben.<br />
        Wir wünschen Ihnen ein erfolgreiches Semester.
    </p>
</div>

Erstellung der Formularvorlagen für das bereits abgesendetes Formular (vkdaten/tools/formular/umfrage-locked.html)

<div class="hinweis_wichtig" style="width: 75%">
    <p>
        Sie haben diese Umfrage bereits durchgeführt.<br />
        Bitte kontaktieren Sie Franz Musterman ( franz.musterman@fau.de ) für weitere Unterstützung.
    </p>
</div>

nach oben