Contact Form

Experten Modus?

Über der Grid Konfiguration findest du eine Option zum Experten-Modus. In diesem Modus verzichtest du auf das Grid und kannst dein Formular via (HTML-) Code erstellen. Dieser Modus ist in neuen Contact Forms Drops standardmäßig deaktiviert, bei einem Update deiner älterer Contact Form Drops jedoch aktiviert. Lies darüber mehr im Appendix weiter unten!

Formularfelder - Konfiguration im Grid

Deine Formularfelder erstellst du in einem Grid Control, das du vielleicht schon aus dem Flex Layout Drop kennst. Damit kannst du deine Inhalte (in diesem Fall die Elemente deines Formulars) bequem anordnen und spezielle Layouts für Endgeräte erstellen. Auf die vielen Möglichkeiten des Grids selbst gehen wir an dieser Stelle nicht ein, sondern verweisen auf die Dokumentation in unserem Wiki.

Typen von Formularfeldern

Das Contact Form Drop unterstützt alle üblichen Input Elemente eines HTML Formulars. Zusätzlich kannst du in deinen Formularen freie HTML Inhalte, andere Drops, Bereiche für Statusmeldungen und shopeigene Captchas einfügen! Alle möglichen Feldtypen findest du hinter der Option Typ des Feldes.

In den folgenden Abschnitten gehen wir etwas näher auf die allgemeinen und speziellen Optionen der einzelnen Formularelemente ein.

Allgemeine Feldkonfiguration

Für jedes Eingabeelement kannst du ein Label, eine Beschreibung, einen Platzhalter und einen Standardwert hinterlegen.

Mit der Option Variable bestimmst du den internen Parameternamen für deines Formularfeldes. Diesen Namen benötigst du für konditionelle Anzeigebedingungen (Reiter Darstellung), die manuelle Mailkonfiguration oder bei der Verwendung von Hooks. Mehr dazu findest du in den entsprechenden Abschnitten weiter unten.

Autocomplete und Standardwerte aus Kundendaten

Wo es möglich ist (bspw. bei Textbox oder Mailadressen) kannst du Standardwerte deiner Felder noch cleverer festlegen, nämlich aus den Daten des angemeldeten Kunden.

Auch die Autocomplete Funktion des Browsers kannst du unterstützen und Semantiken deinem Eingabefeld zuordnen.

Spezielle Feldkonfiguration

Einige Formularfelder bringen Besonderheiten mit sich, auf die wir nachfolgend etwas genauer eingehen wollen.

Textbox

Die Option Name der Antwortadresse kann bei einer Textbox verwendet werden, die den Namen des Anfragenden enthält. Bei deiner Antwort auf die durch das Formular erzeugte Mail wird dann in E-Mail Clients wie Outlook dieser Name angezeigt.

Mailadresse

Ein Feld vom Typ Mailadresse enthält meist die Mailadresse des Anfragenden. Du kannst diese als Antwortadresse festlegen, um direkt auf die durch das Formular erzeugte Mail antworten zu können.

Zusätzlich kannst du mit einer Option festlegen, ob eine Mail an diese Adresse gesendet werden soll und - wenn ja - wie genau (als Empfänger, Kopie oder Blindkopie). Wie du diese Mails genau konfigurierst, erfährst du im Abschnitt Mails weiter unten.

Absenden-Button

Mit dem Absenden Button wird das Formular abgeschickt. Hier kannst du Stil, Größe und Position des Buttons festlegen.

Dropdown, Checkbox und Radio

Bei Formularfeldern, die eine Auswahl ermöglichen, erscheint der Reiter Optionen. Hier kannst du die deine Auswahlmöglichkeiten hinterlegen und auch festlegen, ob diese vorausgewählt sein soll.

Eigener Inhalt - HTML und Drops!

Mit Elementen des Typs Eigener Inhalt kannst du dein Formular optisch anpassen und eigene HTML-Inhalte (auch mit Smarty) und andere Drops in dein Formular einfügen. Mehr Informationen zum Verlinken von Drops findest du im Wiki!

Übrigens: im eigenen Inhalt kannst du auch HTML-Formularelemente nutzen, also auch Code aus dem Expertemodus / alten Contact Form 1.x Formularen (siehe Appendix).

Weitere Besonderheiten

Bei Upload Feldern kannst du die Erlaubte Dateiendungen und die maximale Dateigröße einschränken.

Das Feld Benachrichtigungen gibt Statusnachrichten zum Mailversand aus, zum Beispiel beim erfolgreichen Versand einer Mail oder im Fehlerfall. Nimmst du kein solches Feld in dein Formular auf, werden die Meldungen unter deinem Formular ausgegeben.

