1 of 6

Create a New UI Module/Package

Project Structure

Front-end module project structure

Overview

Before starting with the Module code, ensure your local development environment is set up. You can refer to the local development setup guide link given below for detailed instructions.

Local-Development-Setup

Steps

Download the UI code from the link here Digit-Frontend. if not done earlier

Follow the steps given below to create the project structure.

Once you have cloned the repository from Digit-Frontend, do the following.
Go to micro-ui-internals → packages → modules.
Create a new folder with module's name , For example (Sample).
Create a folder called src and add the components , configs, hooks and pages inside that.
The project structure should be as in the image below:

After creating the new Sample module, we need to create a package.json file for the module, specifying the module name, version, scripts, and required dependencies.

{
  "name": "@egovernments/digit-ui-module-sample",
  "version": "0.0.1",
  "description": "Sample Module UI",
  "main": "dist/index.js",
  "module": "dist/index.modern.js",
  "source": "src/Module.js",
  "files": [
    "dist"
  ],
  "scripts": {
    "start": "microbundle-crl watch --no-compress --format modern,cjs",
    "build": "microbundle-crl --compress --no-sourcemap --format cjs",
    "prepublish": "yarn build"
  },
  "peerDependencies": {
    "react": "17.0.2",
    "react-router-dom": "5.3.0"
  },
  "dependencies": {
    "@egovernments/digit-ui-react-components": "1.8.2-beta.5",
    "@egovernments/digit-ui-components": "0.0.2-beta.1",
    "react": "17.0.2",
    "react-date-range": "^1.4.0",
    "react-dom": "17.0.2",
    "react-hook-form": "6.15.8",
    "react-i18next": "11.16.2",
    "react-query": "3.6.1",
    "react-router-dom": "5.3.0"
  },
  "author": "Jagankumar <jagan.kumar@egov.org.in>",
  "license": "MIT"
}

Refer to the file here - Package.json

The next step is to initialise the Dependency, refer here to learn more about the setup

Install Dependency

Overview

Once the project structure is ready, it is time to install and configure the module dependencies in the Master Data Management Service (MDMS). Follow the steps below to finalise these.

Steps

After creating the Sample module and its package.json file, you need to ensure that this module is enabled in the citymodule.json file in the MDMS (Master Data Management Service) configuration. If it is not enabled, you need to update the MDMS configuration accordingly. You need to add this module to the root tenant in your environment from your branch.

modulename : tenant
mastername : citymodule

file location

https://github.com/<<YOUR ORG NAME>>/egov-mdms-data/blob/<<BRANCH WHERE THE ENVIRONMENTS IS POINTED TO>>/data/<<ROOT TENANT OF YOUR ENVIRONMENT>>/tenant/citymodule.json

for reference: citymodule.json.

For illustration here, add the following module (sample) as given below:

  "citymodule": [{
      "module": "SAMPLE",
      "code": "<<REPLACE WITH YOUR MODULECODE>>",
      "active": true,
      "order": 1,
      "tenants": [
        {
          "code": "<<REPLACE WITH YOUR TENANTS>>"
        }
      ]
    }],

Register the Sample UI module in three places so that it will be available to the developer at runtime as well as at the time of deployment. Below are the three places where the module needs to be registered:

micro-ui/web/micro-ui-internals/package.json micro-ui/web/micro-ui-internals/example/package.json

Micro-ui-internals:- Open the micro-ui-internals package.json file and add the following inside the scripts:

"scripts": { 
    "dev:sample": "cd packages/modules/sample && yarn start",
    "build:sample": "cd packages/modules/sample && yarn build",
  },

In the example/package.json, add the following line:

"@egovernments/digit-ui-module-Sample":"0.0.1",

In the web/package.json, add the following line:

"@egovernments/digit-ui-module-Sample":"0.0.1",

The next step is to initailise the module.js, refer here to know more about the setup

Module.js

Overview

The next step is to register SampleModule in module.js, the module's entry file. To demonstrate rendering, display "Sample Module" using a simple <div> element within the SampleModule component. This creates a basic screen setup for the module, which can be customized or expanded as needed.

Steps

Add the below code in the Module.js file which is already created.

