Formular erstellen

Das System bietet Ihnen Formular Blöcke um individuelle Formulare erstellen zu können. Damit Sie diese Formular Blöcke bei der Blockauswahl auswählen können, benötigen Sie ein Layout, welches für eines oder mehrere Orientierungen ein Formular definiert. Ein Layout könnte z.B. so aussehen:

<form data-edit-template="center" method="post" enctype="multipart/form-data">
    {$page->getBlocks("center")}
</form>

Damit das Formular verarbeitet werden kann, muss es unbedingt mit der POST Methode (method="post") abgesendet werden.
Damit Dateien hochgeladen werden können, muss das Attribut enctype="multipart/form-data" gesetzt sein.

Für die Orientierung center werden in diesem Beispiel die Formular Blöcke verfügbar gemacht. Formular Blöcke verhalten sich wie gewöhnliche Blöcke und können individuell platziert werden. Folgende Formular Blöcke stehen zur Auswahl:

Textfeld
Textarea
Zahlenfeld
Checkbox
Radiobuttons
Auswahlliste
Datei hochladen
Captcha
Zurücksetzen
Absenden

Jeder Formular Block hat Block Einstellungen, über welche bestimmte Eigenschaften gesetzt werden können.

Der Formular Block Textfeld kann optional auch als E-Mail, Passwort oder Datum Feld verwendet werden. Wenn Sie ein E-Mail Feld verwenden, können Sie optional auch eine E-Mail an die eingetragene E-Mail Adresse versenden.

Der Formular Block Textfeld kann auch als regulärer Ausdruck definiert werden. Dieser berücksichtigt Groß- und Kleinschreibung und beginnt immer am Anfang des Wertes.

Über jeden Formular Block können zusätzlich in den Block Einstellungen auch Einstellungen zum allgemeinen Formular vorgenommen werden. Dazu gehören:

E-Mail senden an: Die abgesendeten Formulardaten werden an diese E-Mail Adresse versendet.
E-Mail Template: Verwenden Sie ein E-Mail Template, an welches die abgesendeten Formulardaten übergeben und versendet werden. Wenn Sie zusätzlich noch das vorherige Feld mit einer E-Mail Adresse füllen, wird diese E-Mail Adresse als zusätzlicher Empfänger im E-Mail Template verwendet.
Daten speichern als: Die abgesendeten Formulardaten werden als Unterseite, CSV oder XML Datei gespeichert. CSV und XML werden standardmäßig in den Mediapool der aktuellen Seite gespeichert. Optional können die Dateien aber auch in einer Kategorie eines Multimedia Mandanten abgelegt werden. Wenn Sie die Daten als Unterseiten speichern, erhalten Sie den Reiter Empfangene Daten, in welchem Sie die Daten nachvollziehen können.
Daten hochladen als: Laden Sie die abgesendeten Formulardaten als CSV oder XML Datei auf einem (S)FTP Server hoch.
Pre-Skript ausführen: Geben Sie den Pfad zu einem Skript an, welches vor dem Absenden des Formulares ausgeführt wird.
Post-Skript ausführen: Geben Sie den Pfad zu einem Skript an, welches nach dem Absenden des Formulares ausgeführt wird.
Erfolgsmeldung: Geben Sie eine Erfolgsmeldung an. Standardmäßig wird ein allgemeingültiger Text verwendet.
Fehlermeldung: Geben Sie eine Fehlermeldung an. Standardmäßig wird ein allgemeingültiger Text verwendet.
Unsichtbare Felder: Geben Sie unsichtbare Felder an, die automatisch dem Formular als Inputfelder vom Typ hidden hinzugefügt werden.

Die Pfade für das Pre- und Post-Skript folgen den gängigen Hierarchie Regeln in site (geben Sie z.B. my_form.php ein, wenn das Skript in site/<Mandant>/my_form.php liegt). In den Skript Dateien muss es die Funktion page_pre_send_form, bzw. page_post_send_form geben.

Beiden Funktionen werden folgende Parameter übergeben:

$page: Das aktuelle Page Objekt.
$data: Alle abgesendeten Formulardaten.
$files: Alle zum Hochladen ausgewählte Dateien.
$orient: Die betroffene Orientierung im Layout.
$form (nur Pre-Skript): Alle Informationen zum aktuellen Formular.

Wenn Sie page_pre_send_form verwenden, wird ein Rückgabewert erwartet (true oder false). Wenn Sie nicht true zurückliefern, wird ein Fehler angenommen und die weitere Verarbeitung der eingegebenen Daten abgebrochen. Wenn Sie statt false einen String zurückliefern, wird dieser als Fehlermeldung verwendet.

Wenn Sie den Spamschutz aktivieren möchten, müssen Sie den Formular Block Captcha platzieren.

Sie müssen in jedem Fall den Formular Block Absenden verwenden, damit das Formular überhaupt versendet werden kann.

