Skip to content

Extension Basics

Create your project's custom forms inside src/extensions/ in your fork of iCapture v3. This page introduces the shared concepts used by the aggregate, event, and tracker tutorials.

Before you start

Complete Fork the Core Repository and Start Locally. Confirm that the standard form opens against your test DHIS2 instance before changing its layout.

1. Understand the core and project fork

The iCapture team maintains the shared core. Each project forks that repository into its own account or organisation and adds its custom forms inside src/extensions/. Project teams maintain these forms and check their compatibility when receiving core updates.

2. Know the extension files

The core provides these extension files:

src/extensions/
├── extensionConfig.js
├── useExtensions.jsx
└── useCustomInit.js
File Purpose
extensionConfig.js Exports extension name, application name, application icon, and PWA settings.
useExtensions.jsx Hook called during core initialisation; the core starts with an empty implementation. Add project extension configuration here.
useCustomInit.js Optional custom initialisation hook; the core currently exports null. A simple custom form does not require changing it.

Create additional files for your form components inside src/extensions/. The folder and component names in the guides are examples; you can choose names that suit your project.

3. Understand form registration

The core stores extension configuration in src/store/extensionStore.js. Its setExtensions(keyPath, value) function updates a configuration entry using a dotted key path or an array of keys.

Form type Configuration entry Registered value
Aggregate aggregate.forms[DATASET_UID] Form component
Event event.forms[PROGRAM_UID] Object containing Form, validations, and rules; optional disableDhis2ProgramRules
Tracker stage tracker.programConfig[PROGRAM_UID][STAGE_UID] Stage form component
Tracker profile tracker.programConfig[PROGRAM_UID].profileForm Profile form component

These entries are read by the core's aggregate, event capture, tracker stage, and tracker profile features. Registration shapes differ between form types: use the appropriate shape for the tutorial you follow.

The aggregate, event, and tracker guides include form examples and metadata packages. The tracker guide demonstrates a custom profile and two program stages.

4. Map fields to DHIS2 metadata

Use metadata identifiers to connect form fields to data. Display labels can change or be translated.

  • Aggregate fields need a data element and category option combination, within the selected dataset and reporting context.
  • Event fields belong to the event program's stage.
  • Tracker profile fields use tracked entity attributes; tracker stage fields use data elements.

Each form guide lists the identifiers used by its metadata package. If you create your own metadata, use the identifiers generated by your DHIS2 instance in the extension configuration.

5. Reuse the core form behaviour

The core uses React Hook Form and shared DHIS2 input components. Custom layouts should integrate with the existing form context, validation, loading, and saving behaviour.

An aggregate custom form is rendered within the core's form provider. Event custom forms receive status and setLoading. Tracker stage custom forms receive programStage, status, editing, and loading.

Preserve the disabled states, validation feedback, and data binding supplied by the core. Follow the corresponding form guide for the props used by each workflow.

See Core Reference for quick explanations of the stores, shared inputs, helpers, and settings available to extensions.

6. Define the form requirements

Write down:

  • Project name and form name.
  • Form type and target dataset or program identifier.
  • Required context, such as organisation, period, event, entity, or enrollment.
  • Fields, metadata identifiers, input types, and allowed values.
  • Required fields and validation rules.
  • Visibility rules, calculations, and read-only fields.
  • User permissions and expected save behaviour.

For example, the aggregate guide maps its First visits field as follows:

Label Metadata identifier Input type Required Validation or visibility rule
First visits OpBsCYrBapb INTEGER_ZERO_OR_POSITIVE No Whole numbers greater than or equal to zero

Use the test environment's real metadata identifiers. Labels alone are not a reliable data mapping.

Next step

Choose Create an Aggregate Form, Create an Event Form, or Create a Tracker Form.