In here you will find a growing list of ‘Tips & Tricks’ for building WebUI Apps. Initially this will just be a list. As the list grows we may choose to structure it differently.

Identifiers to use the AIMMS Map Widget

In the desktop UI, you needed an X- and Y coordinate as two separate identifiers. In the WebUI you just need one identifier indexed over two indices, the index related to the locations and one extra index. The set belonging to that second index should contain 2 elements. The first element will be related to X-Coordinates and the second element to the Y-Coordinates. See also screen capture below and supportive snippet of AIMMS Model Code.


The navigation object can have a hierarchical setup with main and subitems as pages. You can achieve this by adding the first subpage as <Folder/SubPageName> instead of just a page name (btw: Currently, all pages are ordered alphabetically. Take this into account when naming your pages).


Renaming or Moving Pages in the AIMMS Navigation Widget

You can rename pages by Editing their name. If the page is placed in an hierarchical structure (thus not located on the top level), you can adjust both the ‘folder’ as the page name and move pages around one-by-one.


Adding Data-Dependent Styling to an AIMMS App

You can define so-called user-annotations in your AIMMS model that will be used to style corresponding DOM elements in the WebUI web page. To define user annotations for an identifier X(i,j,k) that is being displayed in a widget, you can define a string parameter X_annotations(i,k) (the domain of the ‘annotations’ identifier should be a valid subdomain of the original identifier). The ‘annotations’ identifier should be a space-separated string of class-names (that will be used decorate the DOM elements with). In combination with an additional project-specific CSS file, you can then specify the styling on, for example, a per-table-cell basis.

