Form-Widget (Embed-Code)

Einführung

Ein Embed-Code besteht aus ein paar Zeilen HTML und JavaScript, mit denen Sie ein iform4u-Formular in Ihre eigene Website einbetten können. Dies ist die einfachste Methode, ein Formular auf Ihrer Website anzuzeigen, und sie ist am wenigsten fehleranfällig. Außerdem ist einer der wichtigsten Vorteile des Form-Widgets, dass jedes Mal, wenn Sie Ihr Formular im Form Builder ändern, das eingebettete Formular automatisch aktualisiert wird.

Das Form-Widget wurde so entwickelt, dass es auf jeder Webseite funktioniert. Unser Form-Widget erstellt dynamisch ein iFrame, in dem das Formular geladen wird. Da es dieses iFrame selbst erzeugt, kann es dessen Größe auch automatisch anpassen. Das bedeutet, dass Sie den Code nicht nach jedem Update ändern müssen. Außerdem werden durch die Einbettung des Formulars in ein iFrame Konflikte mit bereits vorhandenem JavaScript oder vorhandenen CSS-Elementen auf Ihrer Seite vermieden.

Welchen Formular-Einbettungscode sollte ich verwenden?

Derzeit bietet iform4u zwei Möglichkeiten, ein Formular auf Ihrer Website zu veröffentlichen:

1. Einbettung mit Design: Damit können Sie das Formular mit dem Design bzw. Thema veröffentlichen, das Ihrem Formular zugewiesen wurde.
2. Einbettung ohne Design: Damit können Sie das Formular ohne ein Thema veröffentlichen, auch wenn Ihrem Formular eines zugewiesen wurde.

Üblicherweise sollten Sie die erste Option verwenden.

Wie befüllt man ein Feld mit einem Query-String?

Sie können ein Feld mit URL-Parametern befüllen. Verwenden Sie dazu einfach die Feld-ID oder den Feld-Alias als Schlüssel für den Parameter. Der zugewiesene Wert dieses Parameters erscheint dann in dem jeweiligen Feld.

Hinweis: Wenn Sie ein Mehrschritt-Formular (Multi-Step Form) verwenden, können Sie über die URL zu einer bestimmten Seite springen, indem Sie die Seitennummer anhängen. Um z. B. direkt zur zweiten Seite zu gehen, verwenden Sie den Query-String „p=2“.

Wie kann man PostMessages empfangen, die vom Form-Widget gesendet werden?

Um die Nachrichten abzuhören, die das Form-Widget sendet, müssen Sie lediglich einen Event Listener zu Ihrer Webseite hinzufügen. Wenn Sie beispielsweise in Ihrer Webseite die Submission-ID erfahren möchten, können Sie diesen Code direkt unterhalb des Einbettungscodes einfügen:

window.addEventListener("message", receiveMessage, false);
function receiveMessage(event) {
    if (event.data) {
        var data = JSON.parse(event.data);
        if (typeof data.action !== "undefined" && data.action === "success") {
            console.log("Übermittlung mit ID gespeichert", data.data.id);
        }
    }
}

Einstellungen des Form-Widgets

Das Form-Widget (Embed-Code) besteht aus zwei Teilen:

1. Ein HTML-Code, der den Standardinhalt anzeigt, wenn der Benutzer auf das Formular zugreift, während JavaScript in seinem Browser deaktiviert ist. Standardmäßig wird ein Link zu Ihrem Formular in einem DIV-Element angezeigt.
2. Ein JavaScript-Code, der das Formular darstellt und den Form Tracker (falls Analytics aktiviert ist) initialisiert.

Mit dem Form-Widget können Sie einige Optionen des Formulars spontan konfigurieren:

