Konfiguration

Zuletzt geändert am:

Dieser Artikel beschreibt, wie Sie Formcentric konfigurieren und welche Anpassungsmöglichkeiten Ihnen zur Verfügung stehen.

Konfigurationsquellen

Die meisten Formcentric-Konfigurationswerte sind nicht integrationsspezifisch. Unterschiedlich sind vor allem:

  1. die Quelle, aus der ein Wert gelesen wird
  2. die Schreibweise im jeweiligen Integrationspfad
  3. einige wenige Static- oder Wrapper-spezifische Zusatz-APIs

Priorität und Default-Ketten

Je nach Integrationspfad kommen unterschiedliche Konfigurationsquellen mit klarer Priorität zum Einsatz:
Integrationspfad Lokale Konfiguration Gemeinsame Defaults Browser - globale Defaults Bemerkung
Static data-fc-* am Formular-Container - window.formcentric oder
configure(...)		 lokale Container-Attribute überschreiben browser-globale Defaults
SDK mount(element, config) - window.formcentric oder
configure(...)		 mount() ist config-authoritative
React Props an FormcentricForm FormcentricConfigProvider window.formcentric oder
configure(...)		 Props überschreiben Provider-Defaults und Browser-Globals
Vue Props an FormcentricForm provideFormcentricConfig(...) window.formcentric oder
configure(...)		 Props überschreiben Provider-Defaults und Browser-Globals
Angular-Wrapper auf SDK-Basis projektspezifische Inputs oder Wrapper-Config projektspezifisch window.formcentric oder
configure(...)		 orientiert sich in der Regel am SDK

Für alle Pfade gilt zusätzlich:
Thema Verhalten
Objektwerte requestHeaders, themeVariables und configuration werden zwischen Default- und lokaler Konfiguration zusammengeführt. Bei gleichen Schlüsseln gewinnt die nähere beziehungsweise lokale Konfiguration.
Laufende Instanzen Änderungen an Defaults wirken nicht rückwirkend auf bereits laufende Instanzen. Sie greifen erst bei einer neuen Initialisierung oder einem kontrollierten Re-Mount.
Browser-globale Defaults configure(...) ersetzt die zuvor gesetzten browser-globalen Defaults, statt sie schrittweise zu erweitern.
Static-only data-fc-watch, dynamicInit und initFormcentric() haben keine direkte Entsprechung im SDK- oder Komponenten-Mount.

Gemeinsame Formcentric-Keys

Die gemeinsame Semantik der Formcentric-Keys ist für Static, SDK, React, Vue und SDK-basierte Angular-Wrapper weitgehend identisch. React und Vue übernehmen die SDK-Key-Namen als Top-Level-Props. In Vue-Templates werden sie üblicherweise in kebab-case geschrieben.

Identifikation und Formquelle:
Zweck Static lokal Browser-global SDK / React / Vue / Angular-Wrapper Hinweise
Formular-ID data-fc-id - embedId muss lokal gesetzt werde
Formular-Definition data-fc-form-definition - formDefinition Alternative zu embedId; nicht browser-global
Basis-URL data-fc-src-url srcUrl srcUrl Delivery-Basis-URL
Daten-URL data-fc-data-url dataUrl dataUrl überschreibt den Headless-Endpunkt
Runtime-URL data-fc-formapp-url formappUrl formappUrl überschreibt den Pfad zu formapp.js
Design-URL data-fc-design-url designUrl designUrl überschreibt Design- oder Theme-Ladepfade
Theme und Assets:
Zweck Static lokal Browser-global SDK / React / Vue / Angular-Wrapper Hinweise
Theme-Verzeichnis data-fc-theme-dir themeDir themeDir für verzeichnisbasiertes Theme-Laden
Theme-Name data-fc-theme theme theme zusammen mit themeDir
Theme-CSS data-fc-theme-url themeUrl themeUrl explizite Stylesheet-URL
Theme-Variablen-URL data-fc-theme-variable-url themeVariableUrl themeVariableUrl explizite URL zu _variables.json
Template-URL data-fc-template-url templateUrl templateUrl explizite URL zum Theme-Script
Theme-Variablen data-fc-theme-variables themeVariables themeVariables Objektwerte werden mit Defaults zusammengeführt
Theme-Load überspringen data-fc-skip-theme-load skipThemeLoad skipThemeLoad nur wirksam, wenn explizit gesetzt
Template-Load überspringen data-fc-skip-templates-load skipTemplatesLoad skipTemplatesLoad nur wirksam, wenn explizit gesetzt
Form-Load überspringen data-fc-skip-form-load skipFormLoad skipFormLoad fortgeschrittene Option
Request, Sprache und Runtime:
Zweck Static lokal Browser-global SDK / React / Vue / Angular-Wrapper Hinweise
Variablen data-fc-vars - vars nicht browser-global; URL-Parameter können Werte überschreiben
Request-Parameter data-fc-params - params nicht browser-global
Refs data-fc-refs - refs nicht browser-global
Bearer-Token data-fc-token token token Authorization-Header
Zusätzliche Header data-fc-request-headers requestHeaders requestHeaders Objektwerte werden zusammengeführt
Sprache data-fc-language language language bevorzugte Sprache
Locale data-fc-locale locale locale Fallback für Accept-Language, wenn language fehlt
Übersetzungsdatei data-fc-locales-path localesPath localesPath Pfad zu einer eigenen JavaScript-Datei mit Übersetzungen
Formularname data-fc-name - formName nicht browser-global
Instanz-ID data-fc-instance-id - instanceId nicht browser-global
Content-Handler data-fc-content-handler contentHandler contentHandler Runtime-Option
Umgebung data-fc-env env env preview, live, vestibule_live
Parent URL data-fc-parent-url parentUrl parentUrl Rückkehr- oder Double-Opt-in-Kontext
Zusatzkonfiguration data-fc-configuration configuration configuration Objektwerte werden zusammengeführt
Layout, Debugging und Übersetzungen:
Zweck Static lokal Browser-global SDK / React / Vue / Angular-Wrapper Hinweise
Maximale Breite data-fc-max-width maxWidth maxWidth Layout-Hinweis für den Container
Feste Höhe data-fc-height height height auf Mobilgeräten nicht immer strikt erzwungen
Debugging data-fc-debug debug debug zusätzliche Debug-Ausgaben

