WebUI System Library
When preparing your AIMMS model for use with the WebUI, you have to add the WebUI system library (as described in the Getting Started section). This library offers functionality that you can call yourself from your AIMMS model. This library uses the prefix webui
.
Pages and Dialog Support section
Pages and Dialog Support has been added to the AimmsWebUI library to be able to configure the List Widget , Workflow Panels , Status Bar , Side Panels , Dialog Pages , Page Actions , Widget Actions , Item Actions and some useful procedures in AIMMS. This section can also be used to identify the different page types, their PageId’s and Paths.

Public Pages Support Declarations
- Set webui::AllPageIDs
This set includes all the page ID for all page types added to the Page Manager (page tree).
- Index webui::indexPageId
- Set webui::AllPageTypes
This set includes the different page types, currently page, side panel and dialog.
- Index webui::apt
- Set webui::AllSidePanelPages
- SubsetOf
This set includes all the side panel pages added to the Page Manager.
- Index webui::aspp
- Set webui::AllDialogPages
- SubsetOf
This set includes all the dialog pages added to the Page Manager.
- Index webui::adp
- Element Parameter webui::PageType(indexPageId)
- Range
This element parameter indexed on
AllPageIDs
set maps which page type applies to which page id.
- String Parameter webui::PagePath(indexPageId)
This string parameter indexed on
AllPageIDs
set maps the path for each page created.
- String Parameter webui::PageName(indexPageId)
This string parameter indexed on
AllPageIDs
set maps the path for each page created.
Public Page and Widget Specification Declarations
- Set webui::SidePanelSpecification
This set is the specification for the side panel pages. The string parameters used to configure the side panels on pages are indexed on this set.
- Index webui::indexSidePanelSpec
- Set webui::WidgetActionSpecification
This set is the specification for adding widget actions . The string parameters used to configure the widget actions on certain widgets are indexed on this set.
- Index webui::indexWidgetActionSpec
- Set webui::PageActionSpecification
This set is the specification for adding page actions. The string parameters used to configure the primary action and secondary actions on certain pages are indexed on this set.
- Index webui::indexPageActionSpec
Public WebUI Frontend State Support Declarations
(note: this section was introduced with AIMMS 4.72, as the ‘webui state support’ Experimental Features.)
- Set webui::AllOpenWebUITabs
This set contains one element for each WebUI tab currently open. The element has the form of a UUID.
- Element Parameter webui::LastActiveWebUITab
An element parameter in
AllOpenWebUITabs
, which contains the UUID of the currently open WebUI tab in the browser (if any, it is empty otherwise).
- String Parameter webui::CurrentPageId
This string parameter contains the currently loaded page ID for all open tabs.
- String Parameter webui::CurrentSidePanelPageId
This string parameter contains the page ID for all open currently loaded side panels.
Public Workflow Support Declarations
- Set webui::WorkflowSpecification
This set is used to configure the number of Workflow Panels and their respective titles. The string parameter used to configure Workflows are indexed on this set. The elements of this set (defining workflow properties) are the following:
title
- The title for the workflow to be displayed on top of the Workflow Panelstyle
- A defined style for the workflow (This property is not in use currently. We have made the provision to incorporate different styles that we expect will be available in the future.)
- Set webui::WorkflowPageSpecification
This set is used to configure the steps for each workflow. The string parameter used to configure Workflow’s steps are indexed on this set. The elements of this set (defining workflow properties) are as follows:
displayText
- The label you want to give to the workflow stepicon
- The icon you want to associate with the step. You can select from a list of 1600+ icons, the reference can be found in the icon list. Custom icons can also be used if required.pageId
- The page Id of the Page this step should be associated with. Ideally, every page in a workflow is a step in the Workflow Panel. The page Ids can be referred from the pre-declaredAllRegularPages
set. Using page Ids of Side Panel or Dialog page will result in unwanted behaviour. This is a required field.tooltip
- The text to be displayed when the user hovers over the stepworkflowPageState
- The workflow state of the page, which may be Active (displayed and clickable), Inactive (displayed and not clickable) or Hidden (not visible). If not defined, by default the state is Hidden.pageDataState
- The data state of the page, which may be Complete, Incomplete or Error. The specification of this state is optional. If not defined, by default it has an Empty state.redirectPageId
- The page Id of the page the user should be redirected to when theworkflowPageState
is Inactive or Hidden. When the user tries to navigate to an Inactive or Hidden workflow step they are redirected to this page. The page Id’s can be referred from the elements of the pre-declared setAllRegularPages
.parentPageId
- This attribute is available from AIMMS 4.92 onwards. It can be used in order to indicate a parent step for some step in the workflow, so, actually making the latter a child step in the panel.
- Set webui::ExtensionOrder
This is a sub-set of the pre-declared set of
Integers
, which has several pre-declared indices. This set was created to make it easier to create and configure string parameters and also differentiate them for Workflows, Page and Application Extensions. The pre-declared indices:indexWorkflowOrder
andindexNoOfPages
are used as dimensions of the string parameters which will configure the Workflows and the steps of the Workflows in the application.indexPageExtension
is used as a dimension of the string parameter which will configure the Page Actions(Primary and Secondary), Side Panels and Widget Actions on pages and widgets respectively.indexApplicationExtension
is used as a dimension of the string parameter which will configure the Status Bar messages in the application.
- Index webui::indexWorkflowOrder
- Index webui::indexNoOfPages
- Index webui::indexPageExtension
- Index webui::indexApplicationExtension
Public StatusBar Support Declarations
- Set webui::StatusBarSpecification
This set is the specification used to configure Status Messages on the Status Bar that appears on the footer. You will need to create string parameters indexed over this set.
Public List Support Declarations
- Set webui::ListGroupSpecification
This set is the specification used to configure List Groups in the List Widget. You will need to create string parameters indexed over this set. The elements of this set (defining list groups) are the following:
title
- The title for the list group to be displayed in the List widget.tooltip
- Tooltip to be displayed when the user hovers over the respective list group’s title.
- Set webui::ListGroupItemsSpecification
This set is used to configure the list items in a specific list group. You will need to create a string parameter indexed over this set. The elements of this set (defining list group items) are the following:
icon
- The icon you want to display for the respective list item. You can select from a list of 1600+ icons, the reference can be found in the icon list. Custom icons can also be used if required.color
- The color you want to display for the icon configured, e.g., Blue, Red, etc. Browsers support around 140 color names. This is an optional field. You can also use Hex codes e.g., #FF0000 for Red.text
- The text you want to display for the list item. This is a required field.tooltip
- Tooltip to be displayed when the user hovers over the respective list item.procedure
- The procedure you want to call when the respective list item is clicked.external
- Boolean value to indicate the list item procedure leads to an external link. By default, this option is 0/false.state
- Active (displayed and clickable), Inactive (displayed and not clickable) and Hidden (not displayed). By default, the state is Hidden.
Request Queue Declarations is used to manage the number of requests from WebUI.
Public Pages Support Procedures
- Procedure webui::GetAllPages
This procedure runs every time a page, side panel or dialog page is added to the page manager, which in turn updates the sets and identifiers in the Public Pages Support Declarations.
- Procedure webui::OpenSidePanel(pageId)
This procedure is used to open side panels via the model with respective
pageIds
as the argument.
- Procedure webui::OpenPage(pageId)
This procedure is used to open/navigate to other pages in the application via the model, by passing the respective
pageId
as the argument.
- Procedure webui::OpenExternalLink(url)
This procedure is used to open external links, by passing the URL as the argument. These links will open in a new tab in the browser.
- Procedure webui::ResetRequestQueue
This procedure empties the
RequestQueue
and the Requests set in the Request Queue Declarations.
- Procedure webui::SetProgressMessage(message)
This procedure allows one to overwrite the “Busy” message in the top left corner of the Menu bar by a customized message, which can better inform the user in case the AIMMS session is in “working/busy” state (i.e., some code execution is going on in the background).
See SetProgressMessage below.
- Procedure webui::RefreshAllWidgets
This procedure can be called to force all widgets in your WebUI to be updated. Normally, WebUI widgets are updated only after an AIMMS procedure has been fully executed. In case of long(er) running procedures, you may want to provide your user with up-to-date info in any of your widgets before finishing the procedure already. In such cases, a call to
webui::RefreshAllWidgets
does exactly that. In order to get a clearer view of this data, you may want to use thewebui::UseTransparentVeil
procedure described below.Please know that this procedure uses a delay to allow for the widgets to actually refresh. Per default, this delay is set to 500 milliseconds. Should you encounter situations where you feel that a longer (or a shorter) delay is needed, you can adjust it by adapting the
webui.refreshallwidgets-sleep-milliseconds
option in the optionalwebui-options.conf
file.The current implementation of this procedure is still in an experimental phase. Based on any feedback by our users, we may decide to add arguments to it or to change the default delay, which would require you to adapt your models accordingly.
- Procedure webui::UseTransparentVeil
Calling this procedure has the effect that the veil which is applied to your WebUI page if the AIMMS session is in a “working/busy” state, will be transparent. In combination with the
webui::RefreshAllWidgets
procedure described above, you can use this to keep your users fully up-to-date while executing long(er) running procedures. The effect of the procedure ceases when its calling procedure has finished executing, so it is not a procedure that affects your whole further WebUI session. Please note that, although the veil is transparent, user interaction with any widget on the page (e.g. clicking a button, changing a value, etc.) is (by design) not possible.
Public Dialog Support Procedures
- Procedure webui::RequestPerformWebUIDialog(title, message, actions, onDone)
This procedure is used to display dialog message, such as alerts or warnings.
See RequestPerformWebUIDialog below.
- Procedure webui::OpenDialogPage(pageId, title, actions, onDone)
This procedure is used to open dialog pages via the model, either by clicking on a button or some interaction in the model.
See OpenDialogPage below.
- Procedure webui::IsWebUIDialogOpen
This procedure is used to check whether a dialog is currently open on the WebUI. It can be used to assert that no dialog is currently open before starting a new one.
Note
The procedures OpenSidePanel
, OpenPage
, OpenExternalLink
and OpenDialogPage
currently do not work as expected when called on a page load procedure. This issue will be expected to be fixed in the coming releases.
SetProgressMessage
In case that some longer code execution is going on in the background, your AIMMS WebUI session may be in “working/busy” state and the top left corner of the Menu bar may display the “Busy” message (instead of the application name shown normally):