For example, the following ‘user annotation’

    StringParameter X_annotations {
	IndexDomain: (i,k);	
        Definition: "invalid-value danger" onlyif ( Y(i,k)  > Y_UB(i,k) );

In combination with the following CSS rule

    .aimms-widget td.invalid-value {
	background-color : red;

will make all cells in tables with ‘invalid’ values showing with a red background color.

Adding project-specific translations to an AIMMS App

In addition to the built-in translations in WebUI, you can now add your own translation files to your WebUI applications. Model data (identifiers, set elements etc.) can then be translated according to the browser’s language.

Please note that you can translate not only from one language to another, but also from model abbreviations to strings that are more readable by the end-user, e.g.:

F_X_EGG = Egg

Translation files should be placed anywhere below your project’s /resources/ folder, and must use the following naming-conventions:

Please note that you can create as many translation-files as you like. This allows you to keep a clear topic/subject per file.

To provide a default translation in English for your addon, create a file <anything>.properties with your translation pairs:

org_name = Organization name

To provide a translation for another language, e.g. nl, create a file <anything> with your translation pairs:

org_name = Organisatienaam

To provide a translation for a language-locale, e.g. en-GB, create a file <anything> with your translation pairs:

org_name = Organisation name
Switching the Color Palette for Graphs or Charts

For this please check this thread on our Google Group.

Adding your Own Theme to an AIMMS App

For this please check this thread on our Google Group.   Return to PRO-WebUI Overview

Providing contents for your Gantt chart widget

With the introduction of AIMMS 4.5, the AIMMS WebUI framework has been extended with a Gantt chart widget. This Gantt chart widget is a first version and will be further improved in future AIMMS WebUI versions.
When pivoting the Gantt chart widget, a row of one or more jobs (i.e. a resource) is created for every label (or tuple of labels) in the set corresponding to the index (or indices) in the resources part. All other indices are part of the jobs part.
The first version of the Gantt chart has the following restriction

Preventing the widgets from rearranging any time you make a change in window size

You may find that when you change window size the widgets re-arrange too often. A simple way to prevent that is to limit the maximum number of columns. You can do this via the ‘settings’ icon just to the right of the page name.

Keep Widgets Together as a Group

The group widget allows you to group a small number of widgets together. This way you can easily create form-like structures or simply keep two or more widgets together. It is not intended to be a replacement for page layout.

The group widget comes with a number of templates, numbered from 1 through 11, which you can select in the option dialog. These provide you with various options with secondary content aligned to the left, right, top or bottom of your main widget (note: In the near future, these will be replaced with visual representations). These “templates” provide different areas in which you can add widgets. To add and remove widgets, the group widget has the concept of “edit mode”. When you press the “edit group” button, the available areas will get a darker background and will show a “plus” sign. By clicking on one of these areas, you can add a widget, just like on a page.

Each template has a main area and one or more secondary areas. These secondary areas always have a fixed width or height, while the main area sizes to the available space. The ideal configuration for a group widget is thus to have your main widget, such as a chart or table, in the main area, and secondary widgets, such as selection widgets or buttons, in the secondary areas.

When in edit mode, you can add widgets, or remove them by dragging them onto the top bar (where it says “drag widgets here to remove”). As of now, you cannot drag widgets from one area to another, or outside of the group widget. This might change in the future. You can get out of edit mode by clicking the “edit group” button again, or by pressing the “x” in the top right corner of the edit bar. Not all widgets are suitable to be placed in all template areas. For now, the group widget does not take this into account (note: in the future we will prevent the group widget from showing widgets in areas that do not support them).

Creating Form Input With AIMMS WebUI

As a WebUI app developer, you can now let your users change or add new input data into your models by means of forms.
Instead of directly manipulating the data in your model, the form will act as a staged commit. The advantage of a staged commit over direct manipulation is that while the information is in the form, before it is applied, you can perform input validation. Only if all the form fields pass validation, the data on the form can be committed back to your model.

Normally, implementing a staged commit with validation support requires a lot of logic to be written by the developer. For example, when you want to call a validation routine or prevent accidental loss of information. This could happen when there are uncommitted changes and the user requests to change the form contents by changing the selection. However, we have put all form logic in the AIMMS WebUI Library, allowing you to create a staged commit form for your end users.

As a WebUI app developer, adding a form to your application requires the following basic steps:

1. Create some model identifiers of which the data will be edited through forms;
2. Create two procedures (a validation and a new entry procedure);
3. Call webui::SetupForm(…); and
4. Create WebUI widgets and connect them to several generated identifiers and procedures.

Often it is easier to explain something by means of an example. Therefore we provide a working demonstration in the AddressBook application.

On the AIMMS model side, you have:
1. A Declaration section, with

2. Two procedures

3. SetupPersonForm – the procedure that sets up the form by calling:

{‘PersonName’, ‘PhoneNumber’, ‘PersonAge’},

4. On the WebUI side, you have:

Please note: when clicking on the ‘Save’ button, this only means that the data which you entered in your WebUI form is transferred to the underlying AIMMS model. It does not mean that your current AIMMS case is saved as well, so please make sure that you also save your AIMMS data before exiting. Otherwise, you’ll lose your forms data.

Downloading Table Data into a .csv File

The Table widget offers you the possibility to download its current contents to a .csv file on your local machine, which you can use to further process your data in, for example, Excel. On the top right, left of the ‘Move’ icon, you can find the download icon. When you click it, the contents of the table, exactly as you configured it (in terms of pivoting, for example), will be downloaded to a .csv file. Depending on your browser, you can specify the name of the file or the download location. As a default, the name of your table will be used as the filename with the ‘.csv’ extension.

If your table contains numerical data, the numbers will be written to the .csv file in their maximum precision. So, if you display only 2 decimals in the table, but the underlying number is for example 1.2345, the full precision is written to the file. This allows you to do calculations in Excel with the resulting file, without running into rounding errors. Furthermore, the value ‘na’ from AIMMS is written as the value ‘#N/A’, which is used in Excel, in order to maximize the compatibility.

Please note that the .csv file is constructed within your browser environment before downloading. This means that the performance might vary over the devices that you are using. You will get a warning if your download will be too big to handle for the WebUI. We have successfully tested up to the scenario of 5000 x 100 rows/columns.

Locking Editors for Certain Users

By default, all users of a published (on the PRO server) WebUI application, can edit this application by changing widgets, options, layout, theme etc. If you want to disallow certain users from editing a published WebUI application, you need to create the “WebUI_Cannot_Change_UI” group at the Users tab in the PRO portal. After that, you can add the users who should be disallowed from editing the application, to that group. This will still allow these users to change data and create/compare cases, but they won’t be able to change the applications UI structure.

Hiding Specific Widgets

There are situations where you may want to hide certain widgets for certain users. Especially if many ‘roles’ can be identified amongst the users of your applications, this may apply: some users shouldn’t be allowed to change some specific data that is displayed through a particular widget.

To help you in situations like this, every widget has an option called ‘Visible’, located on the ‘Miscellaneous’ tab in its option editor. Setting this option to False (or 0) has the effect that the widget is not visible anymore. In order not to lose track of these widgets while developing your WebUI, there is an ‘eye’ icon in the top bar, with which you can still show the hidden widgets. These are displayed in grey, in order to distinguish them easily from the visible widgets. This icon is not visible when running your WebUI app in a PRO environment (i.e. in the end-user scenario), or when you have no widgets that have the Visible option set.

It is not only possible to just specify literal values like True/1 or False/0 for the ‘Visible’ option: you can use any scalar AIMMS parameter that you like. This is especially powerful, since it allows you to steer the visibility of each and every widget using whichever logic you want. As an illustration, you could create an AIMMS parameter like:

if CurrentUserGroup = ‘Finance’ or CurrentUserGroup = ‘Management’ then

to make sure that only finance people and people from the management can see one or more specific widgets.

Please note that if you want to make sure that not all your users can see all available data (e.g. because some of it is confidential), hiding certain widgets is not sufficient. Users can still create new widgets for showing all available data. To avoid this, you need to adapt the set AllPublicIdentifiers, such that it only contains the identifiers that the current user is allowed to see. Furthermore, you need to make sure that users cannot edit the parameter that you specified for the Visible option (e.g. by giving it a definition).

Upload Widget

With the Upload Widget, end-users can upload a file to the AIMMS PRO server, which can then be further processed by the AIMMS model. This is very useful for Web Apps that depend on user specific data that is not yet available on the server (e.g. Excel data input). The Upload Widget has, like the Button Widget, a call ‘Procedure’ option, in which you can specify the AIMMS procedure that will run, once the upload is finished. You can specify this option via the option editor of the upload widget, or assign it to its current contents when creating a new upload widget.

The AIMMS procedure should have three arguments, in the exact order below:

The end-user can add a file to the upload widget by pressing the ‘add’ button. After that, a file can be selected using the standard browser controls for selecting files. Once a file is added, the end-user can start the upload by pressing the ‘start’ button. The Upload Widget will show the progress of the upload. Once the upload is successfully finished, the specified AIMMS procedure is called, which should take care of any further processing of the file.

The location of the uploaded file on the AIMMS PRO server is different from the location when running the AIMMS model in developer mode. In order to be able to always get the correct file path, you can use the webui::GetUploadedFilePath function that is available in the AimmsWebUI library. When running on the AIMMS PRO server, this function adds the temporary pro path to the file name. You can use this function in your AIMMS procedure to be able to further process the uploaded file.

During or after this processing, you should update both the return value parameter and the return message string parameter. A return value of 200 means successful. For reference of possible return value, please look here. Once the AIMMS procedure run has finished, the WebUI will show the return message to the end-user. Depending on the return value, messages are shown as messages (in the message log) or errors. By providing clear messages, you can provide your user with feedback on the uploaded file.

When the uploaded file is no longer needed, you should delete it (e.g. by using FileDelete from within the AIMMS procedure). As an app developer, you know best when the file is no longer needed. Please note that uploaded files at the AIMMS PRO server, will be deleted automatically once the current data session is closed. In developer mode, however, files are not automatically deleted.

Using the Search Boxes

The WebUI offers you a search box in various widgets. For example, there is one in the MultiSelect widget, the table widget and the Scalar widget. This search box is very flexible and offers some nice functionality. In this paragraph, we’ll explain what’s possible.

The simple behavior of the search box is to just enter some text (or numbers). All possible items that contain this text are found and presented in a small list below your search box. Please note: the current maximum number of search results is 100. Should the item that you are looking for not be included in these 100 results, you should refine your search further. In the search box of the dropdown list, the currently selected item is always put on top of the list of search results (even if it doesn’t contain the currently entered search criteria!). This allows you to reselect the original value, and lets you easily remember the currently selected value.

A step further is to use so-called regular expressions in your search terms. Though regular expressions offer a lot of possibilities (a good quickstart is offered here), some of the more useful features are listed below:

A minor downside of offering regular expressions is that some characters are regarded as ‘special characters’. For example, if you want to search for an item that contains the substring ‘|’, simply searching for ‘|’ doesn’t work. In these cases, you need to prefix the character with a backslash. So, in the example here, you should look for ‘\|’.

The searches that you can perform are case-insensitive. So, looking for ‘A’ will return all items that contain either ‘a’ or ‘A’ as a substring.

Return to PRO WebUI Overview