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.