feat(custom-forms): legacy custom forms plugin (#480)

[kabaros]

implements https://dhis2.atlassian.net/browse/DHIS2-19900

This plugin adds support for legacy custom forms in the new data-entry app. It aims to make using these custom forms (with JavaScript code) as frictionless as possible so that the old forms can - ideally - work as they are without changes. The approach for this support is achieved by:

1. Providing all the JavaScript base libraries that were available in the Struts app pre-v42, i.e. jQuery, jQuery UI etc..
2. Updating the global scripts in form.js to work for v42+ maintaining - as much as possible - their existing interface so that the upgrade is seamless for existing consumers.
3. Providing a shim for other implicit contracts, i.e. HTML elements like #selectedDataSet or #selectedPeriodId that were used in the past for certain operations like getting current dataSet or period.
4. Document workarounds for operations that can not be supported as they are so that implementers and developers have a way forward with the least amount of hassle possible.

ToDos

• The core: load all JS files defined in the old Struts app, and a shim for commonly used global properties and functions
• support dhis2.de.currentOrganisationUnitId and other properties available in dhis2.de
• Forms with an attribute option combo don't work currently
• update all the form.js API calls that are deprecated (i.e. all the calls to .action struts routes)
• completing/incompleting forms
• validating forms
• view details of data elements
• view history of data elements
• open details with Cmd/Ctrl - Enter
• printing forms - won't do - it's not possible given there is total flexibility in CSS in custom forms. The authors can provide print CSS if they wish
• offline support
• support all/most field types (date, etc...)
  • support Date value type
  • support File value type
• forms with option sets
• forms with indicators
• show error messages with useAlert (proxy setHeaderDelayMessage to useAlert)
• support inline CSS
• API requests to relative path: '../api/data....' (handled with jQuery AJAX override)
• Support custom tabs: a lot of custom tabs with jquery plugins: $( "#tabs" ).tabs();
• jquery UI: floatThead, tabs,
• pass "localize string" from the parent app (and other localization functions)
• Others
  • values outside of min/max range for a given DE are accepted in custom form implementation, but would be warned in non-custom forms [maybe this is consistent with old app, or we don’t care]
  • sometimes the plugin height is less than the total available, so it makes a kind of weird scrollbar. I guess this is just a css issue that we don’t care about for now:
• decide what to bring over from the old Struts /src/main/webapp/dhis-web-commons/javascripts/commons.js
  • show/hide loader - an idea was to use the loader from the new data-entry app, but this is technically difficult as it causes a re-render of the form. Likely we will just support whatever loader the custom form had in the code (i.e. jQuery UI)
  • ensure events: dhis2.util.on(dhis2.de.event.formReady", dhis2.de.event.dataValuesLoaded, dhis2.de.event.dataValueSaved, dhis2.de.event.completed
  • which base styles?
• Possible future optimisations:
  • concatenate all JS for faster loading
  • Remove the calendar/period helpers and logic
  • maybe make loading some JS files optional (through dataStore seting?)
  • ? Replace jQuery DOM manipulation with native APIs as they're mostly redundant in modern browsers now
  • ensure the external scripts are cached on production (or reused by the plugin) etc... the service worker is taking care of that

Testing

To test the custom form plugin, run Aggregate the Data Entry app from this branch as usual (yarn install && yarn start), then navigate to any existing custom form.

This PR supersedes this PoC: #346

Current state (5/09)

custom-form-2025-09-05.webm

supersedes #480

[dhis2-bot]

🚀 Deployed on https://pr-485--dhis2-data-entry.netlify.app

[sonarqubecloud]

Quality Gate failed

Failed conditions
526 New issues
105 New Critical Issues (required ≤ 0)
520 New Code Smells (required ≤ 0)
6 New Bugs (required ≤ 0)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[sonarqubecloud]

Quality Gate failed

Failed conditions
8 New issues
1 New Critical Issues (required ≤ 0)
8 New Code Smells (required ≤ 0)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE