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::AllRegularPages

SubsetOf

AllPageIDs

This set includes all regular pages added to the Page Manager, corresponding to the entries in webui::AllPageIDs, excluding side panels and dialog pages.

Index webui::arp

Set webui::AllSidePanelPages

SubsetOf

AllPageIDs

This set includes all the side panel pages added to the Page Manager.

Index webui::aspp

Set webui::AllDialogPages

SubsetOf

AllPageIDs

This set includes all the dialog pages added to the Page Manager.

Index webui::adp

Element Parameter webui::PageType(indexPageId)

Range

AllPageTypes

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 serves as the specification for the Side-Panels and Tabbed widgets.

The string parameters used to configure the side panels on pages or setting up Tabs on the Tabbed widget are indexed on this set.

Index webui::indexSidePanelSpec

Index webui::indexTabSpec

Set webui::WidgetActionSpecification

This set serves as 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 serves as 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 Panel

• style - 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 step

• icon - 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-declared AllRegularPages 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 step

• workflowPageState - 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 the workflowPageState 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 set AllRegularPages.

• 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 include:

• indexWorkflowOrder and indexNoOfPages 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.

• indexNoOfTabs is used as a dimension of the string parameter which will configure the Tabs on the Tabbed widget.

Index webui::indexWorkflowOrder

Index webui::indexNoOfPages

Index webui::indexPageExtension

Index webui::indexApplicationExtension

Index webui::indexNoOfTabs

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.

Public MenuBar Support Declarations

Set webui::MenuBarSpecification

This set is the specification used to configure the Menu Bar items in the application header. You will need to create a string parameter indexed over this set.

The elements of this set (defining Menu Bar items) are the following:

• displayText - (Required) The text label to be shown for the page link in the Menu bar.

• pageId - (Required) The pageId of the regular page (from the AllRegularPages set) that this link refers to.

• tooltip - (Optional) Text displayed as a tooltip when users hover over the link.

• parentPageId - (Optional) The pageId of a parent link, allowing this link to appear as a child item in a nested menu structure.

• state - (Optional) Controls the visibility and interactivity of the link: Active (visible and clickable), Inactive (visible but not clickable), or Hidden (not shown; default).

Index webui::indexMenuBarSpec

Request Queue Declarations

The identifiers in this section are used to manage the number of requests from WebUI.

Public Identifier Support

String Parameter webui::IdentifierElementText

This string parameter can be used to customize the display text of Identifiers and Indices shown within the widgets on your WebUI. For full details, please see this section.

String Parameter webui::IdentifierElementHtml

Similar to the above, this string parameter too can be used to customize the display text of Identifiers and Indices. However, this String parameter becomes particularly handy when you need to include formatted text, links, or other rich content in the display text. HTML tags in the display text will be interpreted as markup instructions, resulting in the display of properly formatted content. For full details, please see this section.

Important

We recommend utilizing either of the two features mentioned above for translating the display text of Identifiers and Indices, instead of depending on the unsupported traditional method of using .properties files for translations.

String Parameter webui::IdentifierTooltip

This string parameter can be used to customize the tooltip text shown when hovering over Identifiers and Indices shown within the widgets on your WebUI. For full details, please see this section.

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.

Public Notification Procedures

Procedure webui::RequestShowNotification(message, title)

This procedure can be used to trigger an operating system (OS) notification from the browser window in which the WebUI is running. More specifically, this library procedure may be called inside an AIMMS procedure, which, in turn, may be used behind an action triggered from the WebUI front-end.

This library procedure has two formal arguments of type string as illustrated in the following picture:

The contents of the two strings used as actual arguments upon calling this procedure is displayed in the shown notification.

For example, calling the procedure webui::RequestShowNotification after the solve statement in an AIMMS procedure can be used to trigger a notification from the browser to the operating system which notifies the user that the optimization has been completed.

webui::RequestShowNotification("The optimization procedure has been completed", "Optimization Completed");

In order to actually get such notifications on your screen you have to enable notifications in your system and browser settings. For illustration, on a Windows 11 machine the system setting for enabling notifications should look like in the following picture:

If the system notifications are not enabled, then the WebUI notification will not be shown at all.

Similarly, a browser setting for enabling notifications from a specific site is illustrated bellow:

If the notifications are restricted on the browser, then the WebUI user may get an error message with a text such as: “Notification Support: A notification from this site was received, but notifications are currently disabled in the UI”.

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 the webui::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 optional webui-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.

Public Pages Support Procedures

These procedures allow to trigger from within the AIMMS model the (temporary) display of some additional information on a WebUI page.

SetProgressMessage

Procedure webui::SetProgressMessage(message)

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.

ShowMessage

Procedure webui::ShowMessage(messageLevel, message)

This procedure allows to trigger a message to the user (both in developer mode and in end-user mode) from within the AIMMS language and display that message at the top of the current page in the WebUI (i.e. in the browser).

It takes two arguments: the first is the “level” and the second is the message to be displayed. For the levels ‘warning’ and ‘error’ a call to the webui::ShowMessage procedure will behave in the same way as the execution of the commands raise warning or raise error from within the model.

In addition, the ‘info’ level can now be used to send an informational message to the WebUI user (which was not possible in combination with a raise command in the language).

For example, a call to the webui::ShowMessage procedure can be used to display an appropriate message when uploading a file by using the procedure webui::RequestFileUpload (see further below).

Public Dialog Support Procedures

These support procedures allow to display a dialog window with some message along with some potential actions which the user can choose from.

RequestPerformWebUIDialog

Procedure webui::RequestPerformWebUIDialog(title, message, actions, onDone)

You can call the procedure webui::RequestPerformWebUIDialog to display a dialog message on 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 the onDone procedure with the corresponding action as an argument.

• onDone: A reference to a procedure in the predeclared set AllProcedures. The procedure should have a single input string parameter as argument. When a user selects an action, the onDone 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 the onDone 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

Starting from AIMMS 24.2 the WebUI library contains a parameter webui::RequestQueueSize defined as the cardinality of the set webui::Requests, which is present in the public Interface of the WebUI library. So, its value may be accessed from outside the library and may be used to check from within the AIMMS language whether there is currently a dialog opened by a call to the procedure webui::RequestPerformWebUIDialog. This way the app developer may prevent another call to the procedure webui::RequestPerformWebUIDialog while a dialog is already open in the WebUI.

OpenDialogPage

Procedure webui::OpenDialogPage(pageId, title, actions, onDone)

You can call the procedure OpenDialogPage to invoke a dialog page on 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 range AllDialogPages) which should contain the pageId of the dialog page you want to open. When a dialog page is created, an entry is added to the set AllDialogPages under the Public Pages Support Declarations with a unique pageId in the Pages and Dialog Support section. Case sensitivity applies to pageId 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 the onDone 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, the onDone 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 this example is shown below:

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.

Public Upload and Download Procedures

Starting from AIMMS 24.3 the WebUI library provides support for uploading and downloading a file by using some dedicated procedures.

Public Upload Procedures

Procedure webui::RequestFileUpload(onDone)

This procedure can be used to upload a file programmatically from your local computer to the AIMMS application (running on a PRO server). When running this procedure a dialog is opened in which the user may choose the file to be uploaded.

The input argument onDone is an element parameter with the range the predeclared set AllProcedures. The actual procedure argument used when calling webui::RequestFileUpload is a callback procedure defined by the app developer (for example, “HandleUpload”), which is invoked immediately after the upload has been completed. The prototype of this callback procedure should have three arguments as illustrated in the following picture:

In particular, the output arguments such as statusCode and statusDescription can be assigned appropriate values in this callback procedure based on the outcome of the upload process.

The argument fname illustrated above denotes the name of the uploaded file. For security reasons, no absolute paths are allowed to be specified for the location where the uploaded files are stored. Instead, this procedure uses the same conventions as described in the section Upload Widget.

Public Download Procedures

Procedure webui::RequestFileDownload(fname)

This procedure can be used to download a file programmatically from the AIMMS application (running on a PRO server) to your local computer. At the end of the execution of this procedure the default download functionality of your browser is used to download the file on your local machine.

The input argument fname is an string parameter which denotes the name of the downloaded file. For security reasons, no absolute paths are allowed to be specified for the location where the files to be downloaded are stored. Instead, this procedure uses the same conventions as described in the section Download Widget.

Typically the file to be downloaded is generated prior to calling webui::RequestFileDownload. Therefore, before calling this procedure it may be useful to check whether the file denoted by the argument fname actually exists. This can be achieved by using the procedure FileExists as shown below:

if FileExists(webui::GetIOFilePath(fname)) then webui::RequestFileDownload(fname) endif;

Here the pre-defined function webui::GetIOFilePath works as explained in the section Download Widget.

Timezone Support Section

The WebUI System Library includes a section called “Timezone Support,” which contains identifier declarations used by the Timezone settings feature in the WebUI. It also includes identifiers for retrieving information about the end user’s browser, such as the browser name, language, and timezone.

MappedBrowserTimeZone

Element Parameter webui::MappedBrowserTimeZone

This element parameter holds the value of the AIMMS time zone that corresponds to the current user’s browser time zone, based on the webui::BrowserTimeZoneMapping identifier.

The webui::MappedBrowserTimeZone can be used to define the Timeslot format for a calendar, as illustrated below. When applied, the displayed date and time will adjust according to the time zone of the current user.

Authorization Support

The WebUI System Library includes a section called “Authorization Support” containing identifier declarations which can be used to introduce authorization into your WebUI app:

The usage of these identifiers is discussed in the section Creating a WebUI.