Some settings can be clearly assigned to a specific theme or brick. Some of these settings might even only make sense in the context of a specific theme or if certain bricks are active. These settings would probably need to be changed if a different theme is chosen, for example, for a sub page. Because of this, settings can now also be declared within the frontend workspace.

To be able to achieve this, every brick and theme package can provide one or multiple settings files placed in the src/settings folder of the package. Settings are JSON files which end with .settings.json:

A typical settings file looks like this:

{
  "sliderMetaData": {
    "cm_responsiveDevices": {
      "mobile": {
        "width": 414,
        "height": 736,
        "order": 1
      },
      "tablet": {
        "width": 768,
        "height": 1024,
        "order": 2
      }
    },
    "cm_preferredWidth": 1280
  },
  "fragmentPreview": {
    "CMPicture": [
      {
        "titleKey": "preview_label_teaser",
        "viewName": "asTeaser"
      }
    ],
    "CMTeasable": [
      {
        "titleKey": "preview_label_default",
        "viewName": "DEFAULT"
      },
      {
        "titleKey": "preview_label_teaser",
        "viewName": "asTeaser"
      }
    ]
  }
}

Supported Property Types for Settings

A settings file will be imported to the content server when a theme is deployed and is stored in a CMSettings document linked to the theme. As the content type uses Structs settings files can declare the following types:

{
  "my-string-property": "Hello World",
  "my-string-list-property": ["Hello", "World"]
}
    

{
  "my-integer-property": 1,
  "my-integer-list-property": [0, 9]
}
    

{
  "my-boolean-property": true,
  "my-boolean-list-property": [true, false, false]
}
    

{
  "my-link-property": {
    "$Link": "../sass/styling.scss"
  },
  "my-link-list-property": [
    {
      "$Link": "../sass/styling.scss"
    },
    {
      "$Link": "../sass/more-styling.scss"
    },
  ]
}
    

{
  "my-date-property": "2018-11-13",
  "my-date-list-property": [
    "2018-11-13 20:20:39",
    "2018-11-13+03:00",
    "2018-11-13 20:20:39-09:00"
  ]
}
    

{
  "my-struct-property": {
    "hello": "world",
    "show": true
  },
  "my-struct-list-property": [
    {
      "nestedStruct": {
        "hello": "world"
      }
    },
    {
      "list": [1, 2, 3]
    }
  ]
}
    

As you can see it is basically plain JSON syntax except for link and date properties (and their list counterparts). You can describe almost everything that can be expressed via JSON with settings files. However, there are the following limitations:

If one of the limitations is neglected the theme build will trigger a warning or an error accordingly.

Merging of Settings

During the theme build the settings files of all packages will be aggregated and merged. Merging is performed on filename base, so all settings files of the same name in different packages are merged into a single settings file with that name. If a setting is declared multiple times, the setting that is declared closer to the root of the theme's dependency tree takes precedence. This is the same mechanism as for SCSS variables and templates.

Properties are always overridden except for struct properties. If a struct property is encountered multiple times, the theme build will merge the structs instead of replacing the former ones entirely. This is a deep merge, so nested structs will also be merged.

Caution

While you can have multiple settings files to structure the settings to your needs you need to make sure that if the same top-level property is used multiple times in different packages it is always declared in the same settings file.

Let's assume the example for Preview.settings.json at the beginning of the chapter is declared in the preview brick. In case you want to override the fragmentPreview and sliderMetaData in a brick or theme that depends on the preview brick you need to create a Preview.settings.json file in the src/settings folder of your theme.

Settings Lookup

Settings can be looked up in FreeMarker Templates using the bp.setting method of the Section 6.5.3, “Blueprint (bp)”. The lookup mechanism for the given key will first check the given self, then the context (for example, the cmpage) and finally the theme. This implies that a theme setting has the least precedence of all settings definitions and will only be taken into account if it is not overridden somewhere along the lookup chain.

If you want to use theme settings in other backend modules (for example, content beans) via the com.coremedia.blueprint.base.settings.SettingsService you need to make sure that the theme is actually taken into account when providing beans for the lookup. Please check the com.coremedia.blueprint.cae.web.taglib.BlueprintFreemarkerFacade to find code examples on how to achieve this.