In order to inform the user better on what is going on in such a situation, you can call the procedure SetProgressMessage
and overwrite the “Busy” message by a customized message depending on the current phase of the underlying code execution.
Argument
The message
argument of this procedure is a constant string or a string parameter which may be adjusted programmatically during the code execution.
Example
In case the application uses several procedures for executing first some initialization steps, then reading a substantial amount of data from a database and finally processing the data and computing some derived data, the procedure SetProgressMessage
may be called several times displaying in turn some customized messages such as:

Remark
Note that when the procedure SetProgressMessage
is called with an empty string argument, then the displayed message will be set back to the default “Busy” message.
RequestPerformWebUIDialog
You can call the procedure webui::RequestPerformWebUIDialog
to display a message dialog in a WebUI page. Along with the message you can also display buttons which you can bind to custom actions.
Arguments
This procedure has the following arguments:
title
: A string parameter which contains the text to be displayed as the title of the dialog box.message
: A string parameter which contains the message to be displayed in the dialog box.actions
: A set containing custom actions. The elements of this set are represented as buttons in the message dialog and their text is the same as the action names. When an action is selected (i.e. its corresponding button is clicked), it invokes theonDone
procedure with the corresponding action as an argument.onDone
: A reference to a procedure in the predeclared setAllProcedures
. The procedure should have a single input string parameter as argument. When a user selects an action, theonDone
procedure is invoked with the action name as its argument.
Example
As an example, the following code will display the dialog in the picture below it and will call the procedure PerformAction(TheAction)
upon clicking one of its buttons (with TheAction
being an input string parameter argument):
MyActions := data { Yes, No, Cancel };
webui::requestPerformWebUIDialog("Save", "Do you want to save your data?", MyActions, 'PerformAction');

