4 Strategies to apply custom CSS at runtime on OutSystems Reactive Applications

OutSystems allows you to customize your applications in several ways at design time. However, there's no built-in solution regarding runtime customization. 

Back in 2020, when we started developing this feature for a client, we did some research to check if any existing component allowed us to fully customize a Reactive Application's look and feel. But we only found information on the approach to do it on Traditional web Apps through the 'AddStyleSheetTag'—not applicable in Reactive.

The lack of existing options and the specific requirements stating that the client wanted "not only to be able to change the application's colors but to have the possibility to also change some of the main elements through custom CSS" left us with a substantial challenge in hand.

Applying Custom CSS at runtime

Allowing apps to apply custom CSS at runtime is beneficial, and this article will explore four strategies to tackle this successfully:

1. Add custom CSS at runtime through a script;

2. Store the  CSS on a client variable;

3. Import the custom CSS file in the backend;

4. Create a forge component.

#1 — Add custom CSS at runtime through a script

The following script appends a text variable to the head of the page within a style tag. This tag will then overwrite the existing CSS stylesheet.

1. First, find the ‘head’ element of the page:

   • var head = document.getElementsByTagName(‘head’)[0];
     

2. Create a style tag and append it to the head element at the end:

   • var style = document.createElement(‘style’);

   • style.type = ‘text/css’ OR style.setAttribute(‘type’,’text/css’);
     

3. Add the custom CSS to this style tag:

   • style.appendChild(document.createTextNode(css));
     

4. Finally, append the custom CSS to the created style tag at the head of the page:

   • head.appendChild(style);

The script should look like this:

Picture 1 – Script Snippet

By running this script inside the initialize event, the changes to the CSS are done before the rendering of the screen is done. Consequently, only one render has to occur to display the custom changes to the CSS. Having the CSS replaced before the first render of the screen means the user will not see any changes happening after loading the screen. For further reference, check the OutSystems Screen Event Lifecycle.

#2 — Store the CSS on a client variable

OutSystems reactive applications let you store information on client variables. Thus, this second approach stores the custom CSS as a client variable during runtime. This method avoids delays while waiting for the CSS file to be fetched every time a screen is loaded. However, for every change to the CSS, the variable must be updated, and the JS script rerun to apply the new changes. 

A practical way to ensure the custom CSS is always present and up to date and guarantee the script runs is to execute this flow inside a block shared across all the application's screens—like a shared menu block.

Picture 2 – Flows Snippet

On the On Ready event handler of the block, the CSS client variable is checked, and then the JS script is run. This ensures the CSS will always be saved locally. If the CSS already exists, the script can be executed directly on the OnInitialize of the block. 

With the logic present on both the OnReady and OnInitialize event handlers, the script runs either after fetching the data on the OnReady handler or directly on the OnInitialize event handler using the existing data on the client variable. Consequently, saving a server call and further delays on the page load after the first load.

This solution allows different application themes to be configured for different tenants, users, or user configurations.

#3 — Import the custom CSS file in the backend

This solution allows the end user to customize the look and feel of the applications. We will skip the explanation behind this solution's architecture (modules and entities) and focus on the process itself.

With the proper permissions, users can upload as many CSS files as they want. These CSS files will be stored as TEXT in an entity. When rendering the screens using this feature, we have a flow where a CSS stylesheet can be loaded based on parameters. 

The stored CSS does not have to replace the theme altogether. Instead, this solution can be used to make explicit changes to certain areas and elements of the application by loading just the necessary CSS, resulting in less overlap with the existing theme.

#4 — Create a forge component

In the end, we created an OutSystems forge component implementing this functionality that the community could use.

Be our guest and give it a try. The component is called Runtime Theme CSS Customize REACT, and you can download it in the OutSystems Community.

---

We hope this article was helpful. Come back soon for more tips.