Beim Versenden wird die Page Methode sendForm($data, $files, $orient) aufgerufen, die Sie bei Bedarf auch überschreiben können (über eine PageExtension). Es wird aber empfohlen innerhalb der überschriebenen Methode die originale Methode aufzurufen, womit diese Technik eher als Alternative zum Pre- und Post-Skript anzusehen ist. Beispiel:

public function sendForm($data, $files, $orient) {
  	// Ihr Code vor der originalen Methode
  	return parent::sendForm($data, $files, $orient);
}

public function sendForm($data, $files, $orient) {
  	$result = parent::sendForm($data, $files, $orient);
  	// Ihr Code nach der originalen Methode
  	return $result;
}

Alle Formular Blöcke beginnen mit der Bezeichnung input_* und können bei Bedarf durch eigene Formular Blöcke ersetzt werden. Auch das Hinzufügen weiterer Formular Blöcke ist möglich. Diese sollten ebenfalls eine Bezeichnung im Muster input_* haben. Beispiel:

{
    "blocks": {
        "input_reset": {
            "title": "Zurücksetzen",
            "description": "Ein Zurücksetzen Button.",
            "pattern": "[100:reset]"
        }
    }
}

Sie können das HTML der Standard Formular Blöcke in lib/page/t/blocks/ als Vorlage für Ihre eigenen Formular Blöcke verwenden.

Die Eigenschaft name wird verwendet um automatisch das Konfigurationstemplate zu ermitteln. Dieses muss im site Verzeichnis in folgendem Pfad existieren: admin/input/name.tpl (in diesem Beispiel admin/input/reset.tpl). Dieser Pfad kann auch ausgehend von einem Seitentyp oder in site/_global/ sein.

Die Möglichkeiten im Konfigurationstemplate folgen den selben Regeln wie die für conf Elemente und wird automatisch um die allgemeinen Einstellungen für das Formular erweitert.

Wenn Sie eigene Formular Blöcke erstellen, sollten Sie in Ihrem Konfigurationstemplate darauf achten, dass Felder wie name, default oder required vom System ausgewertet werden. Sollten Sie diese Felder für andere Zwecke benötigen als es die Standard Formular Blöcke tun, verwenden Sie bitte andere Bezeichnungen. Für den Fall, dass Sie Felder für genau diese Zwecke benötigen, verwenden Sie natürlich diese Bezeichnungen.

In der conf.json Datei können Sie noch weitere Einstellungen für das Formular über die Eigenschaft form vornehmen, um automatisch das HTML für bestimmte Elemente zu manipulieren. Beispiel:

{
    "form": {
        "wrapper": "<div class=\"field\"><%></div>",
        "required": "<%> <span>*</span>",
        "optional": "<%> <span>(optional)</span>",
        "success": "<div class=\"notification success\"><p><%></p></div>",
        "error": "<div class=\"notification error\"><p><%></p></div>"
    }
}

wrapper: Jeder Formular Block wird automatisch in <%> des angegebenen HTMLs gesetzt. Falls Ihr Design für einzelne Formularelemente z.B. einen umschließenden HTML Container benötigt, können Sie so die Standard Formular Blöcke erweitern, ohne diese überschreiben zu müssen.
required: Wenn das Feld label als Label verwendet wird, können Sie Pflichtfelder mit z.B. einem * (Asterisk) optisch hervorheben. Sie können hier das HTML setzen, wobei <%> für das Label steht. Wenn Sie kein HTML angeben, sind Pflichtfelder nur über das HTML Attribut required erkennbar.
optional: Ähnlich wie required können Sie optionale Felder hervorheben. Alle Felder sind standardmäßig optional. Wählen Sie aber in den Einstellungen des Formularelements die Option "Optional", dann wird das hier eingetragene HTML angewendet. Eine weitere Funktionalität hat die Option "Optional" nicht.
success: Der HTML Container für die Erfolgsmeldung. In <%> steht der Text.
error: Der HTML Container für die Fehlermeldung. In <%> steht der Text.

Weitere Einstellungen:

submit: Standardmäßig wird für den Absenden Button ein input Element erstellt. Wenn Sie den Standard Formular Block nicht überschreiben möchten, weil Sie ein button Element benötigen, können Sie hier den Wert button übergeben.
values: Sie können ähnlich wie bei erweiterten Blöcken eine Liste mit Eigenschaften zusätzlicher Felder definieren. Dazu setzen Sie in wrapper den Platzhalter <%> an den Stellen ein, an denen Sie zusätzliche Felder benötigen. Um festzulegen, bei welchem der mehreren Platzhalter der Formular Block selbst eingefügt werden soll, wird stattdessen ein leeres Element eingefügt (z.B. null, false, leerer String, 0, etc.).

Sie können Standard Formular Blöcke auch über die modify Eigenschaft erweitern, ohne diese überschreiben zu müssen.