Einbettung für Entwickler

Diese Seite richtet sich an Dich, wenn Du das Einbettungsscript genauer steuern möchtest: Du reagierst auf Events wie das Absenden, füllst Felder per JavaScript vor oder bindest Formulare in React, Vue oder einen Page-Builder ein. Die Grundlagen findest Du unter In Webseite integrieren.

Script einbinden

<div data-form="DEIN-FORMULAR"></div>
<script src="https://app.formenio.de/embed.js" async></script>

Binde das Script einmal pro Seite ein, egal wie viele Formulare Du verwendest. Mehrfaches Einbinden schadet nicht.
Die Position ist frei wählbar. Mit async blockiert es das Laden Deiner Seite nicht.
Unter /embed.js erhältst Du immer die aktuelle Version. Du musst Deinen Code bei Updates nicht anpassen.

Alle Attribute

Du setzt die Attribute auf das Element mit data-form.

Attribut	Werte	Beschreibung
`data-form`	Formular-Key	Pflicht. Der Key aus dem Link Deines Formulars (`app.formenio.de/f/KEY`).
`data-mode`	`popup`	Das Element wird zum Auslöser: Ein Klick öffnet das Formular im Popup. Ohne Angabe wird eingebettet.
`data-mobile`	`fullscreen`	Nur eingebettet: Auf Geräten bis 640 Pixel Breite öffnet ein Tipp das Formular im Vollbild.
`data-width`	z. B. `100%`, `600px`, `600`	Eingebettet: Breite des Elements. Popup: maximale Breite des Fensters (Standard: 640 Pixel).
`data-height`	z. B. `500px`, `500`	Start- und Mindesthöhe. Danach passt sich die Höhe an den Inhalt an. Standard: 500 Pixel.
`data-max-height`	z. B. `700px`	Maximale Höhe. Darüber scrollt das Formular innerhalb dieser Höhe.
`data-hide-header`	`true`	Blendet Titel und Beschreibung des Formulars aus.
`data-scroll-offset`	Zahl in Pixeln	Abstand nach oben beim automatischen Scrollen, z. B. für eine feste Kopfzeile. Standard: 16.
`data-theme`	`light`, `outline`, `dark`, `custom`, `underlined`	Überschreibt das Theme des Formulars.
`data-lazy`	`false`	Lädt das Formular sofort. Standardmäßig lädt es, kurz bevor es sichtbar wird.
`data-prefill`	`feldId=Wert&feldId2=a,b`	Füllt Felder vor. Format wie bei Felder vorausfüllen.
`data-params`	`utm_source=newsletter`	Hängt zusätzliche Parameter an die Formular-Adresse an.

Zahlen ohne Einheit werden als Pixel interpretiert.

tipp

Schreibe in das Element einen Link zum Formular, z. B. <a href="https://app.formenio.de/f/DEIN-FORMULAR">Formular öffnen</a>. Das Script ersetzt ihn durch das Formular. Ist JavaScript blockiert, bleibt der Link als Ausweg sichtbar.

Events

Das Script meldet, was im Formular passiert. Jedes Event löst es als CustomEvent auf dem Element mit data-form aus. Das Event steigt bis zu window auf, Du kannst also an beiden Stellen zuhören.

Event	Wann	Inhalt von `event.detail`
`formenio:ready`	Das Formular ist geladen und angezeigt.	`name` (Formularname), `totalPages`
`formenio:page`	Deine Besucher wechseln die Seite.	`page`, `totalPages`
`formenio:submit`	Das Formular wurde erfolgreich abgesendet.	`responseId`
`formenio:open`	Ein Popup oder das Vollbild wurde geöffnet.	–
`formenio:close`	Ein Popup oder das Vollbild wurde geschlossen.	–

Zusätzlich enthält event.detail immer form (den Formular-Key) und element (das Element mit data-form).

hinweis

Die Antworten Deiner Besucher werden bewusst nicht an Deine Website übergeben. Du erfährst nur, dass und wann abgesendet wurde.

