Skip to content

Commit

Permalink
feat: Alterations and improvements to the implementation guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@edvinstava
edvinstava committed Jun 1, 2024
1 parent 444a3fd commit 16b7e13
Show file tree
Hide file tree
Showing 3 changed files with 58 additions and 131 deletions.
Binary file added docs/resources/images/DataStoreManagement_plugin_folder.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/resources/images/DatastoreManagement_Custom_Folder.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
189 changes: 58 additions & 131 deletions docs/using-capture-growth-charts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,163 +9,61 @@ Plugins allows developers to extend the functionality on DHIS2. These plugins en

## Prerequisites { #prerequisites }
- DHIS2 version 2.38 or later
- Capture app version v100.53.0 or later (Can be updated in the **App Management** app).
- [Capture](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-240/tracking-individual-level-data/capture.html) app version v100.53.0 or later (Can be updated in the **App Management** app).
- Access to the Maintenance app.
- Access to the Datastore Management app.
- Access to the App Management app.
- [Tracker Plugin Configurator](https://apps.dhis2.org/app/85d156b7-6e3f-43f0-be57-395449393f7d) application (Can be installed in the **App Management** app).

## Implementation { #implementation }
### Datastore Management app
The plugin is implemented using the Datastore Management app.

#### capture namespace
- Create a new namespace `capture` with key `useNewDashboard`.
- Add the following code to the namespace. Make sure to change `programId` to the id of the program you want to use the plugin for.
```json
{
"<programId>": true
}
```

- Create a new key `enrollmentOverviewLayout` in the `capture` namespace.
- Add the following code to the key. This will be the new layout for the Capture app. Again, change the `programId` Make sure to change the contents of `leftColumn` and `rightColumn` to fit your needs.
```json
{
"<programId>": {
"leftColumn": [
{
"name": "QuickActions",
"type": "component"
},
{
"name": "StagesAndEvents",
"type": "component"
}
],
"rightColumn": [
{
"name": "TrackedEntityRelationship",
"type": "component"
},
{
"name": "ErrorWidget",
"type": "component"
},
{
"name": "WarningWidget",
"type": "component"
},
{
"name": "FeedbackWidget",
"type": "component"
},
{
"name": "IndicatorWidget",
"type": "component"
},
{
"name": "Notes",
"type": "component"
},
{
"name": "ProfileWidget",
"settings": {
"readOnlyMode": true
},
"type": "component"
},
{
"name": "EnrollmentWidget",
"settings": {
"readOnlyMode": false
},
"type": "component"
}
],
"title": "Growth Monitoring"
}
}
```

# Growth chart plugin upload
## Clone the repository
Clone the repository to your local machine by running the following command in your terminal:
```bash
git clone https://github.com/dev-otta/dhis2-who-growth-chart.git
```

## Build the plugin
Run `yarn build` in the root of the project to build the plugin. The build can then be found in `/build/bundle`, and is a compressed file (`.zip`).

Upload the compressed file to the DHIS2 instance using the `manuall install` funciton in the **App Management** app. Now the plugin should be an available app on the instance and you can find it on this url:
- `<Url of instance>/api/apps/capture-growth-chart/plugin.html`

> **Note:** The growth chart will display a warning if it's missing the configuration file. The steps to complete this configuration file will be covered later in this guide.

Make sure to alter `<Url of instance>` with the actual url of you instance.
# Growth chart plugin download
The Capture Growth Charts plugin is availiable in the [DHIS2 App Hub](https://apps.dhis2.org/app/09f48f78-b67c-4efa-90ad-9ac2fed53bb8), and needs to be download in the **App Management** application.

# Configuration { #configuration }
## Maintenance app { #maintenance }
The following steps can be made in the **Maintenance** app on DHIS2.

### Data element
Data elements needed to support full functionality in for the growth chart are; **Weight**, **Height** and **Head circumference**. **Weight** can be in either `gram` or `kg`, but **Height** and **Head circumference** should be in `cm`. If one of the data elements are missing, growth charts using that data element will not be displayed.
Data elements needed to support full functionality in for the growth chart are; **Weight**, **Height** and **Head circumference**. **Weight** can be in either `gram` or `kg`, but **Height** and **Head circumference** should be in `cm`. If one of the data elements are missing, growth charts using that data element will not be displayed.

### Program
#### Tracked entity attribute
Tracked entity attribues needed for the Growth chart plugin is `Date of birth` and `Gender`.
Create a program for storing the growth variables and displaying the Growth Chart.
Documentation for configuring programs on DHIS2 can be found [here](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-241/configuring-the-system/programs.html).
#### Tracked entity attribute {#tracked-entity-attribute}
Tracked entity attribues needed for the Growth chart plugin is `Date of birth` and `Gender`.

> **Tip:** `First Name` and `Last Name` are also utilized in additional functionality, but not necessary for using the growth chart itself.
#### Tracked entity type
Navigate to the tracked entity type for **Person**. This type needs to be assigned the same attributes as those created in the [Tracked Entity Attributes](#tracked-entity-attributes) step. Make sure `Display in list` for the attributes is active, like the image below.
![Tracked entity type](resources/images/tracked_entity_type_attributes.png)
Navigate to the tracked entity type for **Person**. This type needs to be assigned the same attributes as those created in the [Tracked Entity Attributes](#tracked-entity-attribute) step. Make sure `Display in list` for the attributes is active, like the image below.
![Tracked entity type](resources/images/tracked_entity_type_attributes.png)

#### Program
Select your preffered program for storing the growth variables and displaying the Growth Chart.
#### Program
Select your preffered program for storing the growth variables and displaying the Growth Chart.
##### Attributes
The program should have the following attributes:
- `First name`
- `Last name`
- `Date of birth`
- `Gender`


##### Program stages
Select stage where growth variables currently are or will be stored.
The program stage should have the following data elements:
- `Weight` (g or kg)
- `Height` (cm)
- `Head circumference` (cm)



## Datastore Manangement app { #datastore_management }
### Capture namespace
In namespace `capture`, enter the file with key `enrollmentOverviewLayout`
Add new section for the growth chart under `leftColumn`. You can choose where on the left column to place it. Add the following code, but remember to change out `<Url of instance>` with the url of your instance.
```json
{
"source": "http://<Url of instance>/api/apps/capture-growth-chart/plugin.html",
"type": "plugin"
}
```
The following steps can be made in the **Datastore Management** app on DHIS2.
Documentation for the application can be found [here](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-240/maintaining-the-system/datastore-manager.html).

### Capture-growth-chart namespace
#### Config
Create new namespace `capture-growth-chart` with key `config`
The growth chart plugin needs this config to work. Keep in mind that all Id's should be changed, and will be specific for each implementation.

##### Metadata
The `metadata` object contains the following keys:
- `attributes` - Contains the attribute IDs for **dateOfBirth**, **gender**, **firstName**, **lastName**, **femaleOptionCode** and **maleOptionCode**. All of these attribute IDs can be found in the **Maintenance** app under `Tracked entity attributes`, except for the **femaleOptionCode** and **maleOptionCode** which can be found in `Option set` under **Other** in the **Maintenance** app.
- `dataElements` - Contains the data element IDs for **headCircumference**, **height** and **weight**. All of these data element IDs can be found in the **Maintenance** app under **Data elements**.
- `program` - Contains the program stage ID for the program stage where the growth data is stored. This ID can be found in the **Maintenance** app under **Programs** and **Program stages**.
#### Config
Create a new namespace `capture-growth-chart` with key `config`, as seen in the image below.
<img src="resources/images/DataStoreManagement_plugin_folder.png" width="500"/>

##### Settings
The `settings` object contains the following keys:
- `usePercentiles` - A boolean value that determines if the growth chart should use percentiles or z-scores. If `true`, the growth chart will use percentiles. If `false`, the growth chart will use z-scores
- `weightInGrams` - A boolean value that determines if the weight should be in grams or kg.
The growth chart plugin depends on this config to work properly.
Keep in mind that all ID's should be changed, and will be specific for each implementation.

The structure of the config has to be the same as the one in the example below;
```json
Expand All @@ -190,15 +88,44 @@ The structure of the config has to be the same as the one in the example below;
},
"settings": {
"usePercentiles": false,
"customReferences": false,
"weightInGrams": false
}
}
```
```

##### Metadata
The `metadata` object contains the following keys:
- `attributes` - Contains the attribute IDs for **dateOfBirth**, **gender**, **firstName**, **lastName**, **femaleOptionCode** and **maleOptionCode**. All of these attribute IDs can be found in the **Maintenance** app under `Tracked entity attributes`, except for the **femaleOptionCode** and **maleOptionCode** which can be found in `Option set` under **Other** in the **Maintenance** app.
- `dataElements` - Contains the data element IDs for **headCircumference**, **height** and **weight**. All of these data element IDs can be found in the **Maintenance** app under **Data elements**.
- `program` - Contains the program stage ID for the program stage where the growth data is stored. This ID can be found in the **Maintenance** app under **Programs** and **Program stages**.

##### Settings
The `settings` object contains the following keys:
- `usePercentiles` - A boolean value that determines if the growth chart should use percentiles or z-scores. If `true`, the growth chart will use percentiles. If `false`, the growth chart will use z-scores
- `customReferences` - A boolean value that determines if the growth chart should use custom references or the WHO references. If `true`, the growth chart will use custom references. If `false`, the growth chart will use the WHO references.
- `weightInGrams` - A boolean value that determines if the weight should be in grams or kg.

# Enable the plugin in the Capture enrollment dashboard { #enable_plugin }
## Tracker Plugin Configurator app { #tracker_plugin_configurator }
The **Tracker Plugin Configurator** app is used to enable the Growth Chart plugin in the Capture app.
To display the growth chart in the Capture app, use the **Tracker Plugin Configurator** app or follow the guide on [configuring enrollment plugins](https://kdb.devotta.com/docs/capture-plugins/enrollment-plugins).

> **Note:** You are now finished with the configuration and ready to use the Growth Chart plugin in the Capture app with WHO's standard references.
> If you want to use country specific references, follow the steps in the next section.
# Custom references { #custom_references }
The growth chart plugin can be configured to use country specific references, instead of the WHO's standard references.
This can be useful if you want to use references that are specific to your country or region.
The custom references can be set up in the **Datastore Management** app.
If you don't want to use custom references, you are finished with the configuration.
## Datastore Management app { #custom_references_datastore_management }
### Create custom references
1. Create a new key in the `capture-growth-chart` namespace with the key `customReferences`, as seen in the image below.

<img src="resources/images/DatastoreManagement_Custom_Folder.png" width="300"/>

#### Custom references
##### Create custom references
1. Create a new key in the `capture-growth-chart` namespace with the key `customReferences`.
2. Here is the format for the custom references:
2. Here is the format for `customReferences`:
```json
{
"<Indicator key>": {
Expand Down Expand Up @@ -242,7 +169,7 @@ The structure of the config has to be the same as the one in the example below;
}
```

3. Add the custom references you want to use. The structure of the custom references has to be the same as the one in the example below. But the contents of **percentileDatasetValues** and **zScoreDatasetValues** should be changed to your custom references. However, you don't need to add references for both percentiles and z-scores, you can choose to only add one of them if desired.
3. Add the custom references you want to use. The structure of the custom references has to be the same as the one in the example above. But the contents of **percentileDatasetValues** and **zScoreDatasetValues** should be changed to your custom references. However, you don't need to add references for both percentiles and z-scores, you can choose to only add one of them if desired.
4. Add other indicators if you want, but make sure that the key maps to the right category and gender. The indicator key should be one of the following:
- `"hcfa_g"` -> Head circumference for age
- `"lhfa_g"` -> Length/height for age
Expand All @@ -251,7 +178,7 @@ The structure of the config has to be the same as the one in the example below;
<br>
`"_g"` indicates that the gender is girl. If you want to add references for boys, you can add the same key but with `"_b"` instead of `"_g"`.
For example;
`"hcfa_b"` -> Head circumference for age
`"hcfa_b"` -> Head circumference for age, boys.


Here is an example of how the custom references could look like:
Expand Down

0 comments on commit 16b7e13

Please sign in to comment.