import { Loader} from "@egovernments/digit-ui-react-components";
import React from "react";

export const SampleModule = ({ stateCode, userType, tenants }) => {
  const tenantId = Digit.ULBService.getCurrentTenantId();
  const moduleCode = ["sample", "common","workflow"];
  const language = Digit.StoreData.getCurrentLanguage();
  const { isLoading, data: store } = Digit.Services.useStore({
    stateCode,
    moduleCode,
    language,
  });

if (isLoading) {
    return <Loader />;
  }
  return ( <Switch>
  <AppContainer className="ground-container">
           <div>Sample Module </div> 

  </AppContainer>
  </Switch>)
  
const componentsToRegister = {
  SampleModule,
};
export const initSampleComponents = () => {
  overrideHooks();
  updateCustomConfigs();
  Object.entries(componentsToRegister).forEach(([key, value]) => {
    Digit.ComponentRegistryService.setComponent(key, value);
  });
};

Initialize the module's custom hooks, configurations, and register components using initSampleComponents() here.

Refer to the file here: Module.js

Linking the newly created module in Main App

After creating the module code we need to enable it in two places:

For Deployment In app.js we import the SampleModule, initSampleComponents, and enable the Sample module. Add the App.js file in the following path:micro-ui/web/src/App.js

const enabledModules = [
  "sample"
];

const moduleReducers = (initData) => ({
  initData,
});

const initDigitUI = () => {
  window.Digit.ComponentRegistryService.setupRegistry({});
  window.Digit.Customizations = {
    PGR: {},
    commonUiConfig: UICustomizations,
  };
  initSampleComponents();
};

initLibraries().then(() => {
  initDigitUI();
});

Reference for the App.js file: App.js

For Local development In index.js, import the SampleModule, initSampleComponents, and enable the Sample module. Create the index.js file under the following path: micro-ui-internals/example/src/index.js

 const enabledModules = [
  "Sample"
];

const initDigitUI = () => {
  window.contextPath = window?.globalConfigs?.getConfig("CONTEXT_PATH") || "digit-ui";
  window.Digit.Customizations = {
    commonUiConfig: UICustomizations
  };
  initSampleComponents();

Reference for the Index.js file: Index.js

If there is a local server running, make sure to stop it. Restart by running yarn install followed by yarn start at the micro-ui-internals level.

Hurray! Now, the screen is displayed below on visiting the given URL:

http://localhost:3000/digit-ui/employee/sample

Refer to the below sections for a deeper understanding

Import Required Components

Overview

DIGIT comes with common re-usable libraries that can be imported for use in a new module. Follow the steps below to import the required components.

Steps

We are reusing certain React components from our libraries, such as InboxSearchComposer, FormComposerV2, SubmitCard, CardText, and others. Refer to the link below to learn more about these components.

Learn more about our React components

All components are available in the link below. Digit-UI-Components

Common Hooks

Overview

We can develop custom React hooks like useCustomAPIMutationHook to fine-tune the application API interactions. The custom hooks allow us to control how data is fetched and managed, aligning it perfectly with our requirements.

Configuration

This custom hook, useCustomAPIMutationHook, simplifies API calls for mutation operations in React applications using react-query. It allows parameter and body customization for requests to a specified URL, seamlessly managing loading indicators and states. This hook streamlines API interaction and state management within components.

Create useCustomAPIMutationHook under the following path:

micro-ui-internals/packages/libraries/src/hooks/useCustomAPIMutationHook.js

import { useQueryClient, useMutation } from "react-query";
import { CustomService } from "../services/elements/CustomService";

 const requestCriteria = [
      "/user/_search",             // API details
    {},                            //requestParam
    {data : {uuid:[Useruuid]}},    // requestBody
    {} ,                           // privacy value 
    {                              // other configs
      enabled: privacyState,
      cacheTime: 100,
      select: (data) => {
                                    // format data
        return  _.get(data, loadData?.jsonPath, value);
      },
    },
  ];
  const mutation = Digit.Hooks.useCustomAPIMutationHook(...requestCriteria);


while mutating use the following format 

mutation.mutate({
          params: {},
          body: { "payload": {
                   // custom data
                } 
          }},
          {
            onError : ()=> { // custom logic},
            onSuccess : ()=> { // custom logic}
          }
        );


const useCustomAPIMutationHook = ({ url, params, body, config = {}, plainAccessRequest, changeQueryName = "Random" }) => {
  const client = useQueryClient();

  const { isLoading, data, isFetching, ...rest } = useMutation(
    (data) => CustomService.getResponse({ url, params: { ...params, ...data?.params }, body: { ...body, ...data?.body }, plainAccessRequest }),
    {
      cacheTime: 0,
      ...config,
    }
  );
  return {
    ...rest,
    isLoading,
    isFetching,
    data,
    revalidate: () => {
      data && client.invalidateQueries({ queryKey: [url].filter((e) => e) });
    },
  };
};

export default useCustomAPIMutationHook;

Override Hook

To override the useCustomAPIMutationHook, create a new custom hook with the desired enhancements. When considering overriding useCustomAPIMutationHook, identify specific modifications required, such as adding additional parameters or altering data processing logic. Create a new custom hook, preserving the original functionality while incorporating these modifications to suit specific application needs.

We need to replace the usage of the original hook throughout the codebase with the new custom hook. This ensures that wherever the original hook is used, the modified functionality of the custom hook is applied instead.

There is a hook called useCustomMDMSV2, which is used to get data from a Multi-Domain Master Service (MDMS) API. This hook makes it easier to request data, handle load, and prepare the received data for React applications.

useCustomMDMSV2

Create the hook under the following path:

micro-ui-internals/packages/modules/Sample/src/hooks/useCustomMDMSV2.js

export const useCustomMDMSV2 = ({ tenantId, schemaCode, select, changeQueryName = "Random",filters={},config={} }) => {
  
  const requestCriteria = {
    url: "/mdms-v2/v2/_search",
    body: {
      tenantId,
      MdmsCriteria: {
        // tenantId, //changing here to send user's tenantId always whether stateId or city
        tenantId: Digit.ULBService.getCurrentTenantId(),
        filters: filters,
        schemaCode: schemaCode,
        isActive: true,
        limit: 100
      },
    },
    config: {
      select: select
        ? select
        : (response) => {
            //mdms will be an array of master data
            const { mdms } = response;
            //first filter with isActive
            //then make a data array with actual data
            //refer the "code" key in data(for now) and set options array , also set i18nKey in each object to show in UI
            const options = mdms?.map((row) => {
              return {
                i18nKey: Digit.Utils.locale.getTransformedLocale(`${row?.schemaCode}_${row?.data?.code}`),
                ...row.data,
              };
            });
            return options;
          },
          ...config
    },
    changeQueryName,
  };
  const { isLoading, data } = Digit.Hooks.useCustomAPIHook(requestCriteria);
  return { isLoading, data };
};

Creating New Hook

We can also create custom hooks like useIndividualView to simplify tasks like fetching data for specific screens.

Create the hook useIndividualView under the following path:

micro-ui-internals/packages/modules/sample/src/hooks/useIndividualView.js

import { useQuery } from "react-query";
import { sampleService } from "./services/sampleService";
import { searchTestResultData } from "./services/searchTestResultData";

export const useIndividualView = ({t,individualId,tenantId,config={} }) =>{
  //console.log(props);
  console.log(individualId,'test');
  return useQuery(["Individual Details"], () => searchTestResultData({ t, individualId, tenantId }), config);
};

This searchTestResultData function is used within the useIndividualView hook to fetch data related to a specific individual. It utilizes an asynchronous operation to send a request to a server endpoint, retrieves the response, and then processes the data to extract relevant details. The extracted details are then returned, providing the necessary information for rendering the individual's view within the application. Create the Function searchTestResultData under the following path:

micro-ui-internals/packages/modules/sample/src/hooks/services/searchTestResultData.js

export const searchTestResultData = async ({ t, individualId, tenantId }) => {
  
  const response = await Digit.CustomService.getResponse({
    url: "/individual/v1/_search",
   
    params: {
      tenantId: "pg.citya",
      offset: 0,
      limit: 10,
      
    },
    body: {
        Individual: {
          "tenantId": "pg.citya",
          "individualId": individualId,
        },
      },
   
  });
  console.log("response", response);

 
  return {
    details: [
      {
         sections: [
           {
            type: "DATA",
             values: [
              {
                key: "Applicant name",
                value: response?.Individual?.[0]?.name?.givenName || "NA",
              },
              {
                key: "Applicant Id",
                value: response?.Individual?.[0]?.identifiers?.[0].individualId || "NA",
              },
               {
                 key : "Adress",
                value : response?.Individual?.[0]
             }
            ],
          }
         ],
       },
     ],
   };
        }

Reference of using this hook on a view screen: ViewIndividual.js

Registering the Hooks

To register hooks in your application, they should be exported from an index.js file like this. Ensure that each custom hook is correctly exported within this file for seamless integration and usage across your application. Create anindex.js file under the following path:

micro-ui-internals/packages/modules/sample/src/hooks/index.js

const sample = {
  useIndividualView
};

const Hooks = {
  sample,
};

Refer to the file here: index.js

Common Hooks

Overview

Configuration

Create useCustomAPIMutationHook under the following path:

micro-ui-internals/packages/libraries/src/hooks/useCustomAPIMutationHook.js

import { useQueryClient, useMutation } from "react-query";
import { CustomService } from "../services/elements/CustomService";

 const requestCriteria = [
      "/user/_search",             // API details
    {},                            //requestParam
    {data : {uuid:[Useruuid]}},    // requestBody
    {} ,                           // privacy value 
    {                              // other configs
      enabled: privacyState,
      cacheTime: 100,
      select: (data) => {
                                    // format data
        return  _.get(data, loadData?.jsonPath, value);
      },
    },
  ];
  const mutation = Digit.Hooks.useCustomAPIMutationHook(...requestCriteria);


while mutating use the following format 

mutation.mutate({
          params: {},
          body: { "payload": {
                   // custom data
                } 
          }},
          {
            onError : ()=> { // custom logic},
            onSuccess : ()=> { // custom logic}
          }
        );


const useCustomAPIMutationHook = ({ url, params, body, config = {}, plainAccessRequest, changeQueryName = "Random" }) => {
  const client = useQueryClient();

  const { isLoading, data, isFetching, ...rest } = useMutation(
    (data) => CustomService.getResponse({ url, params: { ...params, ...data?.params }, body: { ...body, ...data?.body }, plainAccessRequest }),
    {
      cacheTime: 0,
      ...config,
    }
  );
  return {
    ...rest,
    isLoading,
    isFetching,
    data,
    revalidate: () => {
      data && client.invalidateQueries({ queryKey: [url].filter((e) => e) });
    },
  };
};

export default useCustomAPIMutationHook;

Override Hook

useCustomMDMSV2

Create the hook under the following path:

micro-ui-internals/packages/modules/Sample/src/hooks/useCustomMDMSV2.js

export const useCustomMDMSV2 = ({ tenantId, schemaCode, select, changeQueryName = "Random",filters={},config={} }) => {
  
  const requestCriteria = {
    url: "/mdms-v2/v2/_search",
    body: {
      tenantId,
      MdmsCriteria: {
        // tenantId, //changing here to send user's tenantId always whether stateId or city
        tenantId: Digit.ULBService.getCurrentTenantId(),
        filters: filters,
        schemaCode: schemaCode,
        isActive: true,
        limit: 100
      },
    },
    config: {
      select: select
        ? select
        : (response) => {
            //mdms will be an array of master data
            const { mdms } = response;
            //first filter with isActive
            //then make a data array with actual data
            //refer the "code" key in data(for now) and set options array , also set i18nKey in each object to show in UI
            const options = mdms?.map((row) => {
              return {
                i18nKey: Digit.Utils.locale.getTransformedLocale(`${row?.schemaCode}_${row?.data?.code}`),
                ...row.data,
              };
            });
            return options;
          },
          ...config
    },
    changeQueryName,
  };
  const { isLoading, data } = Digit.Hooks.useCustomAPIHook(requestCriteria);
  return { isLoading, data };
};

Creating New Hook

We can also create custom hooks like useIndividualView to simplify tasks like fetching data for specific screens.

Create the hook useIndividualView under the following path:

micro-ui-internals/packages/modules/sample/src/hooks/useIndividualView.js

import { useQuery } from "react-query";
import { sampleService } from "./services/sampleService";
import { searchTestResultData } from "./services/searchTestResultData";

export const useIndividualView = ({t,individualId,tenantId,config={} }) =>{
  //console.log(props);
  console.log(individualId,'test');
  return useQuery(["Individual Details"], () => searchTestResultData({ t, individualId, tenantId }), config);
};

micro-ui-internals/packages/modules/sample/src/hooks/services/searchTestResultData.js

export const searchTestResultData = async ({ t, individualId, tenantId }) => {
  
  const response = await Digit.CustomService.getResponse({
    url: "/individual/v1/_search",
   
    params: {
      tenantId: "pg.citya",
      offset: 0,
      limit: 10,
      
    },
    body: {
        Individual: {
          "tenantId": "pg.citya",
          "individualId": individualId,
        },
      },
   
  });
  console.log("response", response);

 
  return {
    details: [
      {
         sections: [
           {
            type: "DATA",
             values: [
              {
                key: "Applicant name",
                value: response?.Individual?.[0]?.name?.givenName || "NA",
              },
              {
                key: "Applicant Id",
                value: response?.Individual?.[0]?.identifiers?.[0].individualId || "NA",
              },
               {
                 key : "Adress",
                value : response?.Individual?.[0]
             }
            ],
          }
         ],
       },
     ],
   };
        }

Reference of using this hook on a view screen: ViewIndividual.js

Registering the Hooks

micro-ui-internals/packages/modules/sample/src/hooks/index.js

const sample = {
  useIndividualView
};

const Hooks = {
  sample,
};

Refer to the file here: index.js

Module.js

Overview

Steps

Add the below code in the Module.js file which is already created.

import { Loader} from "@egovernments/digit-ui-react-components";
import React from "react";

export const SampleModule = ({ stateCode, userType, tenants }) => {
  const tenantId = Digit.ULBService.getCurrentTenantId();
  const moduleCode = ["sample", "common","workflow"];
  const language = Digit.StoreData.getCurrentLanguage();
  const { isLoading, data: store } = Digit.Services.useStore({
    stateCode,
    moduleCode,
    language,
  });

if (isLoading) {
    return <Loader />;
  }
  return ( <Switch>
  <AppContainer className="ground-container">
           <div>Sample Module </div> 

  </AppContainer>
  </Switch>)
  
const componentsToRegister = {
  SampleModule,
};
export const initSampleComponents = () => {
  overrideHooks();
  updateCustomConfigs();
  Object.entries(componentsToRegister).forEach(([key, value]) => {
    Digit.ComponentRegistryService.setComponent(key, value);
  });
};

Initialize the module's custom hooks, configurations, and register components using initSampleComponents() here.

Refer to the file here: Module.js

Linking the newly created module in Main App

After creating the module code we need to enable it in two places:

For Deployment In app.js we import the SampleModule, initSampleComponents, and enable the Sample module. Add the App.js file in the following path:micro-ui/web/src/App.js

const enabledModules = [
  "sample"
];

const moduleReducers = (initData) => ({
  initData,
});

const initDigitUI = () => {
  window.Digit.ComponentRegistryService.setupRegistry({});
  window.Digit.Customizations = {
    PGR: {},
    commonUiConfig: UICustomizations,
  };
  initSampleComponents();
};

initLibraries().then(() => {
  initDigitUI();
});

Reference for the App.js file: App.js

For Local development In index.js, import the SampleModule, initSampleComponents, and enable the Sample module. Create the index.js file under the following path: micro-ui-internals/example/src/index.js

 const enabledModules = [
  "Sample"
];

const initDigitUI = () => {
  window.contextPath = window?.globalConfigs?.getConfig("CONTEXT_PATH") || "digit-ui";
  window.Digit.Customizations = {
    commonUiConfig: UICustomizations
  };
  initSampleComponents();

Reference for the Index.js file: Index.js

If there is a local server running, make sure to stop it. Restart by running yarn install followed by yarn start at the micro-ui-internals level.

Hurray! Now, the screen is displayed below on visiting the given URL:

http://localhost:3000/digit-ui/employee/sample

Refer to the below sections for a deeper understanding