Beispiel: Conversion zählen

Mit dem Google Tag Manager:

<script>
  window.addEventListener("formenio:submit", function (event) {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: "formenio_submit",
      formenio_form: event.detail.form
    });
  });
</script>

Nur für ein bestimmtes Formular:

document.querySelector("#kontakt").addEventListener("formenio:submit", function () {
  // z. B. Dankeschön-Hinweis auf Deiner Seite einblenden
});

JavaScript-API

Sobald das Script geladen ist, steht window.Formenio zur Verfügung. Weil das Script asynchron lädt, wartest Du dafür auf das Event formenio:loaded:

function withFormenio(callback) {
  if (window.Formenio) callback(window.Formenio);
  else window.addEventListener("formenio:loaded", function () { callback(window.Formenio); });
}

`Formenio`

Funktion	Beschreibung
`Formenio.get(elementOderSelektor)`	Gibt das Formular zu einem Element mit `data-form` zurück, z. B. `Formenio.get("#kontakt")`.
`Formenio.open(key, optionen)`	Öffnet ein Formular im Popup, ohne dass Du einen Button brauchst. `optionen` ist optional und kennt dieselben Einstellungen wie die Attribute, z. B. `{ width: "500", hideHeader: true }`.
`Formenio.on(event, callback)`	Hört auf ein Event aller Formulare, z. B. `Formenio.on("submit", …)`. Der Name steht ohne `formenio:`.
`Formenio.off(event, callback)`	Entfernt einen Listener wieder.
`Formenio.scan(element)`	Sucht nach neuen Elementen mit `data-form`. Das ist normalerweise nicht nötig (siehe unten).
`Formenio.version`	Die Version des Scripts.

Einzelnes Formular

Formenio.get() und Formenio.open() geben ein Objekt mit diesen Funktionen zurück:

Funktion	Beschreibung
`setValues({ feldId: "Wert" })`	Füllt Felder vor, auch nachdem das Formular geladen ist. Bei Mehrfachauswahl übergibst Du ein Array: `{ feldId: ["a", "b"] }`.
`on(event, callback)` / `off(event, callback)`	Hört nur auf Events dieses Formulars.
`open()` / `close()`	Öffnet oder schließt das Popup bzw. das Vollbild.
`reload()`	Lädt das Formular neu, z. B. um es nach dem Absenden zurückzusetzen.
`destroy()`	Entfernt das Formular.

Für setValues gelten dieselben Regeln wie beim Vorausfüllen per Link: Die Werte werden geprüft, ungültige ignoriert, und Dateifelder lassen sich nicht vorausfüllen.

withFormenio(function (Formenio) {
  setTimeout(function () {
    Formenio.open("DEIN-FORMULAR", { hideHeader: true });
  }, 20000);
});

Beispiel: Produkt vorausfüllen

withFormenio(function (Formenio) {
  Formenio.get("#anfrage").setValues({ feldId: "Produkt A" });
});

React, Vue und andere Single-Page-Apps

Das Script erkennt Elemente mit data-form automatisch, auch wenn Deine App sie erst später einfügt, entfernt oder das Attribut ändert. Binde das Script einmal ein, z. B. in Deiner index.html, und rendere das Element dort, wo das Formular erscheinen soll:

export function Kontakt() {
  return <div data-form="DEIN-FORMULAR" data-hide-header="true" />;
}

Änderst Du data-form, lädt das Script das neue Formular. Entfernt Deine App das Element, räumt das Script das Formular auf.

Content Security Policy

Nutzt Deine Website eine Content Security Policy, erlaube https://app.formenio.de für:

script-src (das Script)
frame-src (das Formular)

Script einbinden​

Alle Attribute​

Events​

Beispiel: Conversion zählen​

JavaScript-API​

Formenio​

Einzelnes Formular​

Beispiel: Popup nach 20 Sekunden​

Beispiel: Produkt vorausfüllen​

React, Vue und andere Single-Page-Apps​

Content Security Policy​