Theming

With CSS Styling you can style your WebUI app any way you like. This flexibility does have a drawback though: it (obviously) requires CSS knowledge and you have to know quite some details about the DOM-tree that AIMMS is using for displaying WebUI apps, in order to target specific parts of the WebUI for styling. With theming we offer you a different way of styling your app. It requires less detailed knowledge than regular CSS styling, while still offering a way to make your apps look the way you want in most cases. Should you still require some additional tweaking after theming your app, you can just use the regular CSS styling side-by-side with it.

How To Use Theming

Setting up WebUI theming is quite straightforward. It requires just one .css file in the

MainProject/WebUI/resources/css/

subfolder of your AIMMS project. You can name this CSS file as you like. It should contain a series of themable properties, which you can assign your own values. These properties are listed in logical groups in the base-theme-<AIMMS version>.css file, which you can use as a base for your work. It is located in a subfolder of the AIMMS installation folder:

C:\Users\<your name>\AppData\Local\AIMMS\IFA\Aimms\<your AIMMS version>\WebUIDev\www\resources\css

Each group and property is commented, to give you an idea for which part of the WebUI you can influence the appearance by changing its value.

On side-note: a pretty large section of that file is aimed at providing a Data Color palette for widgets that can show annotated data, like Charts. If you’re interested in exploring your options there, please read Data Coloring and Palettes too.

The values assigned in this base file are the values that are used by default in the WebUI AIMMS theme. Please note that in your own .css file, you do not have to specify properties from the base file which you do not want to change. This will make sure that you will benefit from the effect of potential future updates to the default values in the base file and that your own file shows your clean changes only.

Since AIMMS 4.95 the amount of themable properties has grown significantly to further enlarge the number of areas the theming applies to. Many of these new but also existing properties have been re-applied throughout WebUI so practically all aspects of Widgets and the application can be coherently influenced from as few properties as possible.

While the base theming file and its (brief) comments are always up-to-date for each release, we also keep some longer documentation about the css properties, which should help you with Understanding Theming.

An Example

As an example of the usage of theming, suppose that you would like to change the background color of your WebUI app and the coloring of the buttons. In the default AIMMS theming, part of an app could look like this:

../_images/Theming-buttons-1.jpg

To accomplish the change, you should create a file (let’s call it yellow_theme.css) in the subfolder mentioned above. In the file, it requires just these lines:

:root {
/* Global app properties */
--color_bg_app-canvas: yellow;

/* Button properties */
--color_text_button_primary: #0768a9;
--color_bg_button_primary: #ffcc00;
}

to change the appearance of the app fragment into this:

../_images/Theming-buttons-2.jpg

As you see, it is a matter of selecting the right properties for your theming wishes and assigning them the right values to get the effect that you are after. For these values, you are not restricted to ‘simple’ values, like the color names/numbers above. It is perfectly possible to use, for example, the CSS-function linear-gradient(). This .css file:

:root {
/* Global app properties */
--color_bg_app-canvas: linear-gradient(
    to bottom right,
    #ffffff 0%,
    #ffcc00,
    #0768a9 100%
);

/* Button properties */
--color_text_button_primary: #0768a9;
--color_bg_button_primary: #ffcc00;
}

will result in the following WebUI theme:

../_images/Theming-gradient.jpg

Obviously, using a function like linear-gradient(), it needs to make sense. That means that it can only be applied to background coloring options, but not to, say, text coloring options.

Note

Although the base theme file contains an explanation that suggests that all properties prefixed with color_bg or bg_ will be purely applied to real backgrounds (allowing for URLs and gradients), there are a few exceptions where only a (straightforward) color values will work to theme some elements with these properties. We have not managed to iron these out yet. Using color values only is currently the safest. Contact us if you run into areas that behave unexpectedly and always keep Chrome’s DevTools at hand to check where and how theming is being applied.

For borders, for example, by adding a specific border value like this:

--border_button_primary: 4px dotted blue;

the example above will change into the following:

../_images/Theming-border-dots.jpg

Obviously it is a matter of taste whether you deem these last two examples beautiful, but it does illustrate that with changing just a handful of theming property settings, you can achieve far-reaching effects.

Value Inheritance

Since WebUI theming is based on CSS, it is also possible to use inheritance of property values using CSS’s var function. For example, if you want to color the background of the widget headers the same as the default text, you can write:

--color_bg_widget-header: var(--color_text_default);

Next to this kind of inheritance, it is also possible to ‘inherit’ from the standard AIMMS color palette. In the same folder as the base theme example file, in the global-custom-prop-constants.css file, these colors are listed for your reference. So, for example:

--color_bg_widget-header: var(--COLOR_AIMMS-YELLOW-DARK);

Would display the background of your widget headers in the standard AIMMS dark yellow color.

If you look at the base theming file, you will notice that the base definitions use inheritance for quite a few properties too. It allows similar color types to be adjusted from a single property, but if needed the properties can still be changed separately.

Moving From Custom CSS/Theming

Many clients have their apps styled using custom CSS. We advise you to move to the new AIMMS Theming, since it offers better maintainability and probably also backward compatibility in the future. The best way to migrate is to put aside all your existing custom CSS files by moving them somewhere outside your project folder, to keep as backup. From this ‘clean’ state, start theming your app as explained above. If, after that, you are not fully satisfied with the result, you can re-visit your previous custom CSS to see whether selected parts of it can be re-used to fill the gap.

Also, it needs to be emphasized that you can combine custom CSS constructs with theming because it is CSS after all. And with your ‘custom css knowledge’ you can also come up with constructions that change theming only locally.

For example, instead of putting all definitions on the :root{...} element, like we do by default, you can also target a single widget, or type, or any context using well-known selectors:

[data-widget\.uri=my_special_table] {
    --color_text_edit-select-link: #9400d3;
    --color_bg_widget-canvas: #ffb6c1;
}

Or, on all pages with ‘red_page’ in the page name, you could just have different colored primary buttons:

[data-widget\.uri*=red_page] {
    --color_bg_button_primary: Red;
    --color_text_button_primary: White;
    --border_button_primary: 1px solid Yellow;
    --color_bg_button_primary_hover: DarkRed;
    --color_text_button_primary_hover: Yellow;
    --border_button_primary_hover: 2px solid White;
    --color_bg_button_primary_active: DarkGoldenRod;
    --color_text_button_primary_active: White;
    --border_button_primary_active: 1px solid White;
}

Be warned, that if you intend to target anything other than :root, and when using a url(...) for one of the several --color_bg... properties, and when publishing to the cloud, you will not be able to use images in the project resource folder. The special treatment we apply to those URLs in the cloud, can only be done for the root element.

You can still use resources like that, but you will have to manually insert and maintain the Application name and version number into the resource path and it will then also only work after publishing. There is, unfortunately, no other way for us to predict where you might have been applying theming to specific elements.