Configuration using a custom overlay folder

Background

Configuration files found in the "resources" folder are overwritten by new installs and upgrades. By creating the same structure in a folder called "overlay", the upgrade process is simplified significantly. The "overlay" folder remains untouched by any a upgrade and override (overlays) the files in the "resource" folder. The "overlay" folder is automatically created at installation but the content is never changed. Using the overlay folder is totally optional and can be introduced gradually by adding files only when needed.

Overlay strategies

The files in the "resource" folder are of several different types and depending on type the overlay strategies will be different.

Two strategies are available:

MERGE:  This strategy is used for files with simple properties, the properties in the overlay file will be merged with the properties in the resource file. The overlay properties has priority and will override the properties in the final content. Only the changed properties needs to be included in the overlay files.

FILE: This strategy is used for files that are binary or when the contents is to complex to make a merge. The files in the overlay folder are used instead of the files in the resource folder.

Folder overview

Overlay sub folder Strategy Content type Usage
bundles/ MERGE Java bundle properties Mail notifications, PDF messages.
images/ FILE Binary Images in mail notifications
lang/ MERGE JSON properties UI language translations
settings/ MERGE JSON properties UI theme and other settings
templates/ FILE Handlebars Mustache templates for mail notifications

Upgrade notes

Files in the "public" folder are not handled by overlays. Files in the public folders needs to copied back to the public folder after an upgrade, e.g. logo.png and favicon.ico

Examples

Styling in general

Detailed information for styling can be found in the chapter Configuration - Styling. Here are some simple examples of how to make changes with overlays.

Change the information text in the dashboard cards

Current text for this example

Change to

The text for the UI is located in the resources/lang/sv/strings.json file. Follow these steps.

  1. Open the file resources/lang/sv/strings.json
  2. Locate the old string, note the position in the json structure
  3. Create a new file named overlay/lang/sv/strings.json
  4. Add the attributes including the "dashboard" and "completed" attributes to the new file
  5. Change the "description" to the desired text.
  6. Refresh the web browser, this change will take effect immediately.

The overlay file should look something like this:

{  
  "dashboard": {
    "completed": {
      "description": "Underskrifter som är slutförda. Dokumentet kan nu laddas ner."
    }
  }
}
Click to copy

Note that the full structure of the json file needs to be included in the overlay file.

Change the primary color and header font size

Current colors and font in this example:

Change the color and the header font size to:

The settings for the color and typography are located in the file resources/settings/theme.json. Follow these steps:

  1. Open the file resources/settings/theme.json
  2. Locate the "palette" and "typography" attributes.
  3. Create a new file named overlay/settings/theme.json
  4. Copy/add the relevant part of "palette" and "typography" to the new overlay file.
  5. Change the colors and font size
  6. Refresh the web browser, this change will take effect immediately.

The overlay file should look something like this:

{
  "palette": {
    "primary": {
      "main": "#5F2F8A"
    }
  },
  "typography": {
    "h1": {
      "fontSize": "32px"
    }
  }
}
Click to copy

Note that the full structure of the json file needs to be included in the overlay file.

Change the logotype image that is sent in mail notifications

The logo image that is included in the mail notifications is stored in the resource/image folder. As this folder is handled via the "FILE" strategy the file will be replaced by an other file from the overlay/image folder.

Simply create the folder overlay/images and copy a new logo.png to the folder.

Restart the application to apply the change.