Configuration guide for the Generic Migration UI

The Generic Migration UI allows the Mobilize product developers to use a generic and configurable graphic user interface. In this page is specified how to configure each part of the generic migration UI.

Then, the defaut.json and production.json should be configured in order to specify all the migrator settings that will be loaded in the generic UI.

The default.json looks like this:

Configuring images and icons

The first step to configure images is to write the product name into the default.json (and production.json for a release version), it should look like this:

To configure the images and icons, they should be added to all the new images and icons in the following folder structure:

Images naming convention

In this section is explained how is the naming convention for each image, SnowConvert is used as example. In the following images can be seen all the images related to the product logos:

In the following image are listed the convention names for generic images of the application, these also can be changed:

With these images in svg format and with those names, the generic UI will place them in all the generic components regardless of their sizes. The containing folder should look like this:

Setting application icon

The application icon should be of 42x42 and in png format. The containing folder should look like this:

Configuring splash screen

To configure the splash screen it's needed a splash html and all the images that are used. The html must be named "splashscreen.html" and must be in "Overwrite\src\renderer\src\assets'productName'productName'" folder.

Its images must be placed in "Overwrite\src\renderer\src\assets'productName'\Images\splashscreen" and the html must specify the routes like

Configuring custom application texts

The generic migration UI uses the ngx-translate module of Angular to switch the text of the entire application depending on the current migrator loaded. More info: https://github.com/ngx-translate/core

To configure the texts for a new migrator, the default.json file should contain the Product.stringResources specifying the name of the file that contains the texts for a specific execution mode, as in the following image:

The .json files that contain the texts for the application should be added to the folder "Overwrite\src\renderer\src\assets\i18n" (It's the default folder for i18n) and its names should match with the ones specified in the previous image, for example:

Custom specific files

The Generic UI provides a lot of generic components, however, there are some that are specific for every converter. For example, the settings modal changes for every technology, the Winforms settings modal may differ from the Silverlight's. That's why exists a folder in the main module for every converter called Overwrite.

This folder contains all the specific files that are not generic like the default.json file previously described, the installer, styles, and components. The structure of the src folder inside the overwrite folder is a mirror of the src folder inside the UI folder which is the submodule of the Generic UI.

All the contents of these folders are going to be overwritten in the Generic UI once the next command is applied: "yarn configure:UI". This should be the first command before start working in the Generic UI.

These commands are in the Build folder:

The next command "yarn configure:sync" synchronize the files you modified in the Generic UI against the same files located in the Overwrite folder. In case new specific files are added they need to be added in the configure:sync command. It looks like this:

This is necessary to keep all these files sync between the Generic UI and the specific files in the main module. Keep in mind that these files must share the same name in all the converter's repositories because they are registered/imported in the app.module.ts file once:

Then, they are built.

Why this approach?

When this UI was created, only the SnowConvert Team was using it but then other teams started to use it as well like Winforms and SilverLight. That's when other specific components were needed and can't be generic like other components. We noticed there were many of them with similar names and implementations like "winforms-settings-modal" and "snow-settings-modal", they were loaded using dynamic loading in Angular. Even the assets folder was increasing every time a new client started using the Generic UI, so every time the Generic UI was increasing its size with components and files that were not part of the Generic UI itself.

After research made by the Generic Infrastructure Team, we concluded that this is the right approach that fulfills the requirements for the current UI and solved the problems we have found. There were other proposals but they cost more or don't fit with the current model.

Some of the proposals:

Proposal #1 - Current approach

Take advantage of the robocopy mechanism to keep sync the specific files for every converter that uses the Generic UI.

Pros:

The change for other teams is smooth.
Does not require a strong change in the architecture.
The robocopy was implemented before so it isn't totally new.
Quick implementation.
Moderate extensibility.

Cons:

It's not the most elegant solution.
It requires manual synchronization.

This implementation looks like this:

Proposal #2 - Angular libraries for specific components

This proposal is about to turn the specific components of every converter into an angular library which will be included in the Generic UI, but this will require having the app.module and the package.json files sync with the robocopy approach for every converter that uses the Generic UI. Not much different from #1.

Pros:

It is a natural implementation for Angular.
Every team will be responsible for its components.
Requires more time to implement it.
Moderate extensibility.

Cons

More responsibilities for every team that uses Generic UI.
The robocopy approach is not removed completely.
It requires manual synchronization.

Proposal #3 - Every converter has its electron app

This proposal is probably the most adequate but it will require a lot of effort and costs that we cannot do right now because of our priorities as a team.

The idea is that every converter that wants to use the Generic UI uses the generic components as a library and that they are responsible for the electron app. From the current implementation to the desire implementation of this proposal may look like this:

Pros: