## Table of Contents - [1.0 Description](#10-description) - [2.0 Embedding](#20-embedding) - [2.1 General Embedding](#21-general-embedding) - [2.1.1 Example](#211-example) - [2.2 Including a Local Theme](#22-including-a-local-theme) - [2.3 Dynamic Initialization and Reinitialization](#23-dynamic-initialization-and-reinitialization) - [2.4 Error Handling During Development](#24-error-handling-during-development) - [3.0 Configuration](#30-configuration) - [3.1 Form Container Attributes](#31-form-container-attributes) - [3.2 Script Tag Configuration](#32-script-tag-configuration) - [3.3 Global Configuration via window.formcentric](#33-global-configuration-via-windowformcentric) - [3.4 Parent URL / Double-Opt-in](#34-parent-url--double-opt-in) - [3.5 Pre-populating Forms with Dynamic Values](#35-pre-populating-forms-with-dynamic-values) - [3.6 Including Custom Translations](#36-including-custom-translations) - [4.0 Troubleshooting](#40-troubleshooting) # Formcentric Client ## 1.0 Description The Static integration of the Formcentric Client is designed for classic website and CMS embeddings. It is based on `formcentric.js`, `formapp.js`, `data-fc-*` attributes on the form container, and the global object `window.formcentric`. The application consists of two main modules: `formcentric.js` This module forms the outer shell of the application and handles the basic setup. It is responsible for: - initializing the Formcentric application on the embedding page - loading and applying design configurations - general configuration of the application `formapp.js` This module forms the core of the application and controls the form logic. It is responsible for: - dynamic rendering of forms - managing form state - communication with the Formcentric Headless server - handling user interactions The Static integration is intended for classic static pages and CMS environments. For module- or SDK-based integrations, the separate SDK documentation should be used. ## 2.0 Embedding ### 2.1 General Embedding For Formcentric forms to be displayed and used on a website, they must be correctly embedded. Embedding is done in a few steps. First, you need to make the required domain settings in the **My Domains** section under **Organization**. There you add the domains and/or subdomains of the websites where the forms will be embedded. Afterwards, you can copy the embed code and insert it into the HTML markup of the website where the form should be displayed. Here is the basic procedure: Insert Script Tag Insert the script tag in the `` or at the end of the `` of your website: ```html ``` Insert Form Container Insert the form container at the location where the form should be displayed: ```html
``` Note: - The script tag must contain the `defer` attribute. - The form container must be a `
` element. - The form ID `data-fc-id` must match the ID from the Formcentric editor. - You can embed multiple forms on a page by inserting multiple containers with different IDs. - After inserting the embed code, the form is automatically loaded and displayed. ### 2.1.1 Example ```html My Website

Welcome to My Website

``` ### 2.2 Including a Local Theme If theme resources should not be delivered by Formcentric but provided locally from your website, their paths can be configured directly on the form container. Two variants are available for this. Variant 1: Theme via theme directory and theme name ```html
``` Variant 2: Configure theme files explicitly ```html
``` ### 2.3 Dynamic Initialization and Reinitialization In Static mode, all existing form containers are initialized when the script loads. If containers are only inserted into the DOM later, three mechanisms are available. Manual reinitialization via `window.formcentric.initFormcentric()` ```html ``` This reinitializes all currently existing `
` containers. Automatic initialization of new containers via `data-fc-dynamic-init="true"` on the script tag ```html ``` This makes the client observe the DOM and automatically initialize newly added form containers. Reinitialization on attribute changes via `data-fc-watch="true"` on the form container ```html
``` This makes the client observe attribute changes on the form container. If an attribute value actually changes, the running instance is stopped and reinitialized with the new attributes. ### 2.4 Error Handling During Development In Static mode, no component-based error callback is available. For development, debugging is therefore used via `data-fc-debug` on the container, via `data-fc-debug` on the script tag, or via `window.formcentric.debug`. Example on the form container: ```html
``` ## 3.0 Configuration The shared semantics of Formcentric keys, the priority of configuration sources, and the mapping between Static, SDK, React, and Vue are centrally documented in [general.md](./01-general.md). This page therefore primarily describes: - the Static notation of shared keys as `data-fc-*` - Static-specific script tag attributes - the Static-specific usage of `window.formcentric` ### 3.1 Form Container Attributes Configuration in Static mode is primarily done via `data-fc-*` attributes on the form container. All attribute values are initially strings in HTML. JSON-based values must therefore be passed as JSON strings. The semantic meaning of the following fields is centrally described in [general.md](./01-general.md). Here we only cover the Static notation. #### 3.1.1 Identification and Form Source | Static Syntax | Equivalent | Note | | --- | --- | --- | | `data-fc-id` | Form ID / `embedId` | locally required if no form definition is used | | `data-fc-form-definition` | Form Definition / `formDefinition` | Alternative to `data-fc-id` | | `data-fc-src-url` | `srcUrl` | can additionally be set browser-globally as default | | `data-fc-data-url` | `dataUrl` | can additionally be set browser-globally as default | | `data-fc-formapp-url` | `formappUrl` | can additionally be set browser-globally as default | | `data-fc-design-url` | `designUrl` | can additionally be set browser-globally as default | #### 3.1.2 Request, Language and Metadata | Static Syntax | Equivalent | Note | | --- | --- | --- | | `data-fc-vars` | `vars` | JSON string; not browser-global | | `data-fc-params` | `params` | JSON string; not browser-global | | `data-fc-refs` | `refs` | not browser-global | | `data-fc-token` | `token` | can additionally be set browser-globally as default | | `data-fc-request-headers` | `requestHeaders` | JSON string with string values | | `data-fc-language` | `language` | can additionally be set browser-globally as default | | `data-fc-locale` | `locale` | can additionally be set browser-globally as default | | `data-fc-locales-path` | `localesPath` | can additionally be set browser-globally as default | | `data-fc-name` | Form name / `formName` | not browser-global | | `data-fc-instance-id` | `instanceId` | not browser-global | | `data-fc-env` | `env` | can additionally be set browser-globally as default | | `data-fc-parent-url` | `parentUrl` | can additionally be set browser-globally as default | | `data-fc-configuration` | `configuration` | JSON string; object values are merged with defaults | Important for `data-fc-vars`: - URL parameters are additionally considered in the initialization request. - If both `data-fc-vars` and URL parameters contain the same key, the URL parameter overwrites the value from `data-fc-vars`. #### 3.1.3 Theme and Assets | Static Syntax | Equivalent | Note | | --- | --- | --- | | `data-fc-theme-dir` | `themeDir` | can additionally be set browser-globally as default | | `data-fc-theme` | `theme` | can additionally be set browser-globally as default | | `data-fc-theme-url` | `themeUrl` | can additionally be set browser-globally as default | | `data-fc-theme-variable-url` | `themeVariableUrl` | can additionally be set browser-globally as default | | `data-fc-template-url` | `templateUrl` | can additionally be set browser-globally as default | | `data-fc-theme-variables` | `themeVariables` | JSON string; object values are merged with defaults | | `data-fc-skip-theme-load` | `skipThemeLoad` | only relevant if explicitly set | | `data-fc-skip-templates-load` | `skipTemplatesLoad` | only relevant if explicitly set | | `data-fc-skip-form-load` | `skipFormLoad` | advanced option | Note on theme behavior: - A local theme is internally only treated as a local theme if either `data-fc-theme-dir` and `data-fc-theme` are set together, or `data-fc-theme-url` and `data-fc-theme-variable-url` are set together. - For templates, additionally either `data-fc-template-url` or the combination of `data-fc-theme-dir` and `data-fc-theme` is required. #### 3.1.4 Layout and Debugging | Static Syntax | Equivalent | Note | | --- | --- | --- | | `data-fc-max-width` | `maxWidth` | can additionally be set browser-globally as default | | `data-fc-height` | `height` | can additionally be set browser-globally as default | | `data-fc-debug` | `debug` | can additionally be set browser-globally or on the script tag | | `data-fc-watch` | Static-only | observes attribute changes on the container | ### 3.2 Script Tag Configuration Additional Static-specific controls are evaluated on the script tag itself: | Attribute | Equivalent | Note | | --- | --- | --- | | `data-fc-debug="true"` | `debug` | Static-specific notation directly on the script tag | | `data-fc-dynamic-init="true"` | `dynamicInit` | Static-only; automatic initialization of newly added containers | Example: ```html ``` ### 3.3 Global Configuration via window.formcentric The available browser-global default keys are not primarily Static-specific. The same default values are also evaluated by the SDK and thus indirectly by React and Vue. What is Static-specific is primarily the direct work with `window.formcentric`. #### 3.3.1 Mechanisms | Mechanism | Typical Use | Description | | --- | --- | --- | | direct mutation of `window.formcentric` | Static, SDK, React, Vue | Sets browser-global defaults directly on the window object. This form works even before loading `formcentric.js`. | | `window.formcentric.configure({...})` | Static after loading `formcentric.js` | Validates the passed browser-global defaults and replaces the previously set default values. | | `configure({...})` from `@formcentric/client` | SDK, React, Vue | Functionally equivalent to `window.formcentric.configure({...})`, but imported directly from the client package in module-based integrations. | #### 3.3.2 Priority and Behavior The shared priority, merge semantics, and the list of browser-global default keys are centrally described in [general.md](./01-general.md). For Static, additionally: - `data-fc-*` attributes on the container override browser-global defaults. - `dynamicInit` is a Static-only extension. - Changes to browser-global defaults also take effect in the Static path only after a new initialization or reinitialization. #### 3.3.3 Available Browser-Global Default Keys The complete list of shared browser-global default keys is centrally available in [general.md](./01-general.md). In the Static path, `dynamicInit` is additionally added as a Static-only extension. #### 3.3.4 Window API for Static | API | Description | | --- | --- | | `window.formcentric.initFormcentric()` | Initializes all currently existing Static containers. | | `window.formcentric.stopAll()` | Stops all running instances. | | `window.formcentric.unmountAll()` | Unmounts all running instances. | | `window.formcentric.getInstance(embedId)` | Returns the current instance for an `embedId`. | | `window.formcentric.setInstanceOptions(embedId, options)` | Sets instance-specific options for a particular `embedId` before initialization. In code, this is ignored if the instance is already running. | Example for browser-global defaults before loading the script: ```html ``` Example for validated browser-global defaults after loading the script: ```html ``` ### 3.4 Parent URL / Double-Opt-in The semantic meaning of `parentUrl` is described in [general.md](./01-general.md). In the Static path, the same shared key is set as the attribute `data-fc-parent-url`. If `data-fc-parent-url` is not set, the client uses `window.location.href` by default. Example: ```html
``` ### 3.5 Pre-populating Forms with Dynamic Values The semantic meaning of `vars` and the shared behavior with URL parameters are described in [general.md](./01-general.md). In the Static path, the shared key is set as the attribute `data-fc-vars`. #### 3.5.1 Pre-populating via URL Parameters Example: ```text https://your-site.com/form?name=Max ``` When loading the form, the URL parameter is included in the initialization variables. #### 3.5.2 Pre-populating via Configuration Attribute ```html
``` ### 3.6 Including Custom Translations The shared semantics of `localesPath` and the structure of the translation file are described in [general.md](./01-general.md). In the Static path, this shared key can be set either locally via `data-fc-locales-path` or browser-globally via `window.formcentric.localesPath`. The file must be available as a JavaScript module and exported via `export default`. Example: ```html
``` Example localization file: ```js export default { de: { formcentric: { error: { required: 'Dieses Feld ist erforderlich.' } }, page: 'S.' }, 'en-US': { formcentric: { error: { required: 'This field is required.' } }, page: 'p.' } } ``` ## 4.0 Troubleshooting In case of problems, check in particular: - whether `data-fc-id` is correct - whether the form is published - whether the domain is enabled in Formcentric - whether the wrapper script is loading correctly - whether `defer` is set - whether `data-fc-src-url`, `data-fc-data-url`, `data-fc-formapp-url` or `data-fc-design-url` are set correctly - whether JSON attributes like `data-fc-vars`, `data-fc-params`, `data-fc-configuration` or `data-fc-theme-variables` contain valid JSON - whether for local themes the paths for styles, variables and templates are completely set - whether `data-fc-watch="true"` is set if attribute changes should trigger reinitialization - whether `data-fc-dynamic-init="true"` on the script tag or `window.formcentric.dynamicInit = true` is set if newly inserted containers should be automatically initialized - whether `window.formcentric.initFormcentric()` is called manually if containers are added after the initial page build - whether `data-fc-language` and `data-fc-locale` are set as expected - whether `data-fc-parent-url` is set if a specific return state should be restored for Double-Opt-in