• Id: Die Formular-ID in der Anwendung. Beispiel: 'id': 132
• Sid: Submission-ID. Verwenden Sie diese Option, um ein bereits vorhandenes, gespeichertes Formular zu bearbeiten. Um die Submission-ID zu finden, gehen Sie in den Submission Manager. Beispiel: 'sid': 964
• Container: Die ID des HTML-Elements, in dem das iFrame für das Formular eingefügt wird. Standardmäßig zeigt diese Einstellung auf die DIV-ID, die den Link zum Formular enthält. Beispiel: 'container': 'c132'
• Width: Legt die Breite des iFrames fest. Beispiel: 'width': '100%'
• Height: Legt die Höhe des iFrames fest. In der Regel wird dieser Wert in Pixeln angegeben. Er wird beim Erstellen des Codes im Form Builder berechnet. Beispiel: 'height': '846px'
• Auto Resize: Ist standardmäßig aktiviert. Gibt an, ob das iFrame automatisch an die tatsächliche Höhe des Formulars angepasst wird (z. B. wenn Fehlermeldungen eingeblendet werden). Wird es auf false gesetzt, ändert sich die Größe nicht automatisch, und die Höhe wird durch die Option "height" bestimmt. Beispiel: 'autoResize': !0
• Theme: Ist standardmäßig aktiviert (Wert 1). Ermöglicht es Ihnen, ein Design (Theme) auf Wunsch zu deaktivieren (Wert 0). Beispiel: 'theme': 1
• Custom JS: Ist standardmäßig aktiviert (Wert 1). Ermöglicht es, das Laden externer JavaScript-Dateien auf Wunsch zu deaktivieren (Wert 0). Beispiel: 'customJS': 1
• Record: Ist standardmäßig aktiviert (Wert 1). Ermöglicht es, den Form Tracker (Aufzeichnung) auf Wunsch zu deaktivieren (Wert 0). Beispiel: 'record': 1
• Reset: Ist standardmäßig aktiviert (Wert 1). Bestimmt, ob das Formular nach dem Absenden zurückgesetzt wird (1) oder nicht (0). Beispiel: 'reset': 0
• Page: In einem Mehrschritt-Formular legt diese Option die Seite fest, die standardmäßig angezeigt wird. Um z. B. die zweite Seite anzuzeigen, verwenden Sie: 'page': 2
• Form: Gibt den Pfad zum Embed des Formulars an. Dieser enthält keine Parameter.
• addToOffsetTop: Ist standardmäßig 0. Fügt der Berechnung der Formularposition eine Zahl positiver oder negativer Pixel hinzu. Dies ist nützlich, wenn auf der Website z. B. ein feststehendes ("fixed") Header-Element existiert. Beispiel: 'addToOffsetTop': '-60'
• Default Values: Wenn Sie Formularfelder mit Standardwerten vorab befüllen möchten, können Sie diese Option verwenden. "Default Values" ist ein JSON-Objekt, in dem der Schlüssel die ID des Formularfelds und der Wert der gewünschte Feldinhalt ist. Beispiel:

  
  'defaultValues': {
      'text_0': 'Dies ist mein Standardwert'
  }
  

  Beachten Sie, dass Checkboxen und Radiobuttons mit booleschen Werten ausgewählt werden können. Beispiel:

  
  'defaultValues': {
      'text_0': 'Dies ist mein Standardwert',
      'checkbox_0': true
  }
  

Interaktion mit dem Formular per JavaScript

Das Form-Widget enthält viele Funktionen und Optionen, die in einer externen JavaScript-Datei konfiguriert werden können.

Hinweis: Um eine JavaScript-Datei zu laden, gehen Sie zu "Forms -> Actions -> Settings -> UI Settings".

Standardmäßig steht ein jQuery-Objekt zur Verfügung. So können Sie auf sehr einfache Weise mit dem Formular interagieren, indem Sie zum Beispiel folgenden Code verwenden:

$(document).ready(function() {
    // Hier können wir mit dem Formular interagieren
});

Das Formularelement

Das Formularelement – formEl – ist ein jQuery-Objekt, auf das Sie zugreifen können, um Informationen abzurufen oder es direkt zu manipulieren. Hier ein Beispiel, in dem wir die Höhe des Formulars ausgeben:

$(document).ready(function() {
    console.log('Die Höhe des Formulars ist', formEl.height());
});

Ereignisse abhören

Bestimmte Ereignisse werden ausgelöst, wenn das Formular bestimmte Aktionen ausführt:

• view: Wird ausgelöst, wenn ein Formular angezeigt wird.
• fill: Wird ausgelöst, sobald Sie das erste Mal mit dem Formular interagieren, z. B. indem Sie ein Textfeld ausfüllen oder einen Radiobutton auswählen.
• error: Wird ausgelöst, wenn der Server einen Validierungsfehler meldet.
• success: Wird ausgelöst, wenn das Formular erfolgreich abgeschickt wurde.
• nextStep: Wird bei jedem Wechsel zur nächsten Seite in einem Mehrschritt-Formular ausgelöst.
• previousStep: Wird bei jedem Schritt zurück ausgelöst.

Ein sehr einfaches Beispiel, um zu erkennen, wann ein Formular einen Server-Validierungsfehler hat:

$(document).ready(function() {
    formEl.on('error', function(event) {
        /* Server-Validierungsfehler nachverfolgen */
        /* Was hier passiert, hängt von Ihrem Analyseprodukt ab! */
    });
});

Die Regel-Engine löst außerdem folgende Ereignisse aus, wenn ein Feld per Konditionalregel ein- oder ausgeblendet wird:

