Zuletzt geändert am:
Dieser Artikel beschreibt, wie Sie Formcentric-Formulare in Ihre Website einbetten.
Installieren Sie zunächst den Formcentric-Client in Ihrem Projekt:
Wenn Sie Theme-Assets lokal bundeln möchten, können Sie zusätzlich die mitgelieferten Dist-Dateien desselben Pakets verwenden.
Die Einbettung erfolgt über mount(element, config) aus @formcentric/client.
Ein einfaches Beispiel:
Dasselbe mit einem DOM-Element:
Zusätzlich zur lokalen mount(element, config) Konfiguration kann das SDK browser-globale Defaults auswerten. Diese Defaults sind nicht Static-spezifisch, sondern werden auch von SDK-basierten Integrationen verwendet.
| Mechanismus | Beschreibung |
configure({...}) aus @formcentric/client |
Validiert die browser-globalen Defaults und ersetzt zuvor gesetzte Default-Werte. |
direkte Mutation von window.formcentric |
Setzt browser-globale Defaults direkt am Window-Objekt. Das funktioniert auch ohne vorherigen configure(...) Aufruf. |
Dabei gilt:
| Thema | Verhalten |
| Priorität |
Lokale mount() Konfiguration überschreibt browser-globale Defaults. |
| Objektwerte |
requestHeaders, themeVariables und configuration werden zwischen globaler und lokaler Konfiguration zusammengeführt. Bei gleichen Schlüsseln gewinnt die lokale Konfiguration. |
| Snapshot-Verhalten |
Browser-globale Defaults werden beim mount() Aufruf gelesen. Spätere Änderungen wirken nicht rückwirkend auf bereits gemountete Instanzen. |
erneutes configure(...) |
Ein weiterer Aufruf ersetzt die zuvor gesetzten browser-globalen Defaults, statt sie schrittweise zu erweitern. |
| Static-only |
dynamicInit kann zwar browser-global gesetzt werden, wird aber vom SDK-Mount selbst nicht ausgewertet. |
Die vollständige Liste der gemeinsamen browser-globalen Default-Keys und ihre fachliche Bedeutung stehen zentral in Client (Allgemein).
Nicht browser-global sind im SDK insbesondere embedId, formDefinition, vars, params, refs, formName, instanceId und conflictBehavior.
Beispiel:
Wenn Ihre Anwendung Theme-Assets selbst bundelt, importieren Sie diese vor dem Mounten und deaktivieren Sie das Runtime-Nachladen von Theme und Templates.
Beispiel mit Dist-Assets aus @formcentric/client:
Wenn Sie das Runtime-Laden verwenden möchten, konfigurieren Sie entweder themeDir und theme oder explizite URLs wie themeUrl, templateUrl und themeVariableUrl.
mount() liefert eine FormInstance mit Lifecycle-Methoden und einem Ready-Promise zurück.
Beispiel:
Dabei gilt:
ready wird nach erfolgreicher Initialisierung aufgelöst.reload() initialisiert das Formular im selben Container neu.stop() beendet die laufende Instanz, belässt das Zielelement jedoch im DOM.unmount() entfernt die Form und bereinigt die Instanz vollständig.Für eine striktere Lifecycle-Sequenzierung in SPA-Code sollten reload(), stop() und unmount() jeweils awaited werden.
Die SDK-Integration ist restart-basiert. Konfigurationswerte werden beim Initialisieren übernommen und nicht automatisch live in eine laufende Instanz übertragen.
Wenn sich Konfigurationswerte ändern, sollte die Einbettung explizit neu aufgebaut werden, zum Beispiel über await form.unmount() und anschließendes erneutes mount(), oder über await form.reload(), wenn Container und Identität bewusst gleich bleiben.
Dabei gilt:
embedId oder formDefinition sollten in der Regel zu einem frischen Mount führen.embedId stabil bleiben und conflictBehavior: 'stop-existing' gesetzt werden.Für einfache Integrationsfälle können optionale Callbacks direkt in der Konfiguration übergeben werden:
onReady: wird nach erfolgreicher Initialisierung aufgerufenonError: wird bei Initialisierungs- oder Laufzeitfehlern aufgerufenBeispiel:
onReady signalisiert, dass die Initialisierung erfolgreich abgeschlossen wurde. Es ist kein dediziertes Signal für einen ersten sichtbaren Render-Zeitpunkt.