Remarks
When you just want to send a message to the user, you should provide a single action (e.g.
Actions := {'OK'}
) and you can use''
for theonDone
argument. In this case, no procedure is called, and the user can just close the ‘dialog’ by pressing the single action (or pressing the return/space key, which will press the default (last, highlighted) button).You can use a translation file (e.g. ‘WebUI/resources/languages/<dialog_actions>.properties’) to provide translations for the various internal action names, containing, for example:
discard-and-continue = Discard and continue
.Translation files are described in more details in Multi-Language Support
OpenDialogPage
You can call the procedure OpenDialogPage
to invoke a dialog page in a WebUI page. Along with opening the dialog page you can also configure the title and the buttons with a specific callback.
Arguments
This procedure has the following arguments:
pageId
: An element parameter (with rangeAllDialogPages
) which should contain thepageId
of the dialog page you want to open. When a dialog page is created, an entry is added to the setAllDialogPages
under the Public Pages Support Declarations with a uniquepageId
in the Pages and Dialog Support section. Case sensitivity applies topageId
mapping.title
: A string parameter which contains the text to be displayed as the title of the dialog box. If this is left blank, i.e “”, it will display the dialog page name given during creation by default.actions
: A set of custom actions. The elements of this set are represented as buttons in the message dialog and their text is the same as the action names. When an action is selected (button is clicked), it invokes theonDone
procedure with the corresponding action as an argument. If this set is empty, the buttons will have “Cancel” and “OK” by default respectively.onDone
: A reference to a procedure in the set AllProcedures. The procedure should have a single input string parameter as argument. When a user selects an action, theonDone
procedure is invoked with the action name as its argument.
Example
As an example, the following code will display the dialog in the picture below it and will call the procedure Procedure_Actions(TheAction)
upon clicking one of its buttons (with TheAction
being an input string parameter argument):
MyActions:= data { Decline, Accept };
pageId := 'dialog_page';
webui::OpenDialogPage(pageId, "Dialog Page Title", MyActions, 'Procedure_Actions');

The declaration of the procedure Procedure_Actions in the example is

When the user clicks either button, the callback sends the respective button’s text back to the string parameter. In the example we use the response to set a Flag to true or false based on which button is clicked.