ef.shown: Wird ausgelöst, wenn ein Feld angezeigt wird.
ef.hidden: Wird ausgelöst, wenn ein Feld ausgeblendet wird.

Um diese Ereignisse abzufangen, können Sie beispielsweise folgende Event-Listener verwenden:

$(document).ready(function() {
    $('#text_1').on('ef.shown', function(e) {
        console.log("Dieses Textfeld wurde eingeblendet.");
    });
    $('#text_1').on('ef.hidden', function(e) {
        console.log("Dieses Textfeld wurde ausgeblendet.");
    });
});

Die Event-Handler: previousStep und nextStep

Zusätzlich zu den oben erwähnten Ereignissen bietet iform4u zwei Event-Handler, mit denen Sie in einem Mehrschritt-Formular per JavaScript vor- und zurückspringen können. Im nächsten Abschnitt sehen wir, wie Sie mithilfe der Auto-Advance-Funktion ohne Klick auf „Next“ zur nächsten Seite gelangen.

Automatisches Weiterschalten in Mehrschritt-Formularen

Wenn Sie ein Mehrschritt-Formular erstellen, fügt iform4u standardmäßig zwei Navigationsschaltflächen – „Previous“ (Zurück) und „Next“ (Weiter) – am unteren Ende des Formulars ein. Diese ermöglichen es Ihnen, durch das Formular zu navigieren, bis Sie zur letzten Seite gelangen, auf der sich in der Regel der Absende-Button befindet.

Hinweis: Mit iform4u können Sie mehrere Absende-Buttons auf verschiedenen Seiten oder an unterschiedlichen Stellen des Formulars hinzufügen.

In manchen Fällen möchten Sie jedoch direkt zur nächsten Seite springen, ohne einen Button zu klicken. Dafür nutzen wir den Event-Handler „nextStep“.

Hinweis: Diese Funktion ist beispielsweise für Umfragen oder Tests sinnvoll, bei denen Änderungen an Antworten nicht erlaubt sind oder ein möglichst schnelles Ausfüllen erwünscht ist.

Im folgenden Beispiel sehen Sie, wie das Formular jedes Mal automatisch zur nächsten Seite weiterblättert, sobald ein Radio-Button ausgewählt wurde:

$(document).ready(function() {
    $('input[type=radio]').on('change', nextStep);
});

Wenn Sie die Navigationsschaltflächen ausblenden möchten, können Sie in das Ihrem Formular zugewiesene CSS-Theme einfach folgende Zeilen einfügen:

.previous,
.next {
    display: none !important;
}

Mehrere JavaScript- und CSS-Dateien in unserem Formular laden

Da das jQuery-Objekt verfügbar ist, können wir mittels jQuery.when().done() mehrere JavaScript-Dateien laden und sie erst verwenden, wenn alle bereitstehen. Schauen wir uns dazu folgendes Beispiel an.

Einen jQuery UI DatePicker in einem Datumsfeld anzeigen

Im folgenden Beispiel-Code demonstrieren wir, wie Sie in den Datumsfeldern Ihres Formulars einen jQuery UI DatePicker anzeigen können:

$(document).ready(function() {
    $.when(
        $('head').append(''),
        $.getScript("//cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"),
        $.Deferred(function(deferred){
            $(deferred.resolve);
        })
    ).done(function(){
        $('body').css('padding-bottom', '200px'); // Abstand, damit der DatePicker sichtbar ist
        $('input[type=date]').each(function () {
            $(this).attr('type', 'text').after(
                $(this).clone()
                    .attr('id', this.id + '_alt')
                    .attr('name', this.id + '_alt')
                    .datepicker({
                        // Übereinstimmung mit dem HTML5-Datumsformat
                        dateFormat: 'mm/dd/yy',
                        changeMonth: true,
                        changeYear: true,
                        altField: this,
                        altFormat: "yy-mm-dd"
                    })
            )
            .hide();
        });
    });
});

Wie Sie sehen können:

• Wir laden zwei Dateien innerhalb der Funktion when(): jquery-ui.css und jquery-ui.min.js.
• In der Funktion done() führen wir den Code aus, sobald beide Dateien geladen sind.
• Die Funktion führt im Wesentlichen drei Schritte aus:
  1. Sie sucht alle Felder vom Typ „date“ und konvertiert diese nach „text“.
  2. Sie klont jedes Datumsfeld in ein Textfeld, das den DatePicker anzeigt.
  3. Sie blendet das ursprüngliche Datumsfeld aus, da dessen Wert automatisch über die Attribute altField und altFormat gesetzt wird.