Customizing Page Content

Sometimes you need to change more than just styling, images or fonts. Cadenza has a few dedicated places where the contents of a page or a block in the UI can be replaced with your own. This chapter describes how to configure this system and how to make sure your custom content is served to the user.

Configuration

Set a system property or an environment variable named CADENZA_THEMES_PATH (see Environment Variables, System Properties and Other Runtime Configuration Options) that points to a folder with your themes. Your custom content templates are resolved from a templates folder within a theme folder.

Example:

To override for example the footer of the default theme of your German Cadenza installation, you may provide a custom footer_de.html file:

<CADENZA_THEMES_PATH>/default/templates/footer_de.html

If you do not provide a custom template, the internal Cadenza default is used.

Writing Custom Content

Custom content templates define HTML fragments and may use certain Cadenza functions and variables (see Functions and Variables for Use in Custom Content).

Language-specific template files must include their language in the filename, e.g. footer_de.html or footer_en.html. This is not necessary for language-independent templates. For example, if the contents of the "libs" template (see below) are language-independent, just libs.html is fine as the file name.

The following sections describe the templates that are available for customization. Most of them depend on your product or your CI and are empty by default. Only for some templates, the documentation includes sample contents.

Template: 404

File name: 404_<locale>.html (for example 404_de.html)

The content of the 404 ("Not found") page.

English default contents:
<div class="d-alert d-alert-warning" style="max-width: 60em">
  <p class="title">The page is not available.</p>
  <p>Sorry, this page cannot be displayed. It may not exist or you may not have sufficient privileges for this page.</p>
</div>

Template: accessAside

File name: accessAside_<locale>.html (for example accessAside_en.html)

Content that is shown aside the login and the password change forms.

English default contents:
{% include './logo.html' %}

Template: appIcon

File name: appIcon_<locale>.html (for example appIcon_en.html)

The app icon definitions for Cadenza being hosted as a Progressive Web App.

English default contents:
<meta name="apple-mobile-web-app-title" content="{{ i18n('productName') }}"/>
<meta name="application-name" content="{{ i18n('productName') }}"/>
<!-- Black-translucent does not work correctly, so either black or default -->
<meta name="apple-mobile-web-app-status-bar-style" content="black"/>

<link rel="shortcut icon" type="image/x-icon" href="{{ themeUrl('/images/favicon.ico') }}"/>

<link rel="icon" sizes="192x192" href="{{ themeUrl('/images/app-icon-192x192.png') }}"/>
<link rel="icon" sizes="512x512" href="{{ themeUrl('/images/app-icon-512x512.png') }}"/>

<link rel="apple-touch-icon" sizes="120x120" href="{{ themeUrl('/images/app-icon-120x120.png') }}"/>
<link rel="apple-touch-icon" sizes="152x152" href="{{ themeUrl('/images/app-icon-152x152.png') }}"/>
<link rel="apple-touch-icon" sizes="167x167" href="{{ themeUrl('/images/app-icon-167x167.png') }}"/>
<link rel="apple-touch-icon" sizes="180x180" href="{{ themeUrl('/images/app-icon-180x180.png') }}"/>

Template: banner

File name: banner_<locale>.html (for example banner_en.html)

A banner that is displayed above the main header on almost every page.

Template: embeddingStandby

File name: embeddingStandby_<locale>.html (for example embeddingStandby_en.html)

Content of Cadenza’s standby page, which is shown if the session of Cadenza content that is embedded in a custom application or portal timed out.

English default contents:
<link rel="stylesheet" href="{{ themeUrl('/css/embeddingStandby.css') }}">

<h1 class="embedding-standby-heading">Standby Page</h1>
<p class="embedding-standby-description">Please click the "Reload" button to trigger reloading the page.</p>
<button class="button button-primary" onclick="Disy.postEvent('reload')">Reload</button>

Template: footer

File name: footer_<locale>.html (for example footer_en.html)

The footer that is shown on almost every page.

English default contents:
<link rel="stylesheet" href="{{ themeUrl('/css/footer.css') }}" />

<div class="userSpecificFooter dark-bg d-stack-h space-2">
  <div class="userSpecificFooterLeftPositioned">
    <a href="{{ i18n('productLink') }}" target="_blank" class="userSpecificLink ellipsis hidden-xs">
      {{ i18n('productName') }} {{ cadenzaVersion }}
    </a>
  </div>
  <div class="userSpecificFooterMiddlePositioned">
    <a href="https://www.disy.net" target="_blank" class="userSpecificLink ellipsis hidden-xs">
      © Disy Informationssysteme GmbH
    </a>
  </div>
  <div class="userSpecificFooterRightPositioned">
    <a href="https://www.disy.net/en/imprint/" target="_blank" class="userSpecificLink ellipsis">
      About Disy
    </a>
  </div>
</div>

Template: helpHeader

File name: helpHeader_<locale>.html (for example helpHeader_en.html)

The header that is shown at the top of help pages (see Customizing Help Topics).

English default contents:
<h1 class="help-topic--heading">{{ i18n('productName') }} – Help</h1>

Template: helpMenuBottomContent

