Configuration

Last updated:

This article describes how Formcentric is configured and what customisation options are available.

Configuration sources

Most Formcentric configuration values are not integration-specific. Key differences are

  1. Source from which a value is read
  2. Syntax used for the respective integration path
  3. A few additional APIs that are Static-/wrapper-specific

Priority and default chains

Various configuration sources, with distinct priorities, are used, depending on the integration path:
Integration path Local configuration Common defaults Browser-global defaults Remark
Static data-fc-* am Formular-Container - window.formcentric or
configure(...)		 Local container attributes override browser-global defaults
SDK mount(element, config) - window.formcentric or
configure(...)		 mount() is config-authoritative
React Props an FormcentricForm FormcentricConfigProvider window.formcentric or
configure(...)		 Props override provider defaults and browser globals
Vue Props an FormcentricForm provideFormcentricConfig(...) window.formcentric or
configure(...)		 Props override provider defaults and browser globals
Angular wrapper based on SDK Project-specific inputs or wrapper config Project-specific window.formcentric or
configure(...)		 orientiert sich in der Regel am SDK
Also applicable for all paths:
Topic Principle
Object values requestHeaders, themeVariables and configuration are put together from the default and local configuration. If keys are identical, the nearer/local configuration takes priority
Running instances Changes to defaults do not retroactively affect instances already running. Instead, they take effect only after re-initialisation or a controlled re-mount.
Browser-global defaults configure(...) replaces browser-global defaults set previously, instead of extending them step by step.
Static only data-fc-watch, dynamicInit and initFormcentric() have no direct parallels in SDK or component mount.

Common Formcentric keys

The common semantic of the Formcentric keys is largely identical for Static, SDK, React, Vue and the SDK-based Angular wrapper. React and Vue apply the SDK key names as top-level props. In Vue templates, they are typically written in kebab-case.

Identification and form source:
Purpose Static local Browser global SDK / React / Vue / Angular wrapper Note
Form ID data-fc-id - embedId Must be set locally
Form definition data-fc-form-definition - formDefinition Alternative to embedId; not browser-global
Base URL data-fc-src-url srcUrl srcUrl Delivery base URL
Data URL data-fc-data-url dataUrl dataUrl Overrides headless endpoint
Runtime URL data-fc-formapp-url formappUrl formappUrl Overrides path to formapp.js
Design URL data-fc-design-url designUrl designUrl Overrides design or theme load paths
Theme and assets:
Purpose Static local Browser-global SDK / React / Vue / Angular wrapper Notes
Theme directory data-fc-theme-dir themeDir themeDir For directory-based theme loading
Theme name data-fc-theme theme theme Together with
themeDir
Theme CSS data-fc-theme-url themeUrl themeUrl Explicit stylesheet URL
Theme variable URL data-fc-theme-variable-url themeVariableUrl themeVariableUrl Explicit URL to _variables.json
Template URL data-fc-template-url templateUrl templateUrl Explicit URL to theme script
Theme variables data-fc-theme-variables themeVariables themeVariables Object values are combined together with defaults
Skip theme load data-fc-skip-theme-load skipThemeLoad skipThemeLoad Only active if set explicitly
Skip template load data-fc-skip-templates-load skipTemplatesLoad skipTemplatesLoad Only active if set explicitly
Skip form load data-fc-skip-form-load skipFormLoad skipFormLoad Advanced option

Request, language and runtime:
Purpose Static local Browser-global SDK / React / Vue / Angular wrapper Notes
Variables data-fc-vars - vars Not browser-global; URL parameters can override values
Request parameters data-fc-params - params Not browser-global
Refs data-fc-refs - refs Not browser-global
Bearer token data-fc-token token token Authorisation headers
Additional headers data-fc-request-headers requestHeaders requestHeaders Object values are combined together
Language data-fc-language language language Preferred language
Locale data-fc-locale locale locale Fallback for Accept-Language, if language is missing
Translation file data-fc-locales-path localesPath localesPath Path to your own JavaScript file with translations
Form name data-fc-name - formName Not browser-global
Instance ID data-fc-instance-id - instanceId Not browser-global
Content handler data-fc-content-handler contentHandler contentHandler Runtime option
Environment data-fc-env env env preview, live, vestibule_live
Parent URL data-fc-parent-url parentUrl parentUrl Returning user or double opt-in context
Additional configuration data-fc-configuration configuration configuration Object values are combined together
Layout, debugging and translations:
Purpose Static local Browser-global SDK / React / Vue / Angular wrapper Notes
Maximum width data-fc-max-width maxWidth maxWidth Layout instruction for the container
Fixed height data-fc-height height height Not always strictly enforced on mobile devices
Debugging data-fc-debug debug debug Additional debug output

Excluded keys

Important exceptions to the common keys include:

  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- or integration-specific details

For syntax- or integration-specific details, see:

  1. client.md for Static markup, script tag and window.formcentric
  1. client-sdk.md for mount() and SDK-spezifische Optionen
  2. client-react.md for React-specific wrapper topics
  3. client-vue.md for Vue-specific wrapper topics

Window object

The global window.formcentric object is the main control surface for the Static integration. Parts of this are also used by the runtime and the event API.

Important notes

  1. configure()validates browser-global defaults and replaces default values set previously.
  2. stopAll, unmountAll and the lifecycle methods of running instances are asynchronous and return Promise<void>.
  3. initFormcentric() triggers a Static scan, but does not itself return a Promise.
  4. setInstanceOptions() takes effect only before initialisation. It is ignored for instances already running.
  5. on, once and off for the event API are provided with the formapp runtime.
  6. on() and once() each return an unsubscribe function.

Structure

A simplified version of the current structure is presented below:

Examples

Global activation of debugging, dynamic init and translations:

Set and validate browser-global defaults again after loading the client:

Set instance options before initialisation:

Read and stop running instance:

Heights and widths

By default, a form will expand to match its content. If fixed dimensions or limits are required, these can be set in various ways, depending on the integration path:

  1. Static via data-fc-height and data-fc-max-width
  2. SDK and components via height, maxWidth or styles on the wrapper element
  3. Alternatively: direct via your own CSS on the form container

Static markup example

Parent URL

parentUrl and data-fc-parent-url are used to restore the states of the embedding application in double opt-in or returning user scenarios.

If no value is set, the current page URL is used as a fallback.

Example:

Captcha Provider

Captcha-related settings are passed via the additional configuration:

  1. Static via data-fc-configuration as a JSON string
  2. SDK and components via configuration as an object
Under captcha.providers[].properties , provider-specific runtime options are defined:
Key Type Default Description
src string - URL of the provider SDK. {{language}} is replaced with the language code. The value may be left empty if the SDK is provided by the host system or if automatic loading is disabled for compatibility reasons.
loadSdk boolean true Controls whether the client loads the provider SDK automatically. If set to false, the SDK must already be available on the host page before client initialization.

Example:

Example with host-provided SDK:

Preconfiguring forms with dynamic values

Form values can be preconfigured both via URL parameters and via a configuration.

Important common behaviours:

  1. URL parameters are also taken into account
  2. If a URL parameter and a configuration set the same key, the URL parameter value overrides the configuration value

Setting value with URL parameter

Example:

Setting value with configuration attribute

Static:

SDK or components:

Including your own translations

Your own translations can be included in all integration paths:

  1. Static: data-fc-locales-path oder window.formcentric.localesPath
  2. SDK and components: localesPath

The file must be provided as a JavaScript module and use export default.

Example:

Adding new languages and translation keys

Feedback

ISO/IEC 27001 Icon
IT-Mittelstand Software Hosted in Germany
IT-Mittelstand Software Made in Germany