Tips and Tricks Converting a WinUI Application to WebUI
Introduction
The WinUI_to_WebUI converter converts the pages of a WinUI application, and SENSAI helps to refine them. See Converting a WinUI Application to WebUI. Some parts of a WinUI application are not pages, though: a splash screen, progress windows, and message dialogs. This article gives tips for these parts:
Converting dialogs that wait for the user, and what to do when the dialogs form a workflow.
Presenting many messages as a structured list of notifications.
Reporting progress in both WinUI and WebUI.
Removing the WinUI splash screen, and adding a logo to the WebUI.
Each tip is a change like any other in the conversion process: make it, check it, and store it in git or a backup copy.
Converting Dialogs That Wait for the User
In WinUI, the dialog functions DialogAsk() and DialogMessage() are synchronous. The execution stops at the call, and continues after the user presses a button. The code after the call can use the answer, and all local variables of the procedure.
In WebUI, the corresponding procedure webui::RequestPerformWebUIDialog returns immediately. The dialog is shown in the browser, but the procedure that called it just continues, and typically ends. Only when the user selects an action, AIMMS calls a second procedure, the ondone procedure, with the name of the selected action as its argument. See the WebUI library.
You can try the example in this project: AIMMS 26.8 project download
An example in WinUI. The local parameter p_count is used both before and after the dialog:
Procedure pr_deletePlants {
Body: {
p_count := Count( i_plant | bp_selected( i_plant ) ) ;
if DialogAsk(
formatString( "Delete %i plants?", p_count ),
"Delete", "Cancel", "Delete plants" ) = 1
then
pr_deleteSelectedPlants ;
sp_status := formatString( "%i plants deleted", p_count ) ;
endif ;
}
}
The same function in WebUI. The code after the dialog moved to pr_deletePlantsDone, and p_count became a global parameter:
Procedure pr_deletePlants {
Body: {
p_count := Count( i_plant | bp_selected( i_plant ) ) ;
webui::RequestPerformWebUIDialog(
title : "Delete plants",
message : formatString( "Delete %i plants?", p_count ),
actions : s_deleteActions, ! the set { Delete, Cancel }
onDone : 'pr_deletePlantsDone' ) ;
}
}
Procedure pr_deletePlantsDone {
Arguments: (sp_action);
Body: {
if sp_action = "Delete" then
pr_deleteSelectedPlants ;
sp_status := formatString( "%i plants deleted", p_count ) ;
endif ;
}
}
To convert a dialog call:
Replace the call by
webui::RequestPerformWebUIDialog. The buttons become the elements of theactionsset, in the order of the buttons.Create the ondone procedure, with one input string argument. Move all code after the dialog call to this procedure. Where the WinUI code tested the number of the button, test the name of the action instead.
Make every local identifier that is used both before and after the dialog global, so the ondone procedure can read it. Declare it in the model, and give it a clear name, because it now lives as long as the application.
Make sure the calling procedure does nothing after the dialog call that depends on the answer. This includes the code of the procedures that called it: when they continue right after the call, they continue before the user has answered.
To only show a message, as with DialogMessage, use a single action such as OK and pass an empty string as ondone procedure. No procedure is called then.
A few things to look out for:
A dialog in a loop, or several dialogs in a row, becomes a chain of ondone procedures. The ondone procedure of the first dialog opens the second one, and so on.
Only one dialog can be open at a time. Before opening a dialog, check
webui::IsWebUIDialogOpen, or the number of waiting requestswebui::RequestQueueSize.In WinUI, pressing Esc or closing the dialog counts as pressing the last button. Check what the WebUI dialog does in that case, and put the safe action, usually Cancel, last.
When a dialog is complicated
For a single dialog, the steps above are all you need. Some applications are more complicated: the user goes through several dialogs in a row, and the code decides from the data which of them to show. Converting such a chain into ondone procedures works, but the result is hard to read and to maintain. Two alternatives are often better:
Redesign the dialogs as a workflow. When each dialog asks the user for a decision, or for input, that belongs to a step of the process, make that step a page in a workflow panel. The user then sees where they are in the process, and can go back. See AIMMS Workflow Panel.
Replace informational dialogs by notifications. Many dialogs do not ask for a decision at all. They only inform the user, for example:
about exceptional input, such as data errors, or
about exceptional output, such as an unexpected result of an optimization.
Present these as notifications, as described in the next section, and keep dialogs only for decisions.
Presenting Many Messages as Notifications
Many dialogs only inform the user, and do not ask for a decision. For those, use notifications instead of dialogs.
WinUI applications often report findings one by one, for example with a message dialog per problem found during a data check. With a few messages, that works. With many messages, the user clicks through a series of dialogs, and the information is gone once the dialog is closed.
In that case, collect the messages in a list of notifications, and present that list on a page in the WebUI. The library libUITools does this. Instead of a dialog, the model calls one procedure per finding:
uit::pr_addNotification(
sp_message : "Capacity of plant P1 is negative",
ep_severity : 'warning',
bp_preventsSolve : 1,
ep_page1 : 'plant_data',
ep_page2 : '');
Each notification has:
a message,
a severity:
info,warningorerror,whether it likely prevents a successful solve, and
up to two pages where the user can fix the cause.
The library shows the notifications in a table. The user can show all notifications or only the unhandled ones, mark a notification as handled, delete it, and open the related page directly from the table row.
Note
The example project contains libUITools: AIMMS 26.8 UIToolsTest project download
To switch to notifications:
Add
libUIToolsto the project.Replace the message dialogs that report findings by calls to
uit::pr_addNotification. Keep a dialog where the user must make a decision before the computation can continue. See Converting Dialogs That Wait for the User for how to convert such a dialog.Add a page with the notifications table, and make it easy to reach, for example as a step in the workflow panel.
Reporting Progress in WinUI and WebUI
Many WinUI applications report the progress of a long computation with DialogProgress(), which shows a progress window with a message and a percentage. In WebUI, the counterpart is webui::SetProgressMessage, which shows a message while the WebUI waits for the computation. See the WebUI library.
When the model reports progress regularly, and you want to keep the WinUI version working during the conversion, use the small library libUITools. Its procedure uit::pr_DialogProgress has the same arguments as DialogProgress:
In WinUI mode, it calls
DialogProgress( message, percentage ).In WebUI mode, it calls
webui::SetProgressMessagewith the message, the percentage, and a bar of ten blocks, for exampleSolving 40% [████______].
The library also provides the flags uit::bp_useWebUI and uit::bp_useWinUI, which you can use for other code that differs between WinUI and WebUI.
Note
libUITools is part of the download of the example project of the previous section.
To use the library:
Add
libUIToolsto the project, for example with . When the project is in git, you can add the library as a git submodule, so updates of the library are easy to take over.Replace each call
DialogProgress(byuit::pr_DialogProgress(. This is a typical routine change to ask SENSAI for:In all procedures of the model and its libraries, replace each call to DialogProgress by a call to uit::pr_DialogProgress, with the same arguments.
Set
uit::bp_useWebUI := 1when the application runs in the WebUI. The flag is 0 by default, so the application starts in WinUI mode. A suitable place is the procedure that runs when the WebUI loads its first page: in the WebUI, open the page settings of the home page, and set the procedure upon load, for example:Procedure pr_openHomePage { Body: { uit::bp_useWebUI := 1 ; webui::OpenPage( 'first_page' ); } }
Removing the Splash Screen and Adding a Logo
Removing the WinUI splash screen
AIMMS shows a startup bitmap as splash screen when it starts with a project: a file <project-name>.bmp in the project folder. For a project MyApp.aimms, that is MyApp.bmp. The splash screen belongs to the desktop application. In a WebUI application, users see the application in their web browser, and the logo belongs in the WebUI itself.
To stop AIMMS from showing the splash screen, rename the bitmap, for example to MyApp-winui-logo.bmp:
Rename the file in the project folder.
Search the WinUI pages and templates for the old file name, for example in the
.xmlfiles belowMainProject\PagesandMainProject\Templates, and in the libraries. WinUI pages and templates often show the same bitmap as a logo. Point them to the new name, so the WinUI version keeps working while you convert.Check that WebUI image widgets do not use the old file. These widgets use their own copy below
MainProject\WebUI\resources\images, so renaming the bitmap in the project folder does not affect them.
When the WinUI version is no longer needed, you can remove the bitmap altogether.
Tip
While you convert, set the AIMMS option Open_WebUI_on_Startup to 1. AIMMS Developer then opens the WebUI as soon as the project is opened.
Adding a logo to the WebUI
The WebUI shows an application logo at the top left of the window, to the left of the application name, when you set it in a theming stylesheet. See A special case: the application logo.
Put the logo image in
MainProject\WebUI\resources\images, for examplelogo.png.Create a stylesheet in
MainProject\WebUI\resources\css, for exampletheming.css:/* Application logo in the header, left of the application name. --bg_app-logo : <left offset> <vertical position> / <width> <height> no-repeat url(<image>) --spacing_app-logo_width : the space reserved for the logo; without it, no logo is shown. /app-resources/ maps to the MainProject/WebUI folder. */ :root { --bg_app-logo: 15px 50% / 145px 32px no-repeat url(/app-resources/resources/images/logo.png); --spacing_app-logo_width: 161px; }
Reload the WebUI.
Keep the following in mind:
Without
--spacing_app-logo_width, no logo is shown. Make it at least the left offset plus the logo width, here 15 + 145 = 160 pixels.Keep the aspect ratio of the image. For an image of 435 x 96 pixels (ratio 4.53 : 1), a displayed size of 145 x 32 pixels does not stretch the logo.
Use an image of two or three times the displayed size, so the logo stays sharp on high-resolution screens.
The height of the header limits the height of the logo.
/app-resources/maps to the folderMainProject\WebUI. That is why the path containsresources/images.
Summary
Convert a dialog that waits for the user by moving the code after the dialog to an ondone procedure, and by making the shared local identifiers global.
Collect many messages as notifications in a table, instead of a series of dialogs.
Use
libUIToolsto report progress in both WinUI and WebUI with a single call.Rename the WinUI startup bitmap to stop the splash screen, and show the logo in the WebUI header with a theming stylesheet.