Skip to content

d2‐autogen‐forms

Jump to bottom
Chukwudumebi Onwuli edited this page Sep 8, 2023 · 4 revisions

d2-autogen-forms. Data Entry custom forms on steroids.

General information

d2-autogen-forms is a tool that generates custom forms for datasets. It is developed using d2-reports. The DHIS2 data entry app provides a default view for users to collect information for different datasets. However, users can add any custom form (in any valid HTML, CSS, and JS) and modify the default view. This allows users to tailor the data entry app to their specific needs.

How it works

Different functionalities can be added to each data element in the dataset by configuring certain settings that are saved in the dataStore. The configuration depends on the following elements, which need to be defined:

  • dataSets
  • dataElements
  • categoryCombo

An example:

{
  "categoryCombinations": {
    "CC_CODE1": {
      "viewType": "shortName"
    }
  },

  "dataElements": {
    "DE_CODE1": {
      "selection": {
        "isMultiple": true,
        "optionSet": {
          "code": "OPTION1_CODE"
        }
      }
    }
  },

  "dataSets": {
    "DS1_CODE": {
      "viewType": "table",
      "tabs": {
        "active": true,
        "order": 1.2
      }
    },
    "DS2_CODE": {
      "viewType": "grid",
      "sections": {
        "SECTION1_CODE": {
          "viewType": "table",
          "texts": {
            "header": "<h2>Section header from dataStore</h2>",
            "footer": "<h3>Section footer from dataStore</h3>"
          }
        }
      },
      "texts": {
        "footer": {
          "code": "MAL-ADP-CF-FTR"
        },
        "header": {
          "code": "MAL-ADP-CF-HDR"
        }
      }
    },
    "DS3_CODE": {
      "viewType": "grid",
      "sections": {
        "SECTION2_CODE": {
          "viewType": "grid-with-periods",
          "toggle": {
            "type": "dataElement",
            "code": "CODE_OF_DATA_ELEMENT"
          },
          "periods": {
            "type": "relative-interval",
            "endOffset": 0,
            "startOffset": -2
          }
        }
      }
    }
  }
}

Toggleable contents

Section contents can be optionally shown/hidden using a dataElement as toggle. In the section configuration:

{
  "toggle": {
    "type": "dataElement",
    "code": "DATA_ELEMENT_CODE"
  }
}

View mode: Table

Data elements will be shown in the first column and the value in the second.

An example, a section with data elements:

-   `ITNs - Policy`
-   `ITNs - Implemented`

This will create this table:

                   |                |
ITNs - Policy      |                |
ITNs - Implemented |                |

View mode: Grid

Data elements will by grouped by rows and columns using formName/name and " - " as a separator of subsection / data element.

An example, a section with data elements:

-   `ITNs - Basic - Written Policy`
-   `ITNs - Basic - Policy Implemented`
-   `ITNs - Extended - Written Policy`
-   `ITNs - Extended - Policy Implemented`

This will create this table:

                | Written Policy | Policy Implemented |
ITNs - Basic    |                |                    |
ITNs - Extended |                |                    |

NOTE: The section processor detects if all the data elements are indexed, and in that case a special. An example:

Data elements:

- `MAL - Compound name (1)`
- `MAL - Compound name (2)`
- `MAL - Compound symbol (1)`
- `MAL - Compound symbol (2)`

Output:

   #   | Compound name | Compound symbol
   1   |               |
   2   |               |

View mode: Grid with periods

Data elements will by grouped by rows and subrows using formName/name and " - " as a separator of subsections.

An example, a section with data elements:

-   `ITNs - Basic`
-   `ITNs - Extended - Written Policy`
-   `ITNs - Extended - Policy Implemented`
-   `ITNs - Extended - Policy Extra`

And having a configuration in the dataStore:

{
  "SECTION_CODE": {
    "viewType": "grid-with-periods",
    "periods": {
      "type": "relative-interval",
      "endOffset": 0,
      "startOffset": -2
    }
  }
}

And rendering a data entry for 2022, will create this table for interval [2022-2 .. 2022+0]:

                                       |  2020  |  2021  |  2022   |
--------------------------------------------------------------------
ITNs - Basic                           |        |        |         |
                 | Written Policy      |        |        |         |
ITNs - Extended  | Policy Implemented  |        |        |         |
                 | Policy Extra        |        |        |         |

View mode: Grid with totals

View mode: Grid with combos

View mode: Grid with subnational OUs

Installation

Install and build the app by running:

$ yarn install # first time only
$ yarn build

This will create a custom-data-form.html file in the dist folder at the root of the project. Subsequently, you can navigate to the dataset > design data entry form > paste the HTML content in the editor and then see your changes in the data entry.

On development, use:

$ HOST=<address> PORT=<port> REACT_APP_DHIS2_BASE_URL=<dhis2_instance_url> REACT_APP_DHIS2_AUTH=<user:passwd> yarn start

For example:

$ HOST=localhost PORT=8082 REACT_APP_DHIS2_BASE_URL=http://localhost:8080 REACT_APP_DHIS2_AUTH='admin:district' yarn start

To test on your local instance, the orgUnit, dataSet and period query parameters need to be set and the URL should be formatted as follows: http://localhost:8081?orgUnit=ID&dataSet=ID&period=PERIOD

Basic configuration of the metadata

Expected structure of the metadata:

  • Maintenance -> Data set -> Edit: Add all the data elements that need to be displayed.
  • Maintenance -> Data set -> Manage sections: Create a section for each table to display in the form.

Advanced customizations on datastore

It is possible to configure an optionSet for data elements so that a drop-down menu will be displayed instead of the classic input component in the autogenerated form. This is a useful option when a user has a TEXT data element but wishes to restrict the values that can be entered.

An illustration of this configured in the datastore would be:

{
  dataElements": {
    "DE_CODE1": {
      "selection": {
        "isMultiple": true,
        "optionSet": {
          "code": "OPTION_CODE1"
        }
      }
    },
  }
}

Here, we are configuring the autogenerated form to display a multiselect dropdown field to the user with the code "DE_CODE1". The values for the drop-down field will be the values in the optionSet with the code "OPTION_CODE1".

Clone this wiki locally