Mit versteckten (und auch Mail Header-) Feldern kannst du Name-Wert-Kombinationen mit deinem Formular übermittelt. Dabei bleiben diese Daten für den Nutzer unsichtbar. In den Werten kannst du Smarty verwenden, um bspw. eine Artikelnummer innerhalb eines Produktanfrageformulars zu übermitteln. Wert wäre in diesem Fall {$Artikel->cArtNr}.

Ein reCAPTCHA Feld fügt eine reCAPTCHA Sicherheitsabfrage in dein Formular ein. Beachte dabei jedoch, dass reCAPTCHA korrekt im JTL-Shop konfiguriert sein muss.

Reiter Darstellung

Im Reiter Darstellung kannst du für die meisten Formularfelder festlegen, ob das Label angezeigt werden soll.

Außerdem kannst du zusätzliche CSS Klassen definieren, die im Elternelement deines Formularfeldes gesetzt werden sollen. Für eine Klasse meine-css-klasse würde der erzeugte Code dann in etwa wie folgt aussehen:

<div class="kk-cf-form-group form-group meine-css-klasse">
    <label>...</label>
    <select>
    ...
    </select>
</div>

Mit Konditionellen Anzeigebedingungen kannst du dein Formularfeld auf Basis von Nutzereingaben ausblenden bzw. deaktivieren. Mit form.meinFeld greifst du dabei auf Eingaben deiner Formularfelder zu, wobei meinFeld der Wert der Option "Variable" des jeweiligen Feldes ist.

form.email !=== '' blendet ein Feld aus oder deaktiviert es, wenn die Variable email einen Wert hat. Über die Option Bedingungsmodus bestimmst du, ob das Feld komplett ausgeblendet oder deaktiviert werden soll.

Für Checkboxen und Felder mit Optionen (Radio Buttons, Dropdowns, Listen) kannst du Zustand und Werte wie folgt prüfen:

• Checkboxen mit Einfachauswahl: form.meinFeld === true (selektiert) oder form.meinFeld === false (nicht selektiert)
• Radiobuttons, Auswahl (Dropdown/Liste) mit Einfachauswahl: form.meinFeld === "meinWert"
• Checkboxen und Dropdowns/Listen mit Mehrfachswahl: form.meinFeld.indexOf('meinWert') >= 0

Tipp: nutze den Entwicklermodus (siehe Abschnitt zu Mails), um alle verfügbaren Variablen und Werte deines Formulars zu sehen!

Versand

Im Reiter Versand konfigurierst du die essenziellen Parameter für den Versand deiner Mail. Bitte vergiss nicht, auch die entsprechenden JTL-Shop Einstellungen zum Mailversand vorzunehmen!

Neben dem Titel der Mail (bzw. Betreff) legst du hier Name und Mail-Adresse des Absenders und die Empfänger der Mail (TO, CC und BCC) fest.

Du kannst auch festlegen, dass bestimmte Eingaben des Formulars (Name und Mailadresse des Anfragenden) übernommen werden sollen. Aktiviere dazu die Option An Mail-Adressen aus dem Formular senden? bzw. Reply-To aus dem Formular nutzen? und die entsprechenden Optionen in den Formularfeldern (siehe oben).

Mit der Versandart legst du fest, ob deine Mail als HTML- oder Textmail versendet werden soll. Auch beides gleichzeitig ist möglich und im Standard gesetzt. Beachte, dass HTML-Mails automatisch in Textmails umgewandelt werden! Du kannst also problemlos HTML für den Inhalt deiner Mails nutzen (siehe nächste Abschnitte zu Inhalt und Styling).

Inhalt

Hier konfigurierst du den Inhalt deiner Mail. Letzteres nur, wenn du möchtest. Denn: die Option Mail-Inhalt automatisch generieren ist standardmäßig aktiv, wodurch dir eine einfache Mail mit Name-Wert-Paaren deiner Formularfelder generiert wird.

Manuelle Erstellung von Mailtemplates

Verzichtest du auf die automatische Generierung, musst du den Mail-Inhalt manuell erstellen. Im entsprechenden Control kannst du Smarty verwenden. Nutzt du im Formular die Variablen name (Textbox), email (Mail-Adresse) und message (Textarea), könntest du so im Mail-Inhalt darauf zugreifen:

Name des Anfragenden: {$form.name}
Mail: {$form.email}
Nachricht: {$form.message} 

Eine einfache Bestätigungsmail an den Kunden könnte wie folgt aussehen.

