Operating WinUI_to_WebUI
Introduction
Moving an existing application from WinUI to WebUI by hand means rebuilding every page, widget and layout, and adding the identifiers each WebUI page needs. The WinUI_to_WebUI converter does this work from the command line. It reads the WinUI pages of the AIMMS project in the current folder and writes the WebUI pages and widgets back into the same folder.
The converter adds the identifiers the WebUI pages need to a generated module in the main model and in each library. It also writes a conversion log with warnings and the objects it could not convert, so you know what to finish by hand.
This article is the operating guide for the converter. Running the converter is only the first step of a conversion. How to refine the result page by page, by hand and with SENSAI, is described in Converting a WinUI Application to WebUI.
Instructions
Setup
Download the zip file from the releases page and unpack it.
Make a backup of your project. The tool modifies files inside your project folder: it adds generated identifiers to your model and writes the WebUI output directly into the project. Commit the project to source control, or copy the whole folder, before you run it.
Check that the project folder contains exactly one
.aimmsfile.
Running a conversion
Open a terminal (Command Prompt or PowerShell).
Go to the folder that contains your
.aimmsfile:cd C:\path\to\your\project
Run the tool:
WinUI_to_WebUI
The tool does the following:
It detects the
.aimmsfile in the current folder.It adds the
AimmsProsystem library and the WebUI repository library, if the project does not reference them yet.It converts all WinUI pages and writes the WebUI output for the main model and for every library that has pages.
It adds the identifiers the WebUI pages need to a generated module in each component.
The generated module in the main model is GeneratedInterfaceIdentifiersMain with prefix giim. In each library it is GeneratedInterfaceIdentifiersLibrary with prefix giil.
During the run, the tool temporarily copies the ModelEditAimmsPython library into the project and removes it again at the end. That library wraps model editing functions such as me::Create and me::SetAttribute in procedures like the one below.
1Procedure pr_getDim {
2 Body: {
3 _ep_id := StringToElement( AllIdentifiers, sp_id, create: 0);
4 if _ep_id then
5 p_dim := IdentifierDimension( _ep_id );
6 else
7 p_dim := -1 ;
8 raise warning formatString("Dimension of undeclared \"%s\" unknown", sp_id);
9 endif ;
10
11 return 1 ;
12 }
13 ElementParameter _ep_id {
14 Range: AllIdentifiers;
15 }
16}
Progress is printed to the console. Lines that start with Warning: report non-fatal issues, for example a PageManager.xml that could not be parsed. They do not stop the conversion. A fatal problem prints an error and exits with a non-zero code. See Errors.
Reviewing the result
Review the changes in your source control diff, or compare against your backup.
MainProject\WebUI\webui.jsonholds the converted pages. Each library with pages gets an equivalent file.<project>_conversion.mdis the conversion log. It lists warnings, objects that were not converted, and the choices made per object.
Options
Run WinUI_to_WebUI --help for the built-in summary.
Option |
Effect |
|---|---|
|
Convert a single page and leave every other page in |
|
Convert WinUI data coloring. Off by default. |
|
How to convert Network Objects. Default |
|
Spacing of nodes in a converted network diagram. Default |
|
Let pages with the same custom grid shape share one layout. |
|
Repoint every element parameter ranged over |
Converting a single page
By default the tool rebuilds the entire webui.json of every component from scratch. This discards manual edits made in the WebUI editor, and changes made with SENSAI. To iterate on one page without disturbing the rest of an already converted WebUI, pass --page:
WinUI_to_WebUI --page pageName
pageName must match the Name attribute of the page in PageManager.xml, which is the same name used for its Pages\<pageName>.xml file. It is not the WebUI slug.
Only that page’s entry and its widgets in
webui.jsonare replaced. Every other page already on disk stays unchanged, including manual layout and widget edits.A component that has pages but no
webui.jsonyet still gets a fresh basewebui.jsonwith no pages converted into it.If the page is not found in any component, the tool exits with an error and does not touch any file.
The tool still processes every page internally to keep the generated identifiers consistent, so --page does not make the run much faster. It only limits what is written to webui.json.
Converting data coloring
WinUI data coloring (a table’s Colors or Background_Color, a chart’s Color) is not converted by default, because the generated stylesheet also colors widgets that do not use coloring. To convert it, pass --colors:
WinUI_to_WebUI --colors
This turns each coloring into a webui::AnnotationsIdentifier on the colored identifier. It creates the giim::s_AllColors color set with p_Red, p_Green, p_Blue and p_ColorSlug, and it writes WebUI\resources\css\w2w-color.css in the main model.
Without --colors, none of this is generated, and a w2w-color.css left behind by an earlier --colors run is removed. The option can be combined with --page and --newcolorset.
Converting network objects
A WinUI Network Object becomes either a WebUI Map widget, with nodes placed by latitude and longitude, or a WebUI Diagram widget, with nodes placed by x and y. Choose with --network:
WinUI_to_WebUI --network=auto
WinUI_to_WebUI --network=map
WinUI_to_WebUI --network=diagram
WinUI_to_WebUI --network=ignore
The default, auto, decides per Network Object:
A GIS background (shapefile layers) in the WinUI object gives a map.
Otherwise, node coordinates whose names read as longitude (X) and latitude (Y), for example
p_Longitude( i )orLatitude_center( r ), give a map.Otherwise, the Network Object becomes a diagram.
map and diagram force that widget for every Network Object in the run. ignore converts no Network Object at all: they get no widget and take no space in the page’s grid. Their number is reported at the end of the conversion log. The choice and its reason are recorded per object in <project>_conversion.md.
To mix choices within one project, combine --network with --page. Convert the whole project once with the default, then reconvert a page whose Network Object should be the other widget:
WinUI_to_WebUI --page "Network Tie Flows" --network=map
Keep the following in mind:
A WebUI Diagram supports one arc set per widget. Only the first arc set of a Network Object is converted. The others are listed in the conversion log.
Diagram coordinates are rescaled from the WinUI visible area to a drawing space the size of the WinUI object times
--diagram-spread, with the Y axis flipped. The initial zoom of the diagram is 1/spread. WebUI draws each node as a labeled box, much larger than the WinUI dot, so the spread gives the nodes room. Use for example--diagram-spread 4for more room, or--diagram-spread 1for the WinUI pixel size. The rescaling is done by generated parameters (p_diagram_x_...andp_diagram_y_...) in the generated module.GIS background layers, node and arc sizes, shapes and colors are not converted.
When the WinUI visible area is computed at run time, the bounds of the map are left unset. The conversion log mentions this.
Repointing AllColors element parameters
WebUI cannot use the predeclared set AllColors as it is. Normally, the tool repoints the Range of an identifier ranged over AllColors to its own generated set giim::s_AllColors only when a converted widget uses that identifier for data coloring, so only with --colors.
To repoint every element parameter in the project whose Range is AllColors, including the ones no converted widget references, pass --newcolorset:
WinUI_to_WebUI --newcolorset
This option can be combined with --page. It is off by default, because it changes identifiers outside what the conversion itself needs.
Errors
Message |
Cause |
|---|---|
|
Run |
|
The folder contains more than one |
|
The |
|
Internal error: the detected path no longer exists. |
Minimal Requirements
AIMMS 26.8. The tool opens the project with the latest installed AIMMS 26.8.x. You can get a license from the AIMMS Community.
The WebUI library. A project that already references WebUI keeps its own version. A project without WebUI gets the WebUI repository library 26.13.1 added.
WinUI_to_WebUI.exe, from the release zip.A WinUI project and a backup of it.