Ausgenommene Keys

Nicht zu den gemeinsamen Keys gehören vor allem:

  1. Static-only:
    data-fc-watch, data-fc-dynamic-init, window.formcentric.dynamicInit, window.formcentric.initFormcentric()
  2. SDK-only: conflictBehavior, onReady, onError
  3. React-only: FormcentricConfigProvider, remountKey, containerProps
  4. Vue-only: provideFormcentricConfig(...), remountKey, containerProps, @ready, @error

Syntax- und integrationsspezifische Details

Für syntax- oder integrationsspezifische Details siehe:

  1. client.md für Static-Markup, Script-Tag und window.formcentric
  2. client-sdk.md für mount() und SDK-spezifische Optionen
  3. client-react.md für React-spezifische Wrapper-Themen
  4. client-vue.md für Vue-spezifische Wrapper-Themen

Window-Object

Das globale Objekt window.formcentric ist die zentrale Steuerungsoberfläche der Static-Integration. Teile davon werden auch von der Runtime und der Event API verwendet.

Wichtige Hinweise

  1. configure() validiert browser-globale Defaults und ersetzt zuvor gesetzte Default-Werte.
  2. stopAll, unmountAll und die Lifecycle-Methoden laufender Instanzen sind asynchron und liefern Promise<void>.
  3. initFormcentric() stößt einen Static-Scan an, liefert selbst aber kein Promise.
  4. setInstanceOptions() wirkt nur vor der Initialisierung. Für bereits laufende Instanzen wird es ignoriert.
  5. on, once und off für die Event API werden mit der Formapp-Runtime bereitgestellt.
  6. on() und once() geben jeweils eine Unsubscribe-Funktion zurück.

Struktur

Die aktuelle Struktur lässt sich vereinfacht so zusammenfassen:

Beispiele

Globale Aktivierung von Debugging, Dynamic Init und Übersetzungen:

Browser-globale Defaults nach dem Laden des Clients validiert neu setzen:

Instanzoptionen vor der Initialisierung setzen:

Laufende Instanz lesen und stoppen:

Höhen und Breiten

Standardmäßig wächst ein Formular mit seinem Inhalt. Wenn feste Maße oder Begrenzungen gewünscht sind, können diese je nach Integrationspfad unterschiedlich gesetzt werden:

  1. Static über data-fc-height und data-fc-max-width
  2. SDK und Komponenten über height, maxWidth oder Styles am Wrapper-Element
  3. alternativ direkt über eigenes CSS am Formular-Container

Beispiel im Static-Markup

Parent URL

parentUrl beziehungsweise data-fc-parent-url dient dazu, Zustände der einbettenden Anwendung bei Double-Opt-in- oder Rückkehr-Szenarien wiederherzustellen.

Wenn kein Wert gesetzt ist, wird als Fallback die aktuelle Seiten-URL verwendet.

Beispiel:

Captcha Provider

Captcha-bezogene Einstellungen werden über die zusätzliche Konfiguration übergeben:

  1. Static über data-fc-configuration als JSON-String
  2. SDK und Komponenten über configuration als Objekt
Unter captcha.providers[].properties werden die Provider-spezifischen Laufzeitoptionen gesetzt:
Key Typ Default Bedeutung
src string - URL des Provider-SDKs. {{language}} wird mit dem Sprachkürzel ersetzt. Der Wert darf leer bleiben, wenn das SDK host-seitig bereitgestellt wird oder aus Kompatibilitätsgründen kein automatisches Nachladen konfiguriert werden soll.
loadSdk boolean true Steuert, ob der Client das Provider-SDK selbst nachlädt. Bei false muss das SDK bereits vor der Initialisierung des Clients durch die Host-Seite vorhanden sein.

Beispiel:

Beispiel mit host-seitig geladenem SDK:

Formulare mit dynamischen Werten vorbelegen

Formulare können sowohl über URL-Parameter als auch über Konfiguration vorbelegt werden.

Ein wichtiges gemeinsames Verhalten ist:

  1. URL-Parameter werden zusätzlich berücksichtigt
  2. wenn URL-Parameter und Konfiguration denselben Schlüssel setzen, überschreibt der URL-Parameter den Konfigurationswert

Vorbelegen über URL-Parameter

Beispiel:

Vorbelegen über Konfigurationsattribut

Static:

SDK oder Komponenten:

Eigene Übersetzungen einbinden

Eigene Übersetzungen können in allen Integrationspfaden eingebunden werden:

  1. Static: data-fc-locales-path oder window.formcentric.localesPath
  2. SDK und Komponenten: localesPath

Die Datei muss als JavaScript-Modul vorliegen und export default verwenden.

Beispiel:

Hinzufügen von neuen Sprachen und Übersetzungsschlüsseln

Feedback

ISO/IEC 27001 Icon
IT-Mittelstand Software Hosted in Germany
IT-Mittelstand Software Made in Germany