Beachte, dass du in deinem Mailtemplates auch Smarty verwenden kannst, um Werte deiner Formularfelder abzufragen. Im nachfolgenden Beispiel werden die selektierten Optionen einer Checkbox mit Mehrfachauswahl (Name der Varibale: cbm) ausgegeben.

{* no option checked *}
{if empty($form.cbm)}
    keine Auswahl
{else}
    {* loop each selected option and echo them *}
    {foreach from=$form.cbm item="checkboxAuswahl"}
        {$checkboxAuswahl} <br>
    {/foreach}  
{/if}

Header & Footer

Wenn du möchtest, kannst du auch separate Mail-Header und Mail-Footer für deine Mails definieren. Das kann dir dabei helfen, einen E-Mails einen einheitlichen Look zu verleihen. Denn: du kannst deine Mails duplizieren und so in neuen Mails deine Header- und Footerinhalte übernehmen.

Im Header und Footer kannst du HTML verwenden und hast Zugriff auf die Formularfelder. Bitte beachte jedoch, dass du in den HTML-Controls nicht - wie sonst üblich - jedes beliebige andere Drop verlinken kannst.

Möchtest du Header und Footer auch für anderen Mails verwenden, nutze separate Plain Drops und verlinke diese in den Mail-Eingabefeldern.

Anhänge

Im Reiter Anhänge kannst du beliebig viele Anhänge für deine Mail hinzufügen. Mit Dateiname bestimmst du den Namen der Datei, wie er im Mailanhang erscheinen soll. Mit dem Upload Control bestimmst du die Datei selbst.

CSS Styling deiner Mails

Du kannst die Elemente deiner Mails auch via CSS Stylen. Im Control Mail-Styling (CSS) kannst du normale CSS Syntax nutzen.

.mail-title {
    font-weight: bold;
    font-size: 30px;
}

Das Besondere: das Drop wandelt diese Regeln automatisch in Inline-Styles um, da diese von (Web-) E-Mail-Clients besser unterstützt werden. Mit obigem Beispiel würde es in der resultierenden HMTL Mail in etwa wie folgt aussehen:

<div class="mail-title" style="font-weight: bold; font-size: 30px;">
    Vielen Dank für die Anfrage!
</div>

Trotzdem solltest du bei der Gestaltung der Mail auf Kompatibilität achten und dich an geeigneter Stelle informieren.

Tipp: wie beim Header und Footer kannst du auch für deine CSS-Styles ein separates Plain Drop nutzen und verlinken, um die Regeln auch in anderen Mails zu verwenden.

Testen im Entwicklermodus!

Oft ist es sehr mühsam, Formulare und die daraus erzeugten Mails zu testen und zu debuggen. Deshalb haben wir ab Contact Forms Version 2.0.0 einen umfangreichen Entwicklermodus integriert, der via Option Entwickler-Modus? aktiviert wird (Standard: aktiv).

Im Entwicklermodus erhältst du nach dem Absenden des Formulars eine Vorschau deiner Mails in einem Popup. Diese Entwürfe kannst du auch an echte Mailadressen senden, um bspw. den Look deiner Mails in bestimmten Mail-Clients zu testen.

JavaScript Hook Beispiel 1

Mit nachfolgendem Code kannst du bspw. weitere Infos über einen missglückten Mailversand in die Console des Browsers loggen.

function(params, next) {
    console.log('SEND MAIL FAILED, form params:', params);
    return next(params);
}

JavaScript Hook Beispiel 2 - Matomo Event Tracking

Nehmen wir an, du hast ein Preisvorschlag Formular mit dem Contact Form Drop realisiert. Außerdem verwendest du bereits Matomo (ehemals Piwik) und möchtest nun das Absenden dieses Formulars tracken.

Folgenden JavaScript-Code kannst du dazu beim Event "Nach erfolgreichen Mailversand" setzen:

function(params, next) {
    if(_paq){
        _paq.push(['trackEvent', 'Contact', 'Preisvorschlag', params.post.cArtNr])
    }
    return next(params);
}

Als letzter Parameter der push() Funktion wird hier der Wert des Formularfeldes mit der Variable cArtNr gesetzt.

PHP Hook Beispiel

Mit PHP Hooks kannst du Daten serverseitig verarbeiten. Ein Beispiel wäre, die Ergebnisse einer Umfrage in einer eigens dafür angelegten Datenbanktabelle der JTL-Shop Datenbank abzulegen.

