Advanced customization (Extension)
Create project-specific dataset, event program, and tracker program forms in src/extensions/. Then commit your changes and create installation packages for testing and release.
iCapture v3 is a React and JavaScript application for DHIS2. Before starting, review the Architecture Overview to understand the shared core and project extension model.
Start here
- Read Fork the Core Repository.
- Follow Start iCapture v3 Locally to connect your fork to your DHIS2 instance.
- Read Extension Basics, and use Core Reference to find reusable stores, components, and helpers.
- Choose Create an Aggregate Form, Create an Event Form, or Create a Tracker Form.
- Complete Testing and Troubleshooting before sharing your project.
- Follow Conventional Commits and Commitizen, then create a local test ZIP or a versioned release.
Choose your form type
| Form type | Use it for | Guide |
|---|---|---|
| Aggregate | Values collected for a dataset, organisation unit, period, and applicable category dimensions | Create an Aggregate Form |
| Event | Individual events and their data fields in an event program | Create an Event Form |
| Tracker | Tracked entity attributes, enrollment, and program stage events | Create a Tracker Form |
Start with one small form. Confirm that it loads, saves, and restores saved values before adding advanced behaviour.
How the repositories work
The iCapture team maintains the original icapture-v3 repository. You receive read access and create a fork named icapture-v3-your_project_name in your own GitHub account or organisation. You develop your project's forms in that fork, inside src/extensions/.
Setup and reference
| You need | Where to find it |
|---|---|
| Forking the core repository | Fork the Core Repository |
| Local environment and DHIS2 connection | Start Locally |
| Extension files and form registration | Extension Basics |
| Stores, shared functions, and configuration | Core Reference |
| Reusable inputs, selectors, and UI controls | Component Catalog |
| Form examples and metadata packages | Aggregate, event, and tracker guides |
| Validation and troubleshooting | Testing and Troubleshooting |
| Commits and versioning | Conventional Commits and Commitizen |
| Local installation package | Create a Local Installation ZIP |
| Published releases | Versioning and Releases |
The guides use src/extensions/ relative to the application repository root. Replace example account names, connection settings, and metadata identifiers with the values for your project where instructed.
Maintenance agreement
- The iCapture team maintains core code and documents changes to extension interfaces.
- Project teams own their custom forms and project-specific configuration.
- Project teams use documented extension interfaces and keep customisation in the designated extension location wherever supported.
- Any required changes outside that location must be documented and reviewed during core updates.
- Project teams verify each update before using it in their deployed application.