CM&F Group Forms Library

This is a frontend component library used to integrate CM&F Group's forms into your website. This library currently supports React. If you need Angular or Vue support, please contact CM&F Group for information.

Solution Overview

Proxy

You will create a proxy service on your web backend to handle API requests from the CmfForm component. The requests will go from your website to your backend, and then from your backend to CM&F Group's API. This design permits your backend to hanlde user authentication and API authentication without exposing sensitive information to the client. You can find some sample code for how to implement this in the Proxy appendix below.

User Authentication

You will need to handle user sign-up and sign-in on your website. On your backend proxy, you will attach a header indicating the unique ID of the user who is logged into your site and using the form. Ensure that this value is retrieved from a trusted source and is not susceptible to tampering by the user.

Example:

customer-id: <your-user-id>

API Authentication

You will be provided with an API key for the CM&F Group API. Your proxy will affix this key in a header to all requests to the CM&F Group API.

Example:

x-api-key: <your-api-key>

Setup

Basic Configuration

1. Installation

npm install @cmfgroup/forms

2. Add the form to one of your webpages

import React from 'react';
import { CmfForm } from '@cmfgroup/forms/react';

export const MyPageComponent = (apiUrl: string) => {
  return (
    <CmfForm apiUrl={apiUrl} headersToAppend={{ 'Authorization': /*your token*/ }} />
  );
};

3. Provide the API URL for your backend proxy as a parameter to the CmfForm component.

4. Using the headersToAppend parameter, provide any additional headers that you need to attach to the requests to the apiUrl (proxy). This could include an authorization token or any other headers that need to be present on each request.

Themed Configuration

There is an optional parameter to the CmfForm component called theme. This parameter allows you to customize the appearance of the form to match your website's theme. The theme parameter should be an instance of Theme as provided by the Material-UI library. You can create a Theme by using the Material-UI Theme Generator.

import React from 'react';
import { CmfForm } from '@cmfgroup/forms/react';
import { createTheme } from '@mui/material';

// This object is generated by the Matierial-UI Theme Creator tool at
// https://zenoo.github.io/mui-theme-creator/
const themeOptions = {
  palette: {
    primary: {
      main: '#cac81c',
      light: '#1fb618',
      dark: '#4e536c',
      contrastText: '#cd3636',
    },
    secondary: {
      main: '#f50057',
    },
  },
};

// Make a theme with the options
const customTheme = createTheme(themeOptions);

export const MyPageComponent = (apiUrl: string) => {
  return (
    <CmfForm apiUrl={apiUrl} headersToAppend={{ 'Authorization': /*your token*/ }} theme={customTheme} />
  );
};

Appendix A: Proxy

Here is an example of how you might implement a proxy in Node.js using Express.

The piece that is omitted here is the getCurrentUserId function. This function should retrieve the user's ID from your authentication service. This could be a cookie, a session, or a token. The important thing is that the user's ID is retrieved from a trusted source and is not susceptible to tampering by the user.

If you provided additional headers to the <CmfForm /> component, you will be able to access the headers in your proxy service. You can use these headers to complete user authentication and lookup the correct user ID to provide in the customer-id header to the CM&F Group API.

import express from 'express';
import cors from 'cors';
import dotenv from 'dotenv';
dotenv.config();

const expressHttpProxy = require('express-http-proxy');
const port = process.env.PORT || 3000;
const app = express();

// This represents a function that retrieves the user's ID from your authentication service.
import { getCurrentUserId } from './UserManager';

// Middleware function to add the headers
const addHeaders = (req: express.Request, res: express.Response, next: express.NextFunction) => {
  req.headers = {
    ...req.headers,
    accept: 'application/schema+json',
    'x-api-key': process.env.AUTH_TOKEN,
    'customer-id': getCurrentUserId(req),
  };
  next();
};

app
  .use(addHeaders)
  .use(cors({ origin: process.env.ALLOWED_ORIGIN }))
  .use('/', expressHttpProxy(process.env.API_URL))
  .listen(port);