function($params) {

    // build survey entry object
    $surveyEntry = new stdClass();
    $surveyEntry->name = $params['form']['name']['value'];
    $surveyEntry->email = $params['form']['email']['value'];
    $surveyEntry->message = $params['form']['message']['value'];

    // insert survey entry to JTL-Shop MySQL database
    $result = Shop::DB()->insert('my_custom_survey_table', $surveyEntry);
}

Je nach gewähltem Hook hat $params unterschiedliche Inhalte. Um dir im Debug-Modus des Formulars den Inhalt und Aufbau von $params anzusehen, nimm einfach folgende Funktion und sende das Formular anschliessend ab:

function($params) {
    echo "<pre>";
    var_dump($params);
    echo "</pre>"
    die();
}

Infos zum Update auf 2.0.0

Das Update auf Version 2.0.0 bringt zahlreiche neue Funktionen und damit auch Vereinfachungen. Wo in älteren Versionen viel manuelle (Code-) Arbeit notwendig war, sorgen nun besseren Controls und Automatismen für mehr Nutzerfreundlichkeit.

Leider lassen sich dadurch aber bspw. ältere (HTML-)Formulare nicht automatisch in das neue Grid System überführen, sondern schalten sich nach einem Update in den Experten-Modus.

Auch die automatisch erzeugten Mail-Inhalte (siehe Abschnitt "Mails") sind nur für neu erstellte Mails Standard. Bei einem Update älterer Drops werden natürlich die vorher erstellten Mailtemplates übernommen.

Prüft bitte in jedem Fall nach einem Update auf die Version 2.0.0 alle Formulare und meldet euch bei uns, falls es hier Probleme geben sollte.

Häufige Anwendungsfälle

Bestätigungsmail an den Kunden senden

Um eine Bestätigungsmail an den anfragenden Kunden zu senden, gehst du wie folgt vor:

• erstelle in deinem Formular ein Feld des Typs "Textbox" für den Namen des Anfragenden
• setze im Textfeld die Option "Name der Antwortadresse?" auf "Ja"
• erstelle in deinem Formular ein Feld des Typs "Mail-Adresse"
• setze im Mailfeld die Option "Mail an diese Adresse senden als" auf "Empfänger (TO)"
• lasse in der Konfiguration deiner den "Empfänger" leer
• setze in der Mail die Option "An Mail-Adressen aus dem Formular senden?" auf "Ja"
• (optional) setze in der Mail die Option "BCC Empfänger" auf eine Email-Adresse, an die eine Blindkopie der Bestätigunsmail gehen soll (z.B. deine Supportermail)

Tipp: auf Youtube findest du ein Video, in dem wir die Konfiguration einer Bestätigungsmail genauer zeigen!

Mail an Support senden (mit Kunden als Absender)

Häufig sendet man Mails eines Kontaktformulares an Supportadressen wie support@meinshop.de. Um auf solche Mails direkt aus dem E-Mail-Client antworten zu können, musst du folgendes konfigurieren:

• erstelle in deinem Formular ein Feld des Typs "Textbox" für den Namen des Anfragenden
• setze im Textfeld die Option "Name der Antwortadresse?" auf "Ja"
• erstelle in deinem Formular ein Feld des Typs "Mail-Adresse"
• setze im Feld die Option "Antwortadresse?" auf "Ja"
• setze in der Mail die Option "Reply-To aus dem Formular nutzen?" auf "Ja"

Tipp: auf Youtube findest du ein Video, in dem wir die Konfiguration einer Mail an den Support zeigen!

Select2 und Contact Form kombinieren

Du kannst im Contact Form Drop auch Select2 nutzen! Mit Select2 lassen sich leicht Suchen in deinen Dropsdown-Optionen oder (mit etwas zusätzlichen Code) Bilder / Icons in den Auswahllisten realisieren.

Einige Beispiele haben wir in einer Dropper Zone zusammengestellt.

Formular Implementation im Expertenmodus

Im Expertenmodus erstellst du Formulare mit HTML Elementen. Vor Version 2.0.0 war dies die einzige Möglichkeit, Formulare zu erstellen. Bei einem Update von Version <= 2.0.0 werden deine bestehenden Formulare in diesem Expertenmodus gesetzt. Ab Version 2.0.0 solltest du diese Variante bei neuen Formularen nur noch nutzen, wenn du genau weißt, was du tust.

Mehr zu den Möglichkeiten von HTML Formularen erfährst du hier.

Input-Attribute

Du kannst deine Inputs mit bestimmten Attributen versehen:

