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
Klassische Runtime-URL data-fc-formapp-url formappUrl (deprecated) - ü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 und für alle Requests der Instanz verwendet.
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
Übersetzungs-Overrides - - locales Objekt mit Übersetzungs-Overrides; erhält date-fns- und Upload-Locale-Objekte per Referenz. Nur über SDK oder Komponenten verfügbar.
Formularname data-fc-name - formName nicht browser-global
Instanz-ID data-fc-instance-id - instanceId nicht browser-global
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. Formcentrich Client Static für Static-Markup, Script-Tag und window.formcentric
  2. Formcentric Client SDK für mount() und SDK-spezifische Optionen
  3. Formcentric Client React Cloud für React-spezifische Wrapper-Themen
  4. Formcentric Client Vue Cloud 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 über ein locales-Objekt oder eine localesPath-Datei bereitgestellt werden.

  1. locales: SDK- und Komponenten-Integrationen können Übersetzungs-Overrides direkt als JavaScript-Objekt übergeben. Locale-Objekte für Datepicker und Datei-Upload bleiben dabei einschließlich ihrer Funktionen per Referenz erhalten. Das Objekt ist weder als data-fc-*-Attribut noch als browser-globaler Default auf window.formcentric verfügbar.
  2. localesPath: URL zu einem JavaScript-Modul mit export default, das zur Laufzeit geladen wird. In Static-Integrationen wird sie über data-fc-locales-path oder window.formcentric.localesPath gesetzt. SDK und Komponenten unterstützen ebenfalls localesPath.

Werden beide Optionen angegeben, hat locales Vorrang.

Vorhandene Übersetzungen anpassen

Für eine bereits mitgelieferte Sprache genügt ein Text-Patch. Die Übersetzungsschlüssel können direkt unter dem Sprachschlüssel oder innerhalb von resources stehen.

Neue Sprachen ergänzen

Für eine nicht mitgelieferte Sprache benötigen Sie ein vollständiges Locale-Modul mit:

  1. resources: Formcentric-Übersetzungen
  2. dateLocale: Locale-Objekt aus date-fns für den Datepicker
  3. uploadLocale: Locale-Objekt aus @uppy/locales für den Datei-Upload

Ein reiner Text-Patch lässt Datepicker und Datei-Upload bei einer nicht mitgelieferten Sprache englisch.

Sobald ein Eintrag resources, dateLocale oder uploadLocale enthält, wird er als strukturiertes Locale-Modul behandelt. Übersetzungsschlüssel müssen dann unter resources stehen. Zusätzliche Übersetzungsschlüssel auf derselben Ebene wie dateLocale oder uploadLocale werden ignoriert und als Warnung protokolliert.

Beispiel: Texte vorhandener Sprachen über eine localesPath-Datei überschreiben:

Beispiel: Locale-Objekte in einer gebündelten Integration übergeben

Importieren Sie die Locale-Objekte aus den npm-Paketen und übergeben Sie das locales-Objekt als SDK-Option beziehungsweise als Prop. Für neue Sprachen in gebündelten Integrationen verwenden Sie diesen Weg, damit die Funktionen der Locale-Objekte erhalten bleiben. Der folgende Ausschnitt zeigt die Struktur; ergänzen Sie unter resources die benötigten Formcentric-Übersetzungen. In Vue wird das Objekt über :locales="locales" übergeben, im SDK über die locales-Option von mount().

Beispiel: Neue Sprache ohne Bundler laden

In einer Static-Integration kann Ihre localesPath-Datei browserfertige Locale-Dateien importieren. Diese können von einem CDN oder von Ihrer eigenen Domain geladen werden.

Alternativ können Sie heruntergeladene Browser-Dateien laden, bevor Formcentric startet, und die Globals in locales.js verwenden:

Um das Locale-Verhalten während der Integration zu prüfen, aktivieren Sie den Debug-Modus (data-fc-debug="true" in Static/Legacy, debug: true im SDK oder die debug-Prop in React/Vue). Formcentric protokolliert dann Probleme beim Laden der Locales, etwa ungültige dateLocale- / uploadLocale-Objekte oder unvollständige Module für nicht ausgelieferte Sprachen, in der Browser-Konsole.

Die vollständige Liste der überschreibbaren Formcentric-Schlüssel steht unten; sie entspricht der im Paket ausgelieferten locales.js-Vorlage. Kopieren Sie sie, behalten Sie die benötigten Sprachschlüssel und kommentieren Sie die Einträge aus, die Sie ändern möchten:

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