zengenti-forms-package

Contensis forms renderer

This is a package to allow you to render Contensis forms in your react/redux app. There are a number of prerequisites in order to get this to work, they are as follows:

Using this in your project

Install the package

npm i --save zengenti-forms-package

Import the sagas and reducers

Import the sagas and add them to your rootSaga function: e.g.

import { sagas as formSagas } from 'zengenti-forms-package';

Import the reducer: e.g.

import { reducer as FormsReducer } from 'zengenti-forms-package';

and add it to your combineReducer function, ensure your reducer key is called form: e.g.

const reducers = { form: FormsReducer, ...otherReducers };

Server-side reverse proxy

Import the server-side api proxy

import { formsApiProxy } from 'zengenti-forms-package/server';

Create the required api endpoints (where you would normally configure server-side features) by calling the imported function supplying the server-side express app instance e.g. formsApiProxy(app);

** this step is not required if you are overriding the rootUrl variable with FORMS_API_CONFIG

Render the Form in your React components

• Import the <Form> component and use it in JSX where it is needed: e.g.

import { Form } from 'zengenti-forms-package';

and supply it with a valid formId prop: e.g.

  <MyComponent>
    <Form formId={1234} />
  </MyComponent>

Suggested usage with Content Types and Entries

• Content type called form containing these fields[]:

"fields": [
  {
    "id": "formName",
    "name": {
      "en-GB": "Form Name"
    },
    "dataType": "string",
    "dataFormat": "",
    "description": {
      "en-GB": null
    },
    "default": null,
    "validations": {}
  },
  {
    "id": "formId",
    "name": {
      "en-GB": "Form - Content ID"
    },
    "dataType": "string",
    "dataFormat": "",
    "description": {
      "en-GB": null
    },
    "default": null,
    "validations": {}
  }
],

• Then in your content type or composer content add an entry picker linking back to form content type, this will give the editor the ability to select a particular form entry from the form content type:

• Essentially we are just trying to feed a prop called formId to the <Form ... /> component invocation.

Localisation

You can pass in a localisedPhrases prop to the Form component. e.g. <Form formId={1234} localisedPhrases={...} />

This is an object type where keys relate to specific phrases in the form.

The value will be rendered wherever that phrase is used.

Currently available keys:

key	type
required	string
optional	string
step	string
previousPage	string
nextPage	string
errorTitle	string

Note: the form component does not handle any language switching itself. All the localisedPhrases prop does is display the value of what you are passing to the key.

<Form formId={1234} localisedPhrases={{
  required: 'gofynnol',
  optional: 'dewisol',
  step: 'cam',
  previousPage: 'blaenorol',
  nextPage: 'nesaf',
  errorTitle: 'Wps!',
}} />

Overriding config variables

Ensure a global variable is available called FORM_API_CONFIG containing any of the following values you wish to override:

const FORM_API_CONFIG = {
  rootUrl: 'https://cms-mycms.cloud.contensis.com/',
  getFormUrl: '/REST/Contensis/content/GetFormSettings',
  uploadFileUrl: '/REST/UI/FormsModule/UploadFile',
};

This is normally available in a webpack file and added to the build via some define plugin.

** The server-side forms proxy will not be used if you are overriding rootUrl with the FORM_API_CONFIG global, instead this url will be called directly from the client

Recaptcha

Recaptcha v2 support has been added. For those curious here is the implementation used: https://developers.google.com/recaptcha/docs/display#auto_render

Requirements

Need a content type named formSettings With a field named recaptchaSiteKey

The form component will check your project for that site key.

How to test

Run npm run start and check your network tab for results from 'gstatic.com' you should return a recaptcha__en.js file. You will likely then get a message stating "Localhost is not in the list of supported domains". More detail can be found here: https://developers.google.com/recaptcha/docs/faq#im-getting-an-error-localhost-is-not-in-the-list-of-supported-domains.-what-should-i-do

Dependencies

• React
• React Helmet
• Redux
• Styled Components
• Webpack

Installation

npm install

Run Development environment

npm start

License

This project is licensed under the ISC License. For detailed terms, please refer to the license file included in this repository.

Attribution

This project makes use of the following dependencies and data sources, which are governed by separate licenses:

1. caniuse-lite

The project indirectly utilizes data from caniuse-lite as part of its build tooling. The data, sourced from caniuse.com, is made available under the Creative Commons Attribution 4.0 International (CC BY 4.0) license. For more information, visit the repository.

2. spdx-exceptions

This project indirectly references the spdx-exceptions package as part of its build tooling. Portions of the data used are derived from version 2.0 of the SPDX specification, licensed under the Creative Commons Attribution 3.0 Unported (CC-BY-3.0) license. For details, see the repository.