@formcentric/client

Formcentric 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).

Field widths

If you want to customize field widths you can do so in _field.scss or any other css file included in your website. Please keep in mind that row calculations depend on these values, so if you decide to change them you should make sure that CORS is configured correctly. Formcentric client should be able to read the relevant css file programatically to extract your customized field widths.

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>

Further form div attributes

• data-fc-form-definition="" Parse an encrypted form definition to the client application (stringified JSON)
• data-fc-data-url="" Define the general asset url
• data-fc-formapp-url="" Define the url of the client js formapp.js
• data-fc-template-url Define the url of the template js file script.js
• data-fc-theme-url Define the url of the style css file styles.css
• data-fc-theme-variable-url Define the url of your css variables json file _variables.json
• data-fc-vars Define a variables object that should be send in the initial request (stringified JSON)
• data-fc-params Override window parameters that should be send in the initial request (stringified JSON)
• data-fc-refs Define a reference object that should be send in the initial request (stringified JSON)
• data-fc-parent-url Define a parent url that should be send in DOI (double optin) emails (see Double optin)

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
                    }

                    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.

Double optin

No configuration is needed if the embedded form is present during initial page loads. However, if the form is embedded in a single page application and only rendered when certain states are set. The following configuration is necessary to enable double optin.

Configure data-fc-parent-url attribute on the form div. This attribute can be used to parameterize the internal state of embedding single page applications. For example if the client is running in a modal open modal state when users click on the opt in link can be restored by storing the neccessary information as parameters in the parent url attribute. The embedding app should then be configured in a way that it restores the states necessary to render the form.

Example Double optin in SPA using React

const FormModal = () => {
    const [open, setOpen] = useState(false)

    useEffect(() => {
        const urlParams = new URLSearchParams(window.location.search)
        const formOpen = urlParams.get('formopen')
        if (formOpen) {
            setOpen(true)
        }
    }, [])

    return (
        <div
            data-fc-id='...'
            data-fc-parent-url='https://admiralcorp.com/?formopen=true'
        />
    )
}