This document provides instructions for integrating PDA Linkage Form into your application. Before going further, refer to Integration PDA authentication and make sure followed the steps in Getting Started section

1 Getting Started

Getting Started

1. Install react and react-dom

PDA Linkage Form micro frontend is implemented in React so they should be installed.

npm install react@^18.3 react-dom@^18.3

Note: Starting with React 19, it will no longer produce UMD builds to reduce the complexity of its testing and release process. So make sure you don’t install version 19. Refer to UMD builds removed

2. update gulp_helper.js: /node_modules/core/gulp_helper.js

inject: (gulp, inject, stream, options) => {
    ...
    if (options['includeModeling']) {
      process.stdout.write('Core gulp helper injecting underscore/backbone for modeling\n');
      coreFiles = coreFiles.concat([
        "./node_modules/underscore/underscore.js",
        "./node_modules/backbone/backbone.js",
        "./node_modules/core/dist/js/cot_backbone.js"
      ]);
    }
    if (options['includePDA']) {
      process.stdout.write('Core gulp helper pdajs-sdk module, react and react-dom\n');
      coreFiles = coreFiles.concat([
        "./node_modules/react/umd/react.production.min.js",         // <--
        "./node_modules/react-dom/umd/react-dom.production.min.js", // <--
        "./node_modules/pdajs-sdk/dist/pdajs-sdk.css",
        "./node_modules/pdajs-sdk/dist/pdajs-sdk.umd.js"
      ]);
    }
    ...
  }

3. Install “Allow CORS: Access-Control-Allow-Origin plugin” for Chrome

If you cannot install Node.js 16.2 or higher (e.g., due to corejs restrictions or inability to use nvm), you can use the deployed versions of Linkage Form and Settings in the SIT environment. However, this approach may result in CORS (Cross-Origin Resource Sharing) errors when accessing the micro-frontends from your local development environment.

To resolve CORS errors, install the Allow CORS: Access-Control-Allow-Origin Chrome plugin:

Installing the Allow CORS Plugin

Open the Chrome browser.
Navigate to the Chrome Web Store.
Search for “Allow CORS: Access-Control-Allow-Origin”.
Click Add to Chrome and confirm the installation.

Note: Make sure the plugin turned on if you test locally.

4. Linkage Form MFE

Create a linkage route and view. In order to load the Linkage Form MFE into the view, you can switch the route to linkage, like http://localhost:9001/#linkage. The route name can be different if necessary. In the linkage view, put these codes

  ...
  handleCancel() {
    window.location.hash = "#accountDetails";
  }

  loadLinkageForm() {
    const removeLinkageForm = pdajsSDK.ui.renderLinkageForm({
      initValues: {
        clientNum: routerModel.get("client_number"),
      },
      accessToken: pdajsSDK.store.get("tokens").accessToken,
      idToken: pdajsSDK.store.get("tokens").idToken,
      grecaptcha,
      recaptchaSiteKey: "/*@echo RECAPTCHA_SITEKEY*/",      
      container: $("#fepe_buslicportal_container")[0],
      onCancel: this.handleCancel,
      onError: this.handleError,
      onPrevious: this.handlePrevious,
      onSuccess: this.handleSuccess,
      runTimeEnv: "/*@echo RUN_TIME_ENV*/",
    });

    pdajsSDK.store.set("removeLinkageForm", removeLinkageForm);
  }
  
  render() {
    // if necessary, you can set page header
    
    this.loadLinkageForm();
  }
  ...

Note: Make sure RECAPTCHA_SITEKEY is defined in the gulpfile.js

loadLinkageForm: It should be called from render function and will load LinkageForm MFE

initValues: If there are pre-populated values for linkage form, those can be passed via initValues property

container: It is HTML element to render the form

grecaptcha: Google reCaptcha instance, which is a global object in the application. Refer to Captcha - Frontend and Server Side - Setup Example

callback handlers

onCancel: If a user clicks a Cancel button. If it is not passed, the Cancel button is not rendered

onPrevious: If a user clicks a Previous button. If it is not passed, the Previous button is not rendered

onError: If there is an error while loading metadata or submitting data, it will be triggered along with an error message. If it is not passed, the message will be rendered at the top of the form in a banner

onSuccess: If submitting is done without any errors. If it is not passed the message will be shown in a modal dialog and redirect back to root route when a user click ok button in the dialog

Note: If you don’t have node >= 18 installed, set runTimeEnv to “dev” for local context in gulpfile.js. If runTimeEnv is set to “local” for local context, the pdajs-sdk will try to load the linkage form from your localhost so if you are not able to run the linkage form locally, it should be set to “dev”.

  preprocessorContext: {
    local: {
      ...
      PDA_CLIENT_ID: "MLS-Portal2",
      PDA_REDIRECT: "http://localhost:9001",
      PDA_HEADER: true,
      RUN_TIME_ENV: "dev",  /////////////////////////////////////// <--
      RECAPTCHA_SITEKEY: "6Ld5K6caAAAAAImIdYd3xaJDBpoYBR3RL9mE1LFz",
    },
    dev: {
      ...
    },

Integration Linkage Form into Cot applications

Getting Started

1. Install react and react-dom

2. update gulp_helper.js: /node_modules/core/gulp_helper.js

3. Install “Allow CORS: Access-Control-Allow-Origin plugin” for Chrome

4. Linkage Form MFE