Last updated:
This article describes how Formcentric forms are embedded into a website.
As a first step, install the Formcentric client in your project:
If you want to bundle theme assets locally, you can also use the supplied dist files in the same package.
Embedding is established with mount(element, config) from @formcentric/client.
A simple example:
The same with a DOM element:
In addition to the local mount(element, config) configuration, the SDK can evaluate browser-global defaults. These defaults are not Static-specific, but are also used by SDK-based integrations.
| Mechanism | Description |
configure({...}) from @formcentric/client |
Validates the browser-global defaults and replaces default values set previously. |
Direct mutation of window.formcentric |
Sets browser-global defaults directly on the window object. This also works without a previous configure(...) call. |
Note the following:
| Topic | Principle |
| Priority |
Local mount() configuration overrides browser-global defaults. |
| Object values |
requestHeaders, themeVariables and configuration are put together from the global and local configuration. If keys are identical, the local configuration wins. |
| Snapshot behaviour |
Browser-global defaults are read during a mount() call. Later changes do not retroactively affect instances already mounted. |
Repeat configure(...) |
Another call replaces browser-global defaults set previously, instead of extending them step by step. |
| Static only |
Although dynamicInit can be set browser-global, it is not evaluated by the SDK mount itself. |
The full list of the common browser-global default keys and their technical meanings are given in the main Formcentric Client General documentation.
In the SDK, important keys not set as browser-global are embedId, formDefinition, vars, params, refs, formName, instanceId and conflictBehavior.
Example:
If your application bundles theme assets itself, you import these before mounting and deactivate the runtime post-loading of the theme and templates.
Example with dist assets from @formcentric/client:
If you want to use runtime loading, either configure themeDir and theme or explicit URLs such as themeUrl, templateUrl and themeVariableUrl.
mount() returns a FormInstance with lifecycle methods and a ready promise.
Example:
Note the following:
ready is triggered after successful initialisation.reload() re-initialises the form in the same container.stop() terminates the running instance but leaves the target element in the DOM.unmount() removes the form and performs a full cleanup for the instance.
For stricter lifecycle sequencing in the SPA code, reload(), stop() and unmount() should each be awaited.
The SDK integration is restart-based. Configuration values are applied on initialisation and not carried across live to a running instance automatically.
If you change configuration values, the embedding should be re-established explicitly. By await form.unmount() followed by a repeat mount(), for example, or via await form.reload() if container and identity should intentionally remain the same.
Note the following:
embedId or formDefinition should normally lead to a fresh mount.conflictBehavior: 'stop-existing' should be set.For simple integration projects, optional callbacks can be passed directly in the configuration:
onReady: is called after successful initialisationonError: is called after initialisation errors or runtime errorsExample:
onReady signals that the initialisation has been successfully completed. This is not a dedicated signal for an initial visible render timestamp.
