Styling

In order to get started you need a place to put all your LESS code. The recommendation is to create one LESS file for each widget. That means if your widget is called MyWidget.js you would create a file called MyWidget.less. Even if you adjust the look of an existing widget you can create a file called let’s say StringField.less and put the rules there. If you only have a few rules or non widget specific rules you can create a file called main.less and put them there. However, these are only recommendations, you can always do it as you like.

The creation of these files won’t make them load automatically. You have to register them in your index file. This file should be put into your src/main/js folder and named index.less. Just include your new files using the LESS @import keyword.

In addition to this index file you normally also have a theme file which will be used as entry point in your webpack.config.js and included in the index.html. The intention of the theme file is to group individual index files and make one file in order to load all rules at once within one request.

Now that we have all the infrastructure set up, we can start adding some rules. As already said, you can use all the LESS variables from Scout. The variables can be found in the scout/style folder of the @eclipse-scout/core module. If you have a look at the file colors.less you find all the colors you can use or customize. Let’s say you want to change the background color of the header, you can redefine the variable @desktop-header-background-color.

That’s it! As you can see, changing this variable not only changes the background color of the header, it also changes the background color of the view-buttons on the top left, because they are supposed to have the same color. You could do the same by using CSS rules, but you would have to write several selectors to achieve the same.

In this example a color from the Scout color palette is used. You can also use a custom hex code instead of @palette-red-4 or define a custom color palette, if you want to use the same colors for different rules.

Beside colors there are some other files in the style folder of the Scout module: animations.less, fonts.less, icons.less, mixins.less and sizes.less. All these files contain variables or mixins which are used by various Scout widgets and may be used by your project as well.

Redefining a LESS variable is the simplest way of customizing. If you need more control you can always write a custom CSS rule. Keep in mind that these rules need to be more specific than the default CSS rules of Scout, otherwise they won’t be executed (see https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity for details). We cannot guarantee that your custom rules will still work when migrating to a newer Scout version, because changing only a small part of the rule might make it more specific so that your rule won’t work anymore. That only applies to custom rules which are supposed to change existing look or behavior. If you are writing a custom widget without overriding default Scout rules there shouldn’t be any problems regarding migration.

Scout applications support styling via CSS/LESS themes. Scout comes with two themes by default: the default theme with blue colors and the dark theme with gray/black colors. Technically a theme has a name and a set of LESS files.

In Scout Classic a theme is activated by calling the method AbstractDesktop#setTheme(String name). This causes the browser to reload the page and loads the CSS theme for that name, like myapp-theme.css for the default theme or myapp-theme-dark.css for the dark theme. The default theme is activated by passing a null value as name.

In Scout JS you do the same thing by calling the method Desktop#setTheme(name).

If you have multiple themes and you want to start with a defined theme by default, you can set a property in the config.properties file on the Scout UI server. In the following example the theme rainbow will be activated, which means the Scout application tries to load the CSS file myapp-theme-rainbow.css on start-up:

Note that Scout only provides an API to switch between themes. If the user of your Scout application should switch between various themes, your application must provide an UI element to do that. Scout provides no standard UI element for that. However, the Widgets apps for Scout Classic and Scout JS give you an idea of how you could implement that feature.

You have two options to customize CSS styles in your Scout project:

If your Scout application should have only a single theme, option 1 is the way to go. If users should have the option to switch between various themes, you should go with option 2. In this chapter we will focus on the latter option.

In order to understand Scout themes, take a look at the myapp-theme.less file which has been generated for your project by the Scout archetype. In the following examples we assume that the name of your project is myapp.

As you can see the theme bundles various LESS modules. Line 1 imports the LESS module from the Scout core. This module contains style definitions for all UI elements provided by Scout. Line 2 imports the LESS module from your application. This module contains style definitions for custom widgets used in your project. The build creates a single CSS file myapp-theme.css, which is used as theme for your project.

We recommend making an index file for each Scout module. These index files import each single LESS file which belongs to that module. This excerpt from Scouts index.less shows how we import all distinct LESS files required to style the desktop or the LESS variable definitions for all colors used in the stylesheet:

How does the dark theme for your Scout application look like? Like for the default theme, we create a LESS file myapp-theme-dark.less, but this time we import the index-dark modules.

Let’s take a look at the details in the index-dark.less file from the Scout core:

As you see, the first thing we do on line 1 is to import the default theme 'index'. This means the dark theme inherits all style definitions from the default theme. The dark theme only extends new additional style and LESS variables or overrides styles or LESS variables from the default theme. This is what happens on line 2: colors-dark.less overrides some variables defined in the colors.less file from the default theme, like the gray colors:

Note that all variables except @palette-gray-2-1 override variables from colors.less. @palette-gray-2-1 is a variable which is only defined and used in the dark theme.