Module development

[]

By now, you must be all set for the actual development. Frontend development is done by adding new modules or modifying existing ones (to a certain extent).

Create a new module

This section is about correctly placing your custom code inside your HCMS CSK project and "registering" the module inside the application to make it correctly visible inside the portal.

Step 1

You need to create a new folder with the name of your module in the frontend-app/src/modules.

Step 2

In the frontend-app/src/modules, you will find a template folder. Copy all files from this folder and paste into your module folder.

Step 3

In the module-info.json file, you need to add information about your module. Below you can check what every entry is for.

```json
  "id": string, // unique id of module - same as directory name of module (used as library name & url routing)
  "src": string, // relative path
  "name": string, // name of module
  "icon": string, // material icon
  "roles": string[], // users with any of those roles will have access to module
  "modules" {id, name, icon, library}[] // (optional) list of submodules
  "group": {"id": string, "name": string, "icon": string}, // (optional) more than one modules with same group will be represented as a collapsing group
  "library": string // (optional) id of another module. When it is set it will use the library of the set module
  // Next 3 attributes are optional and used only in Managment module as visual description of module
  "description": string, // (optional) short description
  "text": string, // (optional) long description
  "screen": string // (optional) screen url
```

Step 4

Now you need to add the same information into the config.json file you created before. The complete file path is frontend-app/web/data/config.json.

You can copy-paste an existing section and edit it accordingly. Especially the module id must be identical. Inside the src element, you can add any port that is not yet reserved for anything else. Optionally, you can add the module name property - if used - to the only_modules list inside that file.

Step 5

You need to add your module to the module list. In the frontend-app/src/shared/lib/Data/ModuleInfo.ts , create a new type and link it to the module id.

Step 6

Next, you need to define the location from which the module will be imported. This can be done in the ModuleLoader.ts, the full path" frontend-app/src/core/lib/Loader/ModuleLOader.ts .

Inside the constant moduleLoader, you need to add a new case statement with the type from the previous step as well as the folder location of the new module.

Step 7

You may want to give the new module a correct name/translation that will be displayed in the left side navigation bar. This can be done in the frontend-app/src/shared/lib/Translation/en.json (for English) and must correspond to what you enter in the same JOSN file located inside the module folder; full file path: frontend-app/src/modules/<<your-module>>/lib/Translation/locale/en.json (for English).

Step 8

To make a module fully work, it needs to be added to two configuration parameters.

Exceptions are modules authentication and theme: without these modules, application would be completely broken. That‘s why they are always available and activated, regardless of the actual configuration.

Both parameters are lists. Please make sure to add modules to them in exactly the same order and pay attention to additional steps:

add to availableModules
- restart your application to make your changes effective
add to activatedModules or
- add in the GUI: in the left navigation, click on Modules and select the module

Step 9

You can now test the visual representation of your new module by adding some simple HTML changes, e.g.:

<p> Hello World </p> to frontend-app/src/modules/<<your-module>>/components/Page/Page.tsx. Then execute:

SHELL

cd frontend-app
npm run dev-all-modules`

You new module must be visible in the left navigation and the home page of it must contain the added paragraph.

Start your own development

Feel free to start with adding more custom code to your module.

Build the new module

Your new module needs to be exported as {Id}Module, e.g. MediaModule. The first letter of the module id must be capital. To do so:

SHELL

   mount: (handler: HTMLDivElement, config: Config) => Promise<void>; // function fires when module is mounted
   unmount: (handler: HTMLDivElement) => Promise<void>; // function fires when module is unmounted

Example content of the resulting module-info*.json:

JSON

 {
   "id": "media",
   "src": "/modules/media/module.min.js",
   "name": "Media",
   "icon": "photo_library",
   "roles": ["media_read", "media_full"],
   "group": { "id": "mediaGroup", "name": "Media", "icon": "photo_library" },
   "library": "",
   "description": "Manage media assets",
   "text": "The Media Module allows easy access to all of your media assets. You can search, download and upload new media files.",
   "screen": "screens/media.png"
 }

Make sure that /frontend-app/webpack.config.js is in place and all your changes in it are finalized.
Run make -f deployment/docker/Makefile dist to build your new module.

The result must generate a web/module*.js JavaScript file. This file is automatically added to the final Docker image. Additionally, a screens directory is also added to the result (if it exists). Any other required files must be added to the Makefile.