Theming and the theme switch addon

[Kilian Valkhof]

Our WebUI Example Project contains a custom theme switcher addon. In this post I will explain how to use and augment this, in order to create your own theme.

Custom addons
Custom addons and themes go into the "resources" folder of your Webui, as you can see here: https://github.com/aimms/WebUI-Examples/tree/master/MealsRUsWebAppPRO/src/main/aimms/WebUI/resources with themes going into the css folder, and custom widgets and addons going into the javascript folder. Some HTML, CSS and JavaScript knowledge is required to code your own addons and widgets. If you want to use them in your own project, you should copy them over to your project resources folder.

Custom Themes
The theme switcher works by setting a class on the topmost element of the document, the html element. This class is determined by prefixing the theme name with "theme-". This in effect allows you to namespace your theme, like we did in the example project with our "dark" theme: https://github.com/aimms/WebUI-Examples/blob/master/MealsRUsWebAppPRO/src/main/aimms/WebUI/resources/css/themes/dark/dark.css

To add your own theme, copy the "dark" folder in the themes, rename it (to "yourcompany" for example) and rename the css file in it accordingly (to yourcompany.css). In this CSS you have full control of the webui, but we urge you to stay away from layout changes, as they will interfere with the rest of the WebUI and may lead to problems. Good theming options are (background)colors, fonts, shadows and borders. Make sure that in your theme, you prefix all css selectors with .theme-YourThemeName (for example, .theme-yourcompany)

It's easiest to first add an empty theme css to the theme-switch-addon, and then customise it, as you can see the changes in the WebUI as you go. There is no full documentation on the HTML and CSS structure yet, so we suggest taking dark.css as a starting point and using the web inspector to find out how to target specific elements.

After you have created your own theme css, you will need to augment the theme-switch-addon to make it aware of your new theme. To do so, you need to add a new line in this file: https://github.com/aimms/WebUI-Examples/blob/master/MealsRUsWebAppPRO/src/main/aimms/WebUI/resources/javascript/theme-switch-addon/src/jquery.aimms.theme-switch-addon.js#L17 On line 17 you will find this code:

<option value="dark">Dark theme</option>\

You can copy this line (or overwrite it if you do not want users to choose the dark theme, or you did not copy it over) and change the value="dark" to the name of your css file, and the text inside the <option> to a friendly version. So, in the yourcompany.css example, the value would be "yourcompany", and the friendly name would be "Your Company theme". Leading to this line:

<option value="yourcompany">Your Company Theme</option>\

After reloading (or re-uploading) the application you should now be able to select your own theme in the theme switcher.

Future
In the future we want to improve on theming by introducing support for SCSS and providing an easier way to customise the entire theme.


As always, if you have any questions let us know, and I personally look forward to seeing all the different themes you will develop!

Regards,
Kilian

[Brian Kulp]

Hi Kilian,

How do you bring in different palettes, instead of ColorBrewer 7 and 11? Or if that is not possible, how do you change your default color scheme?

Thanks,

Brian

[Kilian Valkhof]

Hi Brian,

You can't (as of now) add different palettes, but you can overwrite the default colour scheme in your custom theme css, by specifying the classes .Mod19Ord1 throught .Mod19Ord19.

.theme-YourName .Mod19Ord1 {

background:red;
fill:red;
stroke:red;

}

.theme-YourName .Mod19Ord2 {

background:blue;
fill:blue;
stroke:blue;

}

...

.theme-YourName .Mod19Ord18 {

background:orange;
fill:orange;
stroke:orange;

}


.theme-YourName .Mod19Ord19 {

background:red;
fill:red;
stroke:red;

}

Kind regards,
Kilian

[Brian Kulp]

I have put the following code in my css custom theme and the colors on the graphs are the same. Is this how it is supposed to be done?

.theme-dark .Mod19Ord1 {

background:#DA291C;

fill:#DA291C;

stroke:#DA291C;

}

.theme-dark .Mod19Ord2 {

background:#003DA5;

fill:#003DA5;

stroke:#003DA5;

}

.theme-dark .Mod19Ord3 {

background:#8A8D8F;

fill:#8A8D8F;

stroke:#8A8D8F;

}

.theme-dark .Mod19Ord4 {

background:black;

fill:black;

stroke:black;

[Kilian Valkhof]

Hi Brian,

Yes, that should work, provided you use the dark theme, but it could be that the bars have a different classname (the ordinals are determined in aimms). Can you check by right-clicking on a bar and clicking "inspect element"? This will then give you the element highlighted. It should say class="Mod19OrdN" on there. If the right class (1, 2, 3 or 4) is there, then I'd like to set up a skype meeting (or similar) with you and do some troubleshooting together!

Kind regards,
Kilian

Fluxility

[Brian Kulp]

Thank you! I think I figured it out.

[Brian Kulp]

Could I then ask you one more question? When I go to inspect element, I can edit the HTML code and change the titles of the rows and headers. Right now, the WebUI does not allow editing of these names and they default to parameter names. However, when I refresh the page, the changes go away. Is there a way to save these changes?

[Kilian Valkhof]

Hi Brian,

From one of my colleagues: "When you add an entry to the 'awf.properties' file (somewhere underneath the IFA folder) of the form <identifier-name>=<identifier-description> the table will show the description instead of the name from the model. Same holds for other header values." Hope this helps!

Kind regards,

Kilian Valkhof
Fluxility