DHIS 2 app for configuration of metadata
Switch branches/tags
2.28-dev 2.28 Aggregation-type-last-value DHIS-4682-optionset-unique-fix DHIS2-384-session-handling DHIS2-966-hierarchy-operations-ui DHIS2-975-option-group DHIS2-980/locale-ui-management DHIS2-1283-attribute-not-created-for-option DHIS2-1283-update-attributes-after-delete DHIS2-2151-Sharing-UI DHIS2-3202/sql-views DHIS2-3260/icon-picker-in-maintenance-app DHIS2-3261-color-palette DHIS2-3261/color-palette-in-maintenance-app DHIS2-3343/program-rule-action-send-message DHIS2-3399/program-rule-action-options DHIS2-3403-program-notification-parent DHIS2-3663-add-ProgramStageVariable DHIS2-3667/predictor-groups-in-maintenance-app DHIS2-3819-schedule-message-programruletype DHIS2-3928/sql-views-additional-work DHIS2-3951-category-combos-hidden-in-data-set-elements-for-data-set-api-endpoint DHIS2-4027/sql-view-bottom-scrollbar DHIS2-4145-Relationship-Type DHIS2-4197/incorrect-render-options-when-data-element-is-added DHIS2-4251-select-program-attributes-of-type-email-when-creating-program-notifications DHIS2-4252-tracked-entity-attributes-in-program-stage-notifications DHIS2-4278-incorrect-uid-population-in-message-template-for-program-attributes DHIS2-4320-cannot-update-tracker-program-stage-for-program-notification DHIS2-4658-cannot-search-for-data-elements-blank-ones-get-selected DHIS2-4684-cannot-add-te-as-to-te-ts DHIS2-4692-relationshipType-options DHIS2-5318-fix-color-and-icon-picker-for-option-sets DHIS2-5487-locale-filter-is-broken Feature/dynamic_choice_of_list_columns TECH-93/tweak-eslint-configuration backport-DHIS2-5318-to-v31 backport-v29/DHIS2-4584 backport-v30/DHIS2-4584 backport/DHIS2-3579-default-programType backport/DHIS2-3611-clone-clear-created-date backport/DHIS2-4484-attributes-eventprogram backport/formname-tea backport/optiongroupset-optionset-filter backport/remove-clone-optionSet backport/update-docs-links-optiongroup bug/validationRule_expressions_not_saved_properly chore/dev-auth-app-load-error chore/editModel_refactor chore/refactor-optionset-files chore/refactor_config_override_category_fields chore/replace-createClass dhis2-2643-long-rule-variables-not-shown dhis2-2665/predictor-output-combo dhis2-3080-tea-skip-sync dhis2-3867/allow-audit-level dhis2-4128/allow-free-text-target-boundaries dhis2-4529 feat/DHIS2-942-column-configuration feat/DHIS2-4595-validationstrategy feat/formname-tea feature/DHIS2-11-tracker-programs feature/color-sets feature/colorSets feature/data-entry-form fix/DHIS2-2457-new-fields-for-eventprogram fix/DHIS2-2578-snackBar-lineheight fix/DHIS2-2777-data-dimension-clear-selection fix/DHIS2-3167-wrong-elements-in-custom-form fix/DHIS2-3562-validation-on-save fix/DHIS2-3611-clone-clear-created-date fix/DHIS2-4369/fix-psde-domaintype-crash fix/DHIS2-4584-delete-program-stage fix/DHIS2-4584-delete-ps fix/DHIS2-4692-relationship-add-tet-program fix/DHIS2-4924-cloning-program-rule fix/DHIS2-5316-option-group-translations fix/DHIS2-5323-configurable-columns-orgunit-load fix/Optiongroupset-optionset-filter fix/RP229-14-misaligned-field fix/column-config-black-list fix/custom-registration-delete fix/disable-save-on-saving fix/duplicate-loading-router-race-cond fix/loading-new-optionset fix/prevent-remove-tea-from-tet fix/remove-custom-attributes-enrollmentstep fix/remove-unused-featuretype-options fix/sharing-dialog-new-translation fix/sharing-dialog-new-translations fix/tea-update-te-to-tet fix/update-doc-links-optiongroup fix/updateSharingDialog-viva fix/updateSharingDialogTo1.0.2 fix/validatePrograms-refactor fix/2.27-validation-on-save greenkeeper/initial i18next master patch/DHIS2-5323 program-form-testing ps-translations remove-broken-error-msg remove-lint-errors replace-coordinates-with-featuretype sonarqube sql-view templateUid-programRuleAction test/implement-header-bar test/new-code-style tracked-entity-type-featuretype translations-urdu try-out-prepare update-builds upgrade/material-ui-0.20.0 v22 v23 v24 v25 v26 v27 v29-Palestine v29 v30 v31
Nothing to show
Clone or download
erikarenhill Fixed so the icon behind the picker does not update until you actuall…
…y confirm. Cancel also cancels the selection as expected. (#593)
Latest commit 10cf977 Dec 17, 2018



Build Status

App config

The maintenance app is largely driven by the app config and the schemas from the API. The schemas are read directly from the API (by D2). The following documents the app config:

  • within src/config/ ...
    • maintenance-models.js defines the model types that are shown in the app
    • field-config/ contains configuration for each model type
      • field-order.js defines the order of fields within the form for each model type
      • field-groups.js defines field grouping for the form for each model. This is currently only used for programRules, but it might be a good idea to expand it to other model types as well.
    • field-overrides/ contains extra configuration for fields that require non-standard behavior. Most commonly this means fields that require special components.
      • index.js lists all models that have one or more field overrides
      • The actual field overrides are specified in files named after each model type, which in turn are imported into index.js. Some model types or fields that require a lot of logic are separated into sub folders.
    • inlinehelp-mapping.json specifies mapping from each section/model-type to pages in the documentation.
    • field-rules.js contains conditional logic that can be used to show or hide fields or set field values based on the value of other fields.
    • periodTypes.json contains the list of period types that are supported by the current version of the API.
    • disabled-on-edit/ contains files that list fields that will always be displayed as read-only when an object is being edited.
      • index.js imports lists of field names from files named after each relevant model

For the record, "schemas" and "model types" are essentially the same thing and these terms are used interchangeably both in the maintenance app and elsewhere. Schemas are exposed by the API, but not every model type is listed in the schemas. To add to the confusion "models" are also some times referred to as "objects".

Sections, model types and fields

In order for a model type to show up in the maintenance app, the following conditions need to be met:

  • The model type is listed under a section in src/config/maintenance-models.js
  • The model type exists in the schemas endpoint in the API

Once these conditions are met, the model type will show up in the maintenance app under the section specified in maintenance-models.js. When creating or editing models of the new type, the form will by default only contain a handful of predefined fields. In order for additional fields to be shown in the form, the following conditions need to be met:

  • The field is listed under the model type in src/config/field-config/field-order.js
  • The field exists in the schemas endpoint for the specific model type in the API.

Adding a new model type

Adding a new model to the maintenance typically involves the following steps:

  1. Add the model type to src/config/maintenance-models.js
  2. Add the model type and the list of fields that should be shown in the form to src/config/field-config/field-order.js
    1. (Optional) If the fields should be separated into separate groups in the form, the groups can be specified in src/config/field-config/field-groups.js.
  3. The new model type should now be listed in the maintenance app. Navigate to the new model type and check the form both when creating a new instance of the model type and when editing an existing instance. If you're lucky, everything will just work at this point. More likely there will be one or more fields that require further customization.
  4. Create a new file named after the new model type in src/config/field-overrides/. Open src/config/field-overrides/index.js, import the newly created file and add it to the overridesByType object.
  5. Inside the new field override file (src/config/field-overrides/newType.js), start adding customizations for the fields that require it. This typically involves creating new components and/or overriding certain field properties. Look at the existing field overrides for examples.
  6. Strings that show up as ** string ** in the UI lack translations. These will need to be added to the translations files located in src/i18n/. Some strings are generated dynamically and may only show up in certain situations, for example when trying to delete a model. Note: the translation workflow should at some point change to using i18next in favor of d2.i18n.

Extra special cases

Certain models require customization beyond what's possible using the config and field overrides. In those cases it may be necessary to create a new top level component and associate that component with a special route in src/router.js

Examples of this approach includes:

  • Event program editor: src/EditModel/event-program/EditEventProgram.component.js
  • Custom form editor: src/EditModel/EditDataEntryForm.component.js