@formcentric/client v1.0.7

Formcentric Standalone Client

Formcentric-Client package for rendering Formcentric-Headless Forms.

INSTALLATION

  npm install @formcentric/client

USAGE & EXAMPLES

To implement a form on your Page, two things are needed:

• A div with the data-attribute fc-id
• Execution of the @formcentric/client Script

The Client-Script needs to load the formapp.js, because of this the said file has to be served and reachable.

Theming

The Theme consists of:

• one CSS-File styles.css containing all styles with custom properties
• one JS-File script.js defining the templates for the input fields
• CSS-Custom-Properties _variables.json defined on the body or the embed-div itself

The client does not contain any theme information, and will only work if you are providing these requirements.

Customization

To create a custom theme, follow these steps in your app's root directory. This command generates a new theme, based on our default Formcentric theme, in the fc-themes folder. Optionally, you can base your custom theme on any of the other provided Formcentric themes by specifing its directory name in the second argument.

// npm
npm run fc-create-theme [fcThemeName]

// yarn
yarn fc-create-theme [fcThemeName]

// pnpm
pnpm fc-create-theme [fcThemeName]

Custom theme usage

To use your custom theme, bundle its templateEntry file to a single file script.js in your custom theme's root directory and specify the path on your formDiv (see example below).

EXAMPLE FORM-CONTAINER

<div
    data-fc-id="..."
    data-fc-data-url="https://formcentric.com/headless-server"
    data-fc-formapp-url="assets/formapp.js"
    data-fc-theme-dir="fc-themes"
    data-fc-theme="formcentric"
></div>

Configuration

Most of the configuration is done via the data-attributes on the embed-div, but some scenarios may call for mor advanced control over the rendering app. This is done via the window.formcentric Object. It follows the following interface.

Most of the options are readonly and should not be touched.

declare interface Window {
    formcentric?: {
        initFormcentric?: (debugMode: boolean) => void
        formapp?: {
            templates?: fcTemplates
            start?: Start
            instances?: {
                [embedId: string]: {
                    reSetFormDefinition?: (reSetFormDef: fcClientFormDefinition) => void
                    initElement?: HTMLElement
                    options?: {
                        baseUrl: string
                        embedId: string
                        instanceId: string
                        persist: boolean
                        formDefinition?: fcClientFormDefinition
                        contentHandler?: string
                        debug?: boolean
                        locale?: string
                        env: 'live' | 'preview' | 'vestibule_live'
                    }

                    stop?: VoidFunction
                    unmount?: VoidFunction
                    initialRequestHeaders?: Record<string, string>
                }
            }
        }
    }
}

Especially useful are the initialRequestHeaders. They are passed to the initial Request for getting the formDefinition.

Example for custom request Headers

<script>
    window.formcentric ??= {}
    window.formcentric.formapp ??= {}
    window.formcentric.formapp.instances ??= {}
    window.formcentric.formapp.instances['b1265a82-0eab-47ac-hhhh-948b18e423c5'] = {
        initialRequestHeaders: { testHeader: '123' },
    }
</script>

EXAMPLE CLIENT SCRIPT-TAG

<script
    src="./formcentric.js"
    defer
></script>

Everytime formcentric.js gets executed, every Form-Container (identified by data-fc-id) gets initialized as a form. You can manually call window.formcentric.initFormcentric() to setup and start the client for all divs with and fc-id data-attribute.