# Die Einbindung

## Das Formular in die Website einsetzen

Fügen Sie den folgenden Code an der Stelle Ihrer Website ein, an der das Formular erscheinen soll. Verwenden Sie dafür den HTML-Bereich beziehungsweise einen geeigneten Codeblock Ihres Redaktionssystems.

```html
<div id="gwatch-iframe"></div>
<script
    src="[SCRIPT-URL]"
    data-event-key="[EVENT-KEY]"
    data-url-partial="[FORMULAR-TYP]">
</script>

```

Ersetzen Sie die drei Angaben in eckigen Klammern vollständig durch die Werte Ihrer Event-Administration. Die Anführungszeichen bleiben erhalten.

<table id="bkmrk-angabe-was-geh%C3%B6rt-hi"><thead><tr><th>Angabe</th><th>Was gehört hinein?</th></tr></thead><tbody><tr><td>`src`</td><td>Die Skript-URL, beispielsweise `https://gwatch.events/iframe.js`.</td></tr><tr><td>`data-event-key`</td><td>Der Event-Key der Veranstaltung.</td></tr><tr><td>`data-url-partial`</td><td>Einer der Werte `registration`, `tbc`, `onl`, `fbk` oder `sso`.</td></tr></tbody></table>

**Die Reihenfolge ist wichtig:** Das `<div>` muss bereits vorhanden sein, wenn das Skript ausgeführt wird. Platzieren Sie es deshalb wie im Beispiel **vor dem `<script>`**.

Das Skript erzeugt den IFrame innerhalb dieses Elements. Lassen Sie den Platzhalter leer: Bereits enthaltene Texte oder andere Elemente werden beim Laden des Formulars ersetzt. Die gewählte ID darf auf der Seite nur einmal vorkommen.

## Beispiel für eine Online-Registrierung

```html
<div id="gwatch-iframe"></div>
<script
    src="https://gwatch.events/iframe.js"
    data-event-key="[EVENT-KEY]"
    data-url-partial="registration">
</script>

```

Hier ist die **Online-Registrierung** voreingestellt. Ersetzen Sie `[EVENT-KEY]` und verwenden Sie gegebenenfalls die abweichende Skript-URL Ihrer Installation. Öffnen Sie anschließend die veröffentlichte Website, um die Einbindung zu prüfen; manche Redaktionssysteme führen Skripte in ihrer Bearbeitungsvorschau nicht aus.

## Breite und Höhe des Formularfensters

Der IFrame nutzt **100 % der Breite seines übergeordneten Elements**. Ist die Spalte Ihrer Website schmal, bleibt auch das Formularfenster entsprechend schmal. Passen Sie in diesem Fall das Layout der Zielseite an.

Die voreingestellte Höhe beträgt **`100dvh`**. Das entspricht der aktuellen Höhe des sichtbaren Browserbereichs. Die Höhe wird nicht automatisch an die Länge des Formularinhalts angepasst. Bei langen Formularen kann deshalb im Formularfenster gescrollt werden müssen.

Mit `data-height` können Sie eine andere CSS-Höhe vorgeben, beispielsweise **`900px`**. Eine Zahl ohne Einheit, etwa `900`, ist dafür nicht geeignet.

## Einstellungen im Überblick

Die folgenden Angaben sind optional und werden am `<script>` ergänzt.

<table id="bkmrk-einstellung-vorgabe-"><thead><tr><th>Einstellung</th><th>Vorgabe</th><th>Wirkung und Beispiel</th></tr></thead><tbody><tr><td>`data-target`</td><td>`gwatch-iframe`</td><td>ID des Elements, in das das Formular geladen wird. Bei `data-target="veranstaltungsformular"` muss das Element `<div id="veranstaltungsformular"></div>` heißen. Geben Sie die ID ohne `#` an.</td></tr><tr><td>`data-height`</td><td>`100dvh`</td><td>Höhe des IFrames als CSS-Wert, zum Beispiel `data-height="900px"`.</td></tr><tr><td>`data-scroll-offset`</td><td>`0`</td><td>Abstand in Pixeln oberhalb des Formulars beim automatischen Zurückscrollen, zum Beispiel `data-scroll-offset="80"` für eine feststehende Kopfzeile. Hier wird nur eine ganze Zahl ohne `px` eingetragen.</td></tr></tbody></table>

## Beispiel mit eigener ID, Höhe und Scroll-Abstand

```html
<div id="veranstaltungsformular"></div>
<script
    src="https://gwatch.events/iframe.js"
    data-event-key="[EVENT-KEY]"
    data-url-partial="registration"
    data-target="veranstaltungsformular"
    data-height="900px"
    data-scroll-offset="80">
</script>

```

In diesem Beispiel wird das Formular im Element **veranstaltungsformular** angezeigt. Das Fenster ist **900 Pixel hoch**. Beim automatischen Zurückscrollen bleiben **80 Pixel Abstand** zum oberen Fensterrand, damit eine feststehende Kopfzeile den Formularanfang nicht verdeckt.

## Was nach dem Absenden passiert

Wenn das GATEWatch-Formular nach einer erfolgreichen Übermittlung ausgeblendet wird und den Abschluss meldet, scrollt die umgebende Website zurück zum Anfang des eingebetteten Formulars. So wird der dort angezeigte Abschluss wieder sichtbar.

Dieses Verhalten hängt von der Erfolgseinstellung des jeweiligen Formulars ab. Es wird nicht durch jeden Klick oder jede Fehlermeldung ausgelöst. `data-scroll-offset` verändert nur die Zielposition dieses Scrollens, nicht die Höhe des Formulars.