• submit: Markiere ein Element mit diesem Attribut, wenn du möchtest, dass bei einem Klick auf das Element das Formular versendet wird.
• email: Definiert, dass dieses Feld eine Mail-Adresse enthält, an die das Formular gesendet wird.
• copy: Funktioniert nur in Verbindung mit email und sendet diese Nachricht dann an den Empfänger via CC.
• blind-copy: Funktioniert nur in Verbindung mit email und sendet diese Nachricht dann an den Empfänger via BCC.
• reply-to: Gibt an, dass diese Mail-Adresse als Reply-To Adresse gesetzt wird.
• reply-to-name: Gibt an, dass dieser Wert als Reply-To Namen gesetzt wird.
• required: Prüft vor dem Versand, ob das Feld ausgefüllt wurde.
• validate="email|url|number": Validiert das Feld vorab auf einen bestimmten Eingabetypen. Nicht nötig bei Feldern die bereits das email Attribut haben.
• no-reset: Unterdrückt den automatischen Reset auf dem angegebenen Feld.
• no-mail-display: Stellt die Ausgabe dieses Feldes nicht in der automatischen Mail dar.
• header: Weist den Wert des Feldes einem Header-Flag zu. Das Flag selbst ergibt sich aus dem name Attribut.
• messages: Weist das angegebene Element als Container für Nachrichten aus. Falls kein Element angegeben wird, werden Nachrichten automatisch unter dem Formular angezeigt.

Beispiel:

<input type="text" name="test" required email copy/>
<input type="text" name="zahl" required validate="number"/>
<button type="submit" class="btn btn-primary">Absenden</div>
<div messages></div>

Dateianhänge

Du kannst ein spezielles <upload> Control einfügen, um dem Nutzer Dateiuploads zu erlauben. Diese werden anschließend als Anhang an deine Mail angehängt.

Beispiel:

<upload class="btn btn-primary" name="bilder" size-limit="2048" extensions="png,jpg,jpeg,bmp" multiple>Bilder hochladen</upload>

• class: Die hier angegebenen Klassen stylen den Upload-Button
• size-limit: Maximal erlaube Dateigröße in KB. Bei fehlender Angabe sind 2MB voreingestellt. Wert 0 setzen, um alle Größen zu erlauben.
• extensions: Liste von Dateitypen, welche beim Upload erlaubt sind. Falls nicht angegeben sind alle Dateitypen erlaubt.
• multiple: Ist dieses Attribut gesetzt, können mehrere Dateien hochgeladen werden

Ebenfalls werden die Attribute required und no-reset auch hier unterstützt.

Google reCAPTCHA im Expertenmodus

Um ein Google reCAPTCHA einzufügen, wie du es für deine Domain bei Google konfiguriert hast, nutze im Expertmodus folgenden Code:

{if $drop.actions->recaptchaConfigured()}
<div class="kkcf-g-recaptcha" 
    id="kkcf-g-recaptcha-{$drop._internal.guid}" 
    data-sitekey="{$drop.actions->getRecaptchaSiteKey()}">
</div>
{/if}

JavaScript Events

Beachte, dass dieser Teil der Dokumentation noch aus Version < 2.0.0 stammt. Es ist zwar auch in neueren Versionen noch valide, aber mittlerweile kannst du mit Hook Elementen eleganter client- und serverseitige Funktionen mit deinem Formular verknüpfen.

Du hast die Möglichkeit via JavaScript auf verschiedene Events deines Formulars zuzugreifen:

• beforeValidate: Formulardaten vor der Validierung
• validate: Formulardaten während der Validierung - Du kannst hier eigene Fehler hinzufügen
• beforeSend: Formulardaten kurz vor dem Absenden des Formulars - Praktisch um die Daten zu erweitern.
• success: Formular nach erfolgreichem Mail-Versand
• error: Formular nach fehlerhaftem Versand oder sonstigen Fehlern. Betrifft keine Validierungsfehler!

Um auf bestimmte Events deines Formulars zu reagieren, gib ihm zunächst eine ID. Mit Hilfe dieser ID kannst du jetzt Folgendes tun:

$(function() {

    if (!window.KK_ContactFormDrop) return;

    KK_ContactFormDrop.on('meine_id', 'validate', function(params, next) {
        // mache etwas mit params
        console.log(params.test.value); // gibt den Wert des Parameters aus
        params.test.errors.push('Haha, hier ist immer ein Fehler!');
        // Der Call von next(params) muss zur Fortführung der Kette sein.
        next(params);
    });

}

Solltest du einem Parameter einen Fehler hinzufügen wird das Formular nicht mehr gesendet, sondern der Fehler ausgegeben.