Documentation:Theme as data

Theme as data

This page was created by Hans.karlsen on 2020-06-24. Last edited by Wikiadmin on 2026-07-29.

You can store and select MDriven Turnkey theme CSS in your model data when you want the application's overall appearance to change at runtime.

What theme as data does

Theme as data lets MDriven Turnkey read CSS from an object in your application rather than only from a CSS file on the server. This makes the selected theme part of the application's data, so you can maintain multiple themes and change which one is active while the application runs.

Use this feature for application-wide values such as colors, typography sizes, navigation-bar appearance, and action-button colors. For example, an administrator can select a compact theme with a smaller base font size and shorter data-table rows, or select a theme with a different primary color.

For the supported Turnkey CSS variables and file-based theming, see Documentation:MDriven Turnkey theming. For styling that communicates information in individual controls or rows, use Documentation:StylesInModel instead.

Required model contract

Turnkey discovers the active theme through this exact path:

SysSingleton.oclsingleton.PickedThemeData

The object returned by PickedThemeData must provide these attributes:

Attribute	Type	Purpose
`Name`	`string`	Identifies the theme, for example `Compact blue`.
`DerivedCSS`	`string`	Contains the CSS that Turnkey applies for the picked theme.

The path is case-sensitive in practice because it is the discovery convention Turnkey uses. If PickedThemeData does not return an object with both attributes, Turnkey cannot use that object as the active data theme.

Create a theme in the model

The Theme Builder model section provides an example model structure and a UI for editing theme variables.

In MDriven Designer, start with your model or open the model to which you want to add theming.
Select Help and open the example models page.
Download the Theme Builder model section.
Use Open Merge and select Add Modeler to merge the downloaded model section into the current model. Merging adds the section; it does not replace your existing model.
Inspect the added diagram, theme-data type, and ViewModel. The example supplies a UI in which you can add a theme, give it a name, and edit its theme values.
Run the Turnkey prototype and create a theme, for example Compact blue.
Ensure that the application's SysSingleton.oclsingleton.PickedThemeData resolves to the theme the user selected.

The Theme Builder UI exposes common global styling values as data. Enabling a value makes it part of the generated CSS. For example, setting the base background color affects the application background; setting the navigation-bar background color affects the header; setting save and cancel action colors changes those action buttons.

Write CSS in DerivedCSS

DerivedCSS is the CSS text for the selected theme. Turnkey theme variables are CSS custom properties, also called CSS variables. Put variable declarations inside the CSS :root selector.

For example, a theme named Compact blue can have this DerivedCSS value:

:root {
  --navbar-bg-color: 25, 70, 120;
  --primary-color: 25, 70, 120;
  --base-font-size: 14px;
  --data-table-row-height: 28px;
}

Color variables use RGB component values, for example 25, 70, 120. Size variables use pixel values as documented for the individual variable. Check Documentation:MDriven Turnkey theming for the complete list of changeable properties, their expected value formats, and examples of file-based CSS custom properties.

Choose values deliberately

A theme changes the global visual language of the application. Test both readable text contrast and the effect on dense views.

For example:

Change --navbar-bg-color when you want the navigation bar to identify a product or environment.
Change --save-action-bg-color and --cancel-action-bg-color when those actions need to match your application's palette.
Change --base-font-size and --data-table-row-height together when creating a compact layout. Reducing font size without checking row height can make table content hard to read.

Select themes at runtime

Store each alternative as a theme-data object with its own Name and DerivedCSS. Your selection logic must make the chosen object available at SysSingleton.oclsingleton.PickedThemeData.

For example, if an administrator chooses Compact blue, set the singleton's picked theme to that theme-data object. When the picked object instead contains a different DerivedCSS value, Turnkey can apply that theme's CSS without requiring a different CSS file for each choice.

The CSS generation can be triggered at runtime through SysSingleton.MiscSetting. Use the Theme Builder example to inspect the intended model pattern before adding this behavior to an existing application.

Precedence and testing

A matching rule in tkusercss.css overrides the value supplied by theme data. If a data-theme value appears to have no effect, check tkusercss.css first.

When testing a data theme:

Select or update the theme-data object.
Trigger CSS generation through the application's configured SysSingleton.MiscSetting behavior.
Reload the Turnkey page to see the new CSS.
If the server does not reflect the change, restart the Turnkey site and reload the page.
Check tkusercss.css for an overriding declaration.

Do not use a data theme to replace semantic, data-driven highlighting on individual UI elements. For example, a green or red status label based on a business condition belongs to Documentation:StylesInModel, where a ViewModel styling expression can select the appropriate style.

Choose the right styling method

Need	Use	Example
Select one of several global themes while the application runs	Theme as data	An administrator chooses a compact or a high-contrast application theme.
Adjust standard global Turnkey variables in a CSS file	Documentation:MDriven Turnkey theming	Set `--primary-color` in `tkusercss.css`.
Replace or extensively change the Turnkey stylesheet structure	Documentation:MDriven Turnkey theming	Build and deploy a `theme-user.css` file from SCSS.
Highlight a control or row from business data	Documentation:StylesInModel	Show a red style when a value is outside its allowed range.

Contents