Prüfen Sie den Abstand auf Ihrer Website mit ihrer tatsächlichen Kopfzeile. Ein positiver Wert lässt oberhalb des Formulars entsprechend mehr Platz.

## Persönliche Links und URL-Parameter erhalten

GATEWatch-Links können zusätzliche Angaben hinter einem `?` enthalten. Das Skript liest bestimmte Parameter der umgebenden Website und verwendet sie für den Formularaufruf.

<table id="bkmrk-parameter-verwendung"><thead><tr><th>Parameter</th><th>Verwendung</th></tr></thead><tbody><tr><td>`url-partial`</td><td>Bestimmt den Formulartyp für diesen Aufruf und kann die Vorgabe aus `data-url-partial` ersetzen.</td></tr><tr><td>`type`</td><td>Ergänzt den konkreten Aufruf, beispielsweise bei einem persönlichen Gastlink.</td></tr><tr><td>`key`</td><td>Übergibt den Schlüssel des persönlichen Formularaufrufs.</td></tr><tr><td>`locale`</td><td>Wird als Sprachangabe an das Formular weitergereicht.</td></tr><tr><td>`GUEST_…`</td><td>Entsprechend benannte Parameter werden an das Formular weitergereicht. Ihre Verwendung hängt vom jeweiligen Formular ab.</td></tr></tbody></table>

Sie müssen diese Parameter für gewöhnliche Einladungen nicht selbst zusammensetzen. Verwenden Sie die von GATEWatch erzeugten Links vollständig. Weiterleitungen, Linkverkürzungen oder die Website dürfen die benötigten Parameter nicht entfernen. Andere Parameter werden durch dieses Skript nicht automatisch weitergereicht.

## Die Einbindung prüfen

1. **Direkter Aufruf:** Öffnen Sie die Zielseite ohne zusätzliche Parameter. Erscheint das vorgesehene Formular der richtigen Veranstaltung?
2. **Darstellung:** Prüfen Sie eine breite und eine schmale Bildschirmansicht. Sind alle Felder und Schaltflächen erreichbar?
3. **Einladungslink:** Öffnen Sie einen neu erzeugten Link aus dem vorgesehenen Einladungsablauf. Stimmen Formular und Zugang?
4. **Übermittlung:** Führen Sie den vorgesehenen Ablauf vollständig aus. Prüfen Sie die Rückmeldung und, sofern eingerichtet, das Zurückscrollen zum Formularanfang.
5. **Kopfzeile:** Verdeckt eine feststehende Navigation den Formularanfang? Passen Sie gegebenenfalls `data-scroll-offset` an.

## Häufige Probleme

<table id="bkmrk-beobachtung-was-sie-"><thead><tr><th>Beobachtung</th><th>Was Sie prüfen sollten</th></tr></thead><tbody><tr><td>**Es erscheint kein Formular.**</td><td>Steht das `<div>` vor dem Skript? Stimmen seine ID und `data-target` überein? Sind Skript-URL, Event-Key und Formulartyp vollständig eingesetzt?</td></tr><tr><td>**Der Code wird als Text angezeigt.**</td><td>Verwenden Sie einen HTML- oder Codeblock, der Skripte ausführen darf, statt eines gewöhnlichen Textfelds.</td></tr><tr><td>**Das Skript wird entfernt oder blockiert.**</td><td>Lassen Sie die Website-Betreuung prüfen, ob das Redaktionssystem, ein Einwilligungsdialog oder die Sicherheitsrichtlinien der Website das externe Skript beziehungsweise den IFrame blockieren.</td></tr><tr><td>**Die falsche Veranstaltung erscheint.**</td><td>Vergleichen Sie Event-Key und Skript-URL mit den Angaben der Event-Administration.</td></tr><tr><td>**Es erscheint ein anderer Formulartyp als eingetragen.**</td><td>Prüfen Sie, ob die Seitenadresse einen Parameter `url-partial` enthält. Dieser kann die Vorgabe ersetzen.</td></tr><tr><td>**Ein persönlicher Link führt nur zum allgemeinen Einstieg.**</td><td>Kontrollieren Sie, ob die vollständigen URL-Parameter nach einer Weiterleitung noch vorhanden sind. Vergleichen Sie außerdem die hinterlegte alternative Formular-URL mit der tatsächlichen Zielseite.</td></tr><tr><td>**Das Formular ist zu schmal oder die Höhe passt nicht.**</td><td>Prüfen Sie die Breite des umgebenden Website-Elements und den Wert von `data-height`. Die Fensterhöhe wächst nicht automatisch mit dem Formularinhalt.</td></tr><tr><td>**Nach dem Absenden wird nicht nach oben gescrollt.**</td><td>Prüfen Sie zunächst, ob die Übermittlung erfolgreich war und das Formular für das Ausblenden im Erfolgsfall eingerichtet ist. Erst danach den Scroll-Abstand anpassen.</td></tr><tr><td>**Der Formularanfang verschwindet unter der Kopfzeile.**</td><td>Erhöhen Sie `data-scroll-offset` passend zur Höhe der feststehenden Kopfzeile.</td></tr></tbody></table>

**Für die Website-Betreuung:** Das Skript meldet fehlende oder ungültige Pflichtangaben sowie ein nicht gefundenes Zielelement in der Browserkonsole mit **„GWatch error:“**. Diese Meldung hilft, die Ursache einzugrenzen.

**Zur Vorbereitung:** [Voraussetzungen und Formulartypen](https://doc.gwatch.events/books/iframe-einbindung/page/voraussetzungen).