Zuletzt geändert am:
Dieser Artikel beschreibt, wie Sie Formcentric-Formulare in Ihre Website einbetten.
Installieren Sie zunächst die React-Komponente in Ihrem Projekt:
Wenn Sie zusätzlich Theme-Ressourcen aus dem Formcentric-Client-Paket verwenden möchten, installieren Sie optional auch:
Wenn Sie lokale SCSS-Dateien eines Themes einbinden möchten, benötigen Sie außerdem SASS, zum Beispiel mit Vite:
Die Einbettung erfolgt über die Komponente FormcentricForm. Die Konfiguration wird über Props übergeben. data-fc-* Attribute und ein globaler Initialisierungsaufruf sind für die React-Integration nicht erforderlich.
Ein einfaches Beispiel:
Neben den Props am einzelnen FormcentricForm unterstützt React zwei weitere Ebenen für gemeinsame Defaults:
| Quelle | Reichweite | Priorität | Beschreibung |
browser-globale Defaults über configure(...) oder window.formcentric |
gesamte Browser-Seite | niedrig | werden vom zugrunde liegenden SDK-Mount als Defaults gelesen |
FormcentricConfigProvider |
React-Teilbaum | mittel | liefert subtree-weite Defaults für alle FormcentricForm Komponenten darunter |
Props an FormcentricForm |
einzelne Form | hoch | überschreiben Browser-Globals und Provider-Defaults |
Dabei gilt:
| Thema | Verhalten |
| verschachtelte Provider | Mehrere FormcentricConfigProvider werden zusammengeführt. Innere Provider überschreiben äußere Werte. |
| Objektwerte | requestHeaders, themeVariables und configuration werden zusammengeführt. Bei gleichen Schlüsseln gewinnt die nähere beziehungsweise lokale Konfiguration. |
| Remount-Verhalten | Änderungen an Provider-Defaults oder browser-globalen Defaults wirken nicht automatisch auf bereits laufende Formulare. Für eine laufende Instanz muss zusätzlich remountKey geändert oder die Komponente neu gemountet werden. |
| Static-only | dynamicInit ist kein React-Prop und hat für komponentenbasierte Mounts keine Wirkung. |
Die vollständige Liste der gemeinsamen Keys und ihrer Semantik steht zentral in Formcentric Client Allgemein.
Nicht als gemeinsame Defaults gedacht sind insbesondere embedId, formDefinition, vars, params, refs, formName, instanceId, conflictBehavior, remountKey, containerProps, onReady und onError.
Beispiel mit FormcentricConfigProvider:
Für browser-globale Defaults außerhalb von React-spezifischem Code kann zusätzlich configure(...) aus @formcentric/client verwendet werden.
Die Theme-Ressourcen können direkt als SCSS und JavaScript in die Anwendung integriert werden.
Beachten Sie dabei, dass die Anwendung für die Verwendung von SCSS konfiguriert sein sollte.
Mit Vite genügt es, hierfür SASS zu installieren:
Danach können Sie die Styles des ausgewählten Themes in eine eigene index.scss Datei importieren:
Importieren Sie anschließend die Theme-Dateien in Ihre React-Anwendung:
Wenn Sie Theme-Variablen direkt übergeben möchten, können Sie diese zusätzlich als Prop setzen:
Die React-Komponente ist als Integrations-Bridge konzipiert und nicht als vollständig kontrolliertes React-Widget. Die meisten Props wirken nur beim Initialisieren der Form.
Wenn sich Konfigurationswerte zur Laufzeit ändern, sollte das Formular explizit neu initialisiert werden. Hierfür steht das Prop remountKey zur Verfügung.
Beispiel:
Für einfache Integrationsfälle können optionale Callbacks verwendet werden:
onReady: wird nach erfolgreicher Initialisierung aufgerufenonError: wird bei Initialisierungs- oder Laufzeitfehlern aufgerufen
Beispiel:
onReady signalisiert, dass die Initialisierung erfolgreich abgeschlossen wurde. Es ist jedoch kein separater Garant für einen „ersten sichtbaren Render-Zeitpunkt“ des Formulars.
