DIGIT-Works/useCustomAPIHook.js at develop · egovernments/DIGIT-WorksGitHubSteps to add new screens in DIGIT-ui
This document provides the steps for creating new screens in the DIGIT-UI.
Creating a screen in DIGIT UI involve simple steps and is classified into 4 different screen -
To create any new screen of the Create type, use the FormcomposerV2 and transmit the configuration as specified in the sample.js file.
To check the different types of configurations, refer to the fieldSelector function.
To use any view screen, create the hook for initiating API calls and structure the configurations for the View section.
Refer to the integrated screen with ApplicationDetailsTemplate - ViewProperty.js.
The hook details for the same is mentioned in useGenericViewProperty.js
The service configuration details are available in Search.js
To create any inbox screen, use the InboxComposer and add the following configurations:
Main file: EdcrInbox
Check the folder which contains other configs like filter, table, search, and mobile responsiveness.
The hook for the same is defined in useEDCRInbox.js
Use the latest InboxSearchComposer (InboxV2)
Both Inbox and Search screens can be shown based on the input configurations passed to that component - BillInbox.js
Configuration are mentioned in InboxConfig for local reference and it is fetched from the MDMS BillInboxConfig.
An example of a Search screen is available in SearchConfig.
This page provides the steps to configure the FormComposer.
For complex configuration or screen details refer to documentation on Utility - preprocess
There are 3 new use cases added to the FormComposer in addition to the default one where the whole form was rendered in a single card. Those 2 are the following:
Multiple cards
Cards with navigation menu
Multiple cards with navigation menu on a single card
The following use cases are covered in the DIGIT-WORKS repo.
URL to access:/works-ui/employee/works/sampleForm
This can be done by setting the showMultipleCards prop to the FormComposer as true. In this case, every object in the formConfig will be treated as a separate Card and will be rendered accordingly.
Access Config Link.
FormComposer provides the option to activate a navigation menu that appears on top of the card. Each link in the menu corresponds to a specific card. To enable this feature, provide an array configuration for the navigation menu as a prop to the FormComposer component. Then, map each card with a link from the navigation menu configuration array using a designated key named "navLink", associating it with a value in the Navigation Menu Config.
Access Configuration link.
This use case is the same as above. The only difference is the navLink property in the config. If this property is present and valid for a card config, the corresponding card will be mapped to a navigation menu link. On the other hand, if navLink is not present or invalid, the corresponding card will be rendered as a separate Card.
Multiple options can be selected.
There are two common components for workflow related actions and timeline management.
WorkflowActions - WorkflowActions
WorkflowTimeline - WorkflowTimeline
Both of these components are available on each View Screen. The WorkflowTimeline component is responsible for presenting the workflow history at the bottom of the View Screen. Similarly, the WorkflowActions component renders an action bar at the bottom of the view screens, showcasing pertinent actions based on the logged-in user's role and workflow configuration.
This component is directly integrated with the ApplicationDetailsContent component that renders all the relevant data in view screens. WorkflowTimeline component is called in this component like this:
It expects a few props:
BusinessService -> Name of the businessService from workflow configuration
applicationNo -> Idgen generated application number
tenantId
timelineStatusPrefix -> prefix used in localisation of every checkpoint in timeline
statusAttribute -> here we can pass the attribute(either status/state) that is the key in the workflow process instance response, whichever we want to show in the checkpoint.
This component internally calls the workflow APIs to fetch the process instance of the application and renders the history accordingly. It also makes a check for the current state of the application. If the current state is not terminated state then it will show an extra checkpoint at the top with statusAttribute as status to show pending states checkpoint. If the current state is terminated state then it will not show pending states.
Refer to the below snapshots, notice they both have 4 checkpoints. Approved refers to terminate state.
This component is rendered on every View component separately to render the action bar with relevant actions.
Sample code Snapshot:
It expects a few props:
BusinessService -> Name of the businessService from workflow configuration
forcedActionPrefix -> for localization
applicationNo -> Idgen generated application number
tenantId
applicationDetails -> same data returned from hook used on view screen
Url -> update API url to hit
setStateChanged -> when update is successful this is called. Hence search apis will be called again and workflow history and workflow actions will be updated without screen refresh
moduleCode
editApplicationNumber -> Used in case of edit/modify action
This component internally calls the update apis and shows a relevant toast on success/failure or a response screen in case of edit action.
A significant part of this component is another component called the WorkflowPopup. This is the popup that renders whenever the user clicks on a specific action. This popup is fully configurable through this configuration file Popup Config. Popup configs are defined in this configuration file which are organised as per the businessService of the workflow configuration. Refer to the configMap object in this file for more details.
Approach to render Inbox and Search screen content based on config passed via MDMS data.
The Inbox Service is an event-based service designed to:
Fetch pre-aggregated data of municipal services and workflows.
Perform complex search operations.
Return applications and workflow data in a paginated manner.
Provide the total count of entries matching the search criteria.
This page outlines the following:
Rendering the Inbox or Search screen based on configurations.
Dynamically calling APIs using details provided in configurations.
InboxSearchComposer is a container component for the inbox and search screens. It consists of four child components, which can be rendered conditionally.
| Prop Name | Description |
|---|---|
The InboxSearchLinks component is used to render titles and links in the inbox.
The SearchComponent is used to render search or filter forms. It includes 'clear' and 'search' buttons for user interaction.
The Results table component is used to render a table with searched results.
The RenderFormFields component is used to render form fields specified in the 'fields' parameter of the configuration.
To fetch inbox details, the useCustomAPIHook is utilized. This hook takes all necessary API details such as URL, query parameters, body, and config from the configuration (defined in MDMS).
Create config based on the sections to be displayed on the screen. The basic structure for the Inbox and Search screens is given below.
Based on the flag given for each section its visibility is controlled. If the ‘show’ flag is true, then the section is visible, else it is hidden.
Add API details in the top section, this API will be called via useCustomAPIHook and return the data. This consists of the below details.
Add search form config which can be used in both inbox/search screen. It consists of UIconfig containing label info, styling info, default form values, and fields which need to be rendered in the form. Refer below
Add Links config consists of link info, logo to be shown and title. Refer below
Add Filter form config which is similar to the search form. Refer below
Add Table (Search result) config consists of labels, column data and related jsonpaths to access the data passed. Refer below
To add any customisations on query params, request body, table columns or to add any custom validations in forms, related code can be added in the UICustomisations file as below
Once the above config is defined, created an index file/ Component in the pages folder. Fetch the config from MDMS and pass it to the inboxSearchComposer component as below
This approach is followed only in Inbox and Search screens currently.
Only one API can be called dynamically based on given configurations.
To use the latest Inbox search composer it has to be imported from the React components or Utilities
React components
package
Utilities:
package
| Prop Name | Description |
|---|---|
| Prop Name | Description |
|---|---|
| Prop Name | Description |
|---|---|
| Prop Name | Description |
|---|---|
configs
Config fetched from MDMS data
headerText
Config fetched from MDMS data
links
Links to navigate to other screens
customClass
Class to update styling
logoIcon
Icon name and class to render in component
uiConfig
Config to render search/filter form
header
Title of form
screenType
Type of parent screen, can be either ‘inbox’ or ‘search’
fullConfig
Entire config of screen which also includes API details
config
Config to render table
data
Search results need to be populated in table
isLoading
Flag to pass to handle loading state
isFetching
Flag to pass to handle loading state
fullConfig
Entire config of screen which also includes API details
fields
Config to render all form fields
control, formData, errors, register, setValue, getValues, setError, clearErrors
Props to handle all form actions like collectibe data, setting errors, clearing errors etc.
apiDetails
Includes all API details required to fetch data
