LSPS documentation logo
LSPS Documentation
Customizing a Theme

When customizing the theme of the Application User Interface, use the exposed variables of the themes if possible.

If further customization is required, create your own theme. Consider setting up the sass compiler to be able to preview your changes instantly in the browser.

Creating a Custom Theme

While you can create a new theme from scratch, it is recommended to extend an existing theme. To create a custom theme for your application based on an existing theme, proceed as follows:

  1. In workspace with the sources of your Application User Interface, create the theme resource:
    1. Open <YOUR_APP>-vaadin-war/src/main/webapp/VAADIN/themes with default themes.
    2. Create a copy of a directory with a theme (lsps-valo, lsps-dark or lsps-blue).
    3. Rename the directory to the theme name.
    4. In <YOUR_THEME>/styles.scss, change the theme class name to your theme name: Make sure the directory name and the theme name are identical.
      /*
      changed .lsps-valo to .my-theme
      */
      .my-theme {
        @include addons;
        @include lsps-valo-base;
        @include theme-app;
      }
      
  2. In <YOUR_APP>-vaadin/src/main/java/org/eko/processapp/core/AppUIProvider.java, override the getThemeManager() method so it uses the ThemeManager constructor with all the themes.

    @Override
      protected ThemeManager getThemeManager() {
        ImmutableSet<String> themes =
                  ImmutableSet.of("lsps-dark", "lsps-valo", "lsps-blue", "my-theme");
        //my-theme passed as default:
        return new ThemeManager("my-theme", themes);
      }
    

    The default themes have a style.scss file that imports the relevant scss files. It is the included scss files you need to change. If possible, introduce your changes to the sass/_variables.scss file before you create or modifying other scss files.

    Make sure none of your custom classes clash with system classes (Vaadin and GWT classes).

  3. Consider setting up the Sass compiler so you can preview changes to your theme without rebuilding the entire application: Once set up, you simply introduce your change to the scss files and run the saas compiler with its run configuration from PDS.

Important: Make sure that the name of the directory with your theme and the style class defined in its style.scss file have the same value.

Modifying a Theme

It is recommended to modify your theme primarily using the exposed variables in the <YOUR_THEME>/sass/_variables.scss file.

Example _variables.scss

$v-background-color: hsl(100, 100%, 100%);
$valo-menu-background-color: #FFFFFF;
/* logo path is relative to theme root */
$l-application-logo: url('img/logo.png');

If you need to add an scss rule, do the following:

  1. Create an scss file in the sass directory of your theme, for example, _textarea.scss.
  2. Create the rule in the file as a mixin.
    @mixin _textarea {
      .v-textarea {
        width: 100% !important;
        min-width: 100px;
      }
    }
    
  3. Import the file and rule in the theme's styles.scss:
       
    ...
    @import "../../../VAADIN/themes/wtpdfviewer/wtpdfviewer.scss";
    @import "sass/_textarea.scss";
     
    .my-theme {
      @include addons;
      @include lsps-valo-base;
      @include theme-app;
      @include _textarea;
    }
    -------->8
    
  4. Recompile the theme with the SassCompiler.
  5. Open and refresh the browser with the application. Make sure the correct theme is used: check the selected theme on the Settings page of the application.

Compiling a Modified Theme

If you want to preview the changes in LSPS Application often without recompiling other themes, do the following:

  1. Set the Application User Interface to run in debug mode: set the productionMode parameter in <YOUR_APP>-vaadin-war/src/main/webapp/WEB-INF/web.xml to false.
  2. Set up a Sass compiler configuration that will run mvn exec:java -Dexec.mainClass="com.vaadin.sass.SassCompiler" -Dexec.args="<INPUT_SCSS> <OUTPUT_CSS>":

    1. Go to Run > Run Configuration.
    2. In the left pane, select Java Application and click the New button in the caption area of the pane.
    3. On the right, define the following:
      1. Name: a name of the configuration
      2. Project: <YOUR_APP>-vaadin-war
      3. Main class: com.vaadin.sass.SassCompiler
        sasscompilerconfig.png
        Run configuration for Sass compiler
    4. Switch to the Arguments tab and define the input scss file and output css file as input Program arguments: the output css file must be located in the theme directory of the target directory and have the name styles.css.

    The main scss is the style.sccs file with the relevant scss-files imports so the arguments are defined as follows:

    src/main/webapp/VAADIN/themes/<THEME_NAME>/styles.scss
    src/main/webapp/VAADIN/themes/<THEME_NAME>/styles.css
  3. Test the configuration:
    1. Create an scss file and import it in the theme's styles.scss.
    2. Introduce your changes to the scss file and see them applied:
    3. Run the Saas compiler configuration.
    4. Open and refresh the browser with the application. Make sure the correct theme is used: check the selected theme on the Settings page of the application.

Important: In Google Chrome, make sure to have the Chrome DevTools displayed (press the F12 key) and caching is disabled (go to the Network tab and select Disable cache)

Modifying General Theme Settings

The application default style is based on Vaadin's Valo and extends this theme: The theme's Settings are exposed in the src/main/webapp/VAADIN/themes/<THEME_NAME>/sass/_variables.scss file of the *<YOUR_APP>-vaadin-war* project. Therefore if you want to change only the general theme properties, do so in the _variables.scss file:

The application themes are located in the src/main/webapp/VAADIN/themes/ directory.

Setting the Default Theme

To set the default theme for your application, open the AppUIProvider class in the *<YOUR_APP>.core* package of the <YOUR_APP>-vaadin project and override the getThemeManager() method so it returns a ThemeManager with the theme.

  @Override
  protected ThemeManager getThemeManager() {
    ImmutableSet<String> themes = ImmutableSet.of("lsps-dark", "lsps-valo", "my-theme");
    return new ThemeManager("my-theme");
  }