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 upgrades and overrides (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 currently 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
assets/ FILE Binary Assets for the frontend application

Upgrade notes

Overlays do not handle files in the public/ folder. These files are overwritten during an upgrade. However, by using the assets/ folder, two types of files can be overridden by simply adding them into the assets folder: logo & faviocon. If you have changed other files in the public/ folders, these needs to be copied back to the public/ folder after an upgrade.

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."
    }
  }
}

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"
    }
  }
}

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 the contents of the overlay/image/ folder, if present.

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

Restart the application to apply the change.

Update frontend logo or favicon

The frontend of the application will try to fetch both a logo and a favicon from the assets/ folder, but if not present, it will fetch from the public/images/ folder (favicon will use the public/ folder). The application will search for the following file extensions, in the following order:

  • .PNG
  • .JPG
  • .SVG
  • .ICO

This means if two favicons are added to the assets/ folder, called favicon.png and favicon.ico, the favicon.png will be used as favicon. Only files named logo.<file-extension> or favicon.<file-extension> will be included in the search.

Different kinds of logos can also be added to the public/images/ folder where the application will look for logos in the following order:

  • logo.png
  • logo.jpg
  • logo.svg

This means if two logos, called logo.jpg and logo.svg, are present in the public/images/ folder, logo.jpg will be used.

Favicons will try to find different kinds of favicons via the assets/ folder or icons named favicon.ico in the public/ folder.