This repository holds the configuration files for the openIMIS Frontend Reference Implementation:
- Legacy web application
- Modular front end
Please look for the direction on the openIMIS Wiki: https://openimis.atlassian.net/wiki/spaces/OP/pages/963182705/MO1.1+Install+the+modular+openIMIS+using+Docker
Note: the modular frontend is part of the release ZIP of the legacy webapp, if the modular frontend need to be changed then new modular frontend static files need to be placed in /inetroot/www/openIMIS/front
Note 2: The docker file can be change to build first the frontend by uncommenting the "downloader" related lines.
This repo branches, tags,... are maintained by openIMIS official delivery team who use it to build the official openIMIS Docker images containing the official modules (versions) list.
In case of troubles, please consult/contact our service desk via our ticketing site.
This repository holds the configuration files for the openIMIS Frontend Reference Implementation. It serves 2 distinct use cases:
- developers who want to implement new modules or modify existing frontend modules of openIMIS
- distributors who want to assemble modules into a Docker image for delivery
Note: please, refer to openIMIS Frontend localisation to provide translations and bind user's language to a locale for data format (dates, numbers,...)
This repo branches, tags,... are maintained by openIMIS official delivery team who use it to build the official openIMIS Docker images containing the official modules (versions) list.
In case of troubles, please consult/contact our service desk via our ticketing site.
When programming for openIMIS frontend, the shared (with openimis-fe_js) dependencies (react,...) must be declared as *peerDependencies* in your package.json file. You are also highly encouraged to used the features provided in the openimis-fe-core module. This includes (but is not limited to) main menu entries, date handling, user info,... Another important point is NOT TO HAVE in backend db table user_Core (managed by Django) user called 'admin' or 'Admin'. This could case defects while running frontend via command `yarn start`. This issue is related to the link between userCore and tblUser tables. |
- clone this repo (creates the
openimis-fe_js
directory) - install node (node V16.x)
- install yarn
- within
openimis-fe_js
directory- generate the openIMIS modules dependencies and locales (from openimis.json config):
yarn load-config
oryarn load-config openimis.json
- install openIMIS technical dependencies:
yarn install
- start openIMIS frontend (in development mode):
yarn start
- generate the openIMIS modules dependencies and locales (from openimis.json config):
-
within
openimis-fe_js
directory- generate the openIMIS modules dependencies and locales (from openimis.json config):
yarn load-config
oryarn load-config openimis.json
- clean yarn cache in case local directory / git /link are used:
yarn cache clean
- install openIMIS technical dependencies:
yarn install
- build openIMIS frontend (in development mode):
yarn build
- copy the build folder on the webserver
- generate the openIMIS modules dependencies and locales (from openimis.json config):
```{
"name": "CoreModule", // If name is not provided, it will assume the module is exported as the `default` module
"npm": "@openimis/[email protected]"
}```
At this stage, your browser opened on localhost:3000 with current openIMIS frontend. In developement mode, the frontend connects to the backend via a proxy configuration, expecting to reach the backend on localhost:8000 (cfr. /package.json file, "proxy" entry).
- checkout the module's git repo NEXT TO (not within!)
openimis-fe_js
directory and create a git branch for your changes - from
openimis-fe-claim_js
- install module dependencies:
yarn install
- build current (dev) version of the module:
yarn build
- prepare a linkable version of your local package:
yarn link
- install module dependencies:
- from
openimis-fe_js
- uninstall the packaged module you want to work on (example @openimis/fe-claim):
yarn remove @openimis/fe-claim
- link the local version of the module:
yarn link "@openimis/fe-claim"
- uninstall the packaged module you want to work on (example @openimis/fe-claim):
Note:
- It is not necessary to register a linked module in the package.json file
- To unlink a previously linked package:
yarn unlink "@openimis/fe-claim"
- [OPTIONAL] To enable live reload of the module, from
openimis-fe-claim_js
, activate the watch:yarn start
(if configured into thepackage.json
of the module)
- create a (git-enabled) directory next to the other modules:
/openimis-fe-mymodule_js
. Note: the module name can be different from the directory/github repo. The npm repo has an @openimis scope to group all openIMIS modules - to be integrated in openIMIS ecosystem, you module should provide an entry entity (e.g. MyModule) with its contributions (MainMenu entries,...).
- prepare a linkable version of your local package:
yarn link
(from within/openimis-fe-mymodule_js
) - from /openimis-fe_js:
- install the linkable version of your package:
yarn link @openimis/fe-mymodule
- add your module (name and entry entiry) in
openimis.json
and regenerate the modules import script:node module-requirements.js
Note: to ease development lifecycle, please consider using the 'rollup' mechanism (see @openimis/fe-core for an example)
- install the linkable version of your package:
To create a distinct implementation of an existing openIMIS module (e.g. @openimis/fe-location-dhis2
)
Unlike backend modules, there is 'shared logical name' between distinct implementations of a same 'module'. If you want to provide an distinct implementation for locations (example), just create a separate module, with a distinct module name and ensure the packaging (distribution) picks your module (and not the reference implementation).
- adapt your package.json (bump version number, ensure license is mentioned,...)
- commit your changes to the git repo and merge to master
- tag the git repo according to your new version number
- publish to npm central repo:
npm publish
(from within/openimis-fe-mymodule_js
) Note: you'll need to login,... (cfr. https://docs.npmjs.com/cli/publish)
Note: As a distributor, you may want to run an openIMIS version without docker. To do so, follow developers setup here above (up to starting the server with yarn start).
- clone this repo (creates the openimis-fe_js directory) and create a git branch (named according to the release you want to bundle)
- adapt the openimis-fe_js/openimis.json to specify the modules (and their versions) to be bundled
- make release candidates docker image from openimis-fe_js/:
docker build . -t openimis-fe-2.3.4
- run the docker image:
docker run -p 8080:80 openimis-fe-2.3.4
(exposing the 80 port to 8080 port of docker host)
When release candidate is accepted:
- commit your changes to the git repo
- tag the git repo according to your new version number
- upload openimis-be docker image to docker hub
Note: This image only provides the openimis frontend server. The full openIMIS deployment (with the backend,...) is managed from openimis-dist_dck repo and its docker-compose.yml file.
-
from
/openimis-fe_js
:- run this command:
node dev_tools/installModuleLocally.js <repourl> <branch>
- for example
node dev_tools/installModuleLocally.js https://github.com/openimis/openimis-fe-contract_js.git develop
- run this command:
-
this command executes every steps to install module locally. Those steps are:
- Download module from GitHub repository using git clone.
- Go into module directory
- Within this directory run
yarn install
,yarn build
andyarn link
(according to that provided order) - Within openimis-fe_js:
-
execute
yarn remove @openimis/fe-invoice
-
In openimis.json openimis add:
{ "name": "ContractModule", "npm": "@openimis/[email protected]" }
-
Edit package.json - in "dependencies" put or update this module that you want to run from local environment:
{ ... "dependencies": { ... "@openimis/fe-contract": "file:../openimis-fe-contract_js", ... } ... }
-
execute
node modules-config.js
-
run
yarn link <module>
for example:yarn link "@openimis/fe-contract"
-
run
yarn install
-
after this you can execute
yarn start
and you should see local module in your imis application.
- from
/openimis-fe_js
:- run this command:
node dev_tools/addCIToModule.js <moduleNameDirectory>
- for example
node dev_tools/addCIToModule.js openimis-fe-invoice_js
- run this command:
- this command allows to add files to execute CI on every PR and allows to publish to npm.
- if
.github/workflows
doesn't exist in particular module, this directories are created while running this command - files to be added through that command based on provided templates:
- CI_and_build.yml
- npmpublish.yml
- those files are saved in
.github/workflows
- from
/openimis-fe_js
:- run this command:
node dev_tools/installModuleLocallyAll.js
. This command will execute all required steps to fetch all modules present inopenimis.json
from the git repositories and install them as editable libraries.
- run this command:
- create separate new module based on frontend template module.
- this module should be named like:
openimis-fe-language_{lang}_js
for exampleopenimis-fe-language_es_js
(Spanish language) - add to this module such files as:
.babelrc
,.gitignore
,.estlintrc
- within
src/translation
add{lang}.json
file for examplees.json
- in
index.js
withinsrc
modified (for example we want to have 'es' Spanish language):
import messages_es from "./translations/es.json";
const DEFAULT_CONFIG = {
"translations": [{ key: "es", messages: messages_es }],
}
export const LanguageEsModule = (cfg) => {
return { ...DEFAULT_CONFIG, ...cfg };
}
- build your new module with translations by typing within this module
yarn build
,yarn install
andyarn link
commands. - in
tblLanguages
on database level add new language for example 'es' (Spanish language) - within assembly frontend module
openimis-fe_js
inopenimis.json
add language key for new language/localization for example:
...
"locales": [
{
"languages": [
"es",
"es-ES"
],
"intl": "es-ES",
"fileNames": "es"
},
{
"languages": [
"en",
"en-GB"
],
"intl": "en-GB",
"fileNames": "en"
},
{
"languages": [
"fr",
"fr-FR"
],
"intl": "fr-FR",
"fileNames": "fr"
}
],
...
- in
openimis.json
add also this newly created module with translations - within
openimis-fe_js/src
inlocales.js
add new language like below:
export const locales = ["es-ES","en-GB","fr-FR"]
export const fileNamesByLang = {"es":"es", "es-ES":"es","en":"en","en-GB":"en","fr":"fr","fr-FR":"fr"}
export default {"es":"es-ES", "es-ES": "es-ES","en":"en-GB","en-GB":"en-GB","fr":"fr-FR","fr-FR":"fr-FR"}
- type
yarn build
and if success - typeyarn start
and you should see this translation in your app (go to 'users' page, select user, change language into the newly provided, refresh page and you should see texts in changed language) - if you encounter any problems by that point, run
yarn load-config
in the main module - there is also possibility to overwrite particular language for example 'English' into 'Gambian English' (without changes on database level). In your new translation module in index.js (for example new module called
openimis-fe-language_en_gm_js
):
import messages_en from "./translations/en.json";
const DEFAULT_CONFIG = {
"translations": [{ key: "en", messages: messages_en }],
}
export const LanguageEnGmModule = (cfg) => {
return { ...DEFAULT_CONFIG, ...cfg };
}
- this approach overwrites default
en
language translations intoen-gm
(Gambian English) translations without adding new language on database level and without changing 'locales' in 'openimis.json' and 'locales.js' file both on assembly frontend module (openimis-fe_js).
Based on error reported on that ticket
Description of error:
- after
yarn start
the page loads but no content is display - sometimes it just keeps spinning the loader
- web console doesn't show any errors
How to solve this?
- double check if you use proper versions of backend/frontend modules (assembly and core ones)
- make sure you have the latest version of dockerized database
Conclusions:
- The reason of this error is usually using not up-to-date assembly and core modules (both backend and frontend ones)
Based on error reported on that ticket
Description of error:
- modular openIMIS deployed on server
- backend is set on port 8000, frontend is set on port 3000
- backend works fine, no errors
- it is not possible to reach both login and home page due to 400 error
- web console doesn't show any errors
How to solve this?
- double check if you use proper versions of backend/frontend modules (assembly and core ones)
- make sure you added env variables on backend side (site root/sire url)
- double check value for
proxy
key in package.json (IMPORTANT: be careful with this setting on production environment)
Conclusions:
- The reason of this error is usually not setting up env variables on backend side and wrong value for
proxy
key
If you face another issues not described in that section you could use our ticketing site. Here you can report any bugs/problems you faced during setting up openIMIS app.