File name: helpMenuBottomContent_<locale>.html (for example helpMenuBottomContent_en.html)

The content that is show at the bottom of the help menu.

English default contents:
<link rel="stylesheet" href="{{ themeUrl('/css/helpMenuBottomContent.css') }}">

<hr />
<div class="helpMenuBottomContent">
  <h2>{{ i18n('helpMenu.license.versionInfo') }}</h2>
  <dl class="helpMenuLicenseInfo">
    <dt>{{ i18n('helpMenu.license.version') }}</dt>
    <dd>{{ cadenzaVersion }}</dd>

    <dt>{{ i18n('helpMenu.license.owner') }}</dt>
    <dd>{{ cadenzaLicense.customer }}</dd>

    <dt>{{ i18n('helpMenu.license.expireDate') }}</dt>
    <dd>{{ cadenzaLicense.expireDate }}</dd>

    <dt>{{ i18n('helpMenu.license.licenseType') }}</dt>
    <dd>{{ cadenzaLicense.type }}</dd>
  </dl>
</div>

Template: libs

File name: libs_<locale>.html (for example libs_en.html)

Possibility to include additional JavaScript libraries into the page for use in custom content.

Template: loginBanner

File name: loginBanner_<locale>.html (for example loginBanner_en.html)

A banner that is shown on top of the login page.

Template: loginFormHeader

File name: loginFormHeader_<locale>.html (for example loginFormHeader_en.html)

Content that is shown at the top of the login form.

English default contents:
<h1 class="d-login-heading">Login</h1>

Template: loginFormFooter

File name: loginFormFooter_<locale>.html (for example loginFormFooter_en.html)

Content that is shown at the bottom of the login form.

Template: mainHeaderLeft

File name: mainHeaderLeft_<locale>.html (for example mainHeaderLeft_en.html)

Content that is shown at the far left of the main header (to the left of the home button).

Template: mainHeaderMiddleLeft

File name: mainHeaderMiddleLeft_<locale>.html (for example mainHeaderMiddleLeft_en.html)

Content that is shown at the middle left of the main header (to the right of the home button).

English default contents:
<h1 class="d-topnav--branding-text" data-testid="app-name">{{ i18n('productName') }}</h1>

Because of responsive design (the way that Cadenza adapts to small screen sizes), the middle left section is the only one that is guaranteed to be shown. It is recommended to keep the application links in the mainHeaderMiddleLeft template (see the customMenu tag in Published Template Functions).

Template: mainHeaderMiddleRight

File name: mainHeaderMiddleRight_<locale>.html (for example mainHeaderMiddleRight_en.html)

Content that is shown at the middle right of the main header (to the left of the user and help menus).

Template: mainHeaderRight

File name: mainHeaderRight_<locale>.html (for example mainHeaderRight_en.html)

Content that is shown at the far right of the main header (to the right of the user and help menus).

Template: welcome

File name: welcome_<locale>.html (for example welcome_en.html)

Content of Cadenza’s welcome page.

English default contents:
{% include './logo.html' %}

Functions and Variables for Use in Custom Content

When customizing Cadenza you can replace certain fragments of pages with your own HTML content. In addition to being able to use all the various features that the web platform offers you, we also have a few specialized functions and variables that you can include in your content.

The functions and variables can only be used inside templates, and they are evaluated on the server.

Published Template Functions

This is a list of officially published and maintained functions that are usable for customization.

cadenzaUrl
Parameter Type Description

url

String

A URL relative to the Cadenza context path

Makes the given relative URL absolute to the Cadenza server.

Example usage:

<a href="{{ cadenzaUrl('/') }}">Home</a>
getProperty
Parameter Type Description

name

String

The name of the system property or environment variable you want to resolve.

This function allows resolution of a system property or an environment variable by providing its name. If both exist, the system property will win.

If the property can not be found the empty string is returned.

Example usage:

Value of the 'user.language' property: {{ getProperty('user.language') }}
i18n
Parameter Type Description

key

String

The key of the custom message

This function allows using the custom messages in custom templates.

Example usage:

Message with the 'productName' key: {{ i18n('productName') }}
themeUrl
Parameter Type Description

path

String

The path of a theme asset relative to the theme path, e.g. '/images/logo.png'

This function returns the absolute URL path of a theme asset.

Example usage:

<img src="{{ themeUrl('/images/logo.png') }}" alt="Logo" />
include

The include tag allows you to include another template into the current one. The included template has access to the same variables as the current one.

Example usage:

{% include './another-template.html' %}

Published Template Variables

This is a list of officially published and maintained variables that are usable for customization.

cadenzaLicense

Metadata of the Cadenza license

Property Type Description

customer

String

The license customer

expireDate

String

The formatted expiration date of the license

type

String

The type of the license (standard or demo, internationalized)
cadenzaVersion

The Cadenza version as a String

currentUsername

The name of the currently logged-in user or an empty string if there is none

Message Key Usage in Custom Page Content

You can reference every custom message property (see also Customizing Message Properties) in custom content by using the i18n function (see also Published Template Functions).

Example:
<span>{{ i18n('productName') }} - Software made in Germany. Contact us at {{ i18n('contactText') }}</span>