Documentation:Theme and style

Theme and style

This page was created by Hans.karlsen on 2016-12-08. Last edited by Wikiadmin on 2026-07-29.

You can deploy Turnkey theme files, CSS, and other site assets with your MDriven model by placing them in a correctly named _AssetsTK folder; this page is for developers who upload a model to MDrivenServer.

Use AssetsTK to deploy files with a model

An AssetsTK folder is a folder beside your model file. When you upload the model, MDriven includes the folder in the model sent to MDrivenServer. MDriven Turnkey extracts it and expands its contents into the Turnkey application root (AppRoot), preserving the folder structure.

Use AssetsTK when a file must be present in the deployed Turnkey site, for example:

A CSS file such as Content/tkusercss.css.
A compiled theme file such as Content/theme-user.css.
An image, font, or other static asset referenced by your styling.
A C# assembly used for C#-developed logic.

For guidance on choosing a styling approach, see HowTos:Styling and Theming Your Application. For CSS variables, SCSS themes, and the supported Turnkey theme files, see Documentation:MDriven Turnkey theming.

Name and place the AssetsTK folder

Create the folder next to the .modlr or .ecomdl model file. Its name must be the model file name with the extension replaced by _AssetsTK.

Model file	AssetsTK folder
`products.azurewebsites.net__MDrivenServerA0.modlr`	`products.azurewebsites.net__MDrivenServerA0_AssetsTK`
`MyApplication.ecomdl`	`MyApplication_AssetsTK`

Do not append _AssetsTK after the extension. For example, MyApplication.modlr_AssetsTK does not follow the required naming pattern.

Deploy a CSS customization

Follow these steps to deploy a CSS file with the model:

Locate the directory containing your .modlr or .ecomdl file.
Create the sibling folder named <ModelName>_AssetsTK.
Inside that folder, create the same relative folder structure that the file must have in the Turnkey application.
Put the CSS file in that structure. For example, place a CSS-variable customization at <ModelName>_AssetsTK/Content/tkusercss.css.
Upload the model with MDriven Designer.
Open or refresh the Turnkey application and verify the change.

For example, a tkusercss.css file can define CSS custom properties:

:root {
  --primary-color: 245, 156, 26;
  --navbar-bg-color: 245, 156, 26;
}

The color values in these Turnkey variables use RGB values. The available variables and the CSS-variable workflow are documented in Documentation:MDriven Turnkey theming.

Deploy a compiled SCSS theme

If you create a theme from SCSS using the local prototyping workflow, deploy the resulting theme-user.css through AssetsTK. Keep the relative path used by the Turnkey application, for example:

<ModelName>_AssetsTK/
  Content/
    scss/
      theme-user.css

The Turnkey application recognizes Content/scss/theme-user.css and uses it instead of the default theme CSS. The theming documentation also identifies Content/theme-user.css as a deployment location. Follow Documentation:MDriven Turnkey theming for the local SCSS compilation workflow and for restoring the standard theme.

What happens during upload

When you upload the model:

MDriven includes the matching _AssetsTK folder in the uploaded model.
On the server, MDriven Turnkey unpacks the folder under AppData using the name ExtractForExpansionInSite_AssetsTK.
Turnkey expands the assets into AppRoot while retaining their relative paths.

For example, the uploaded file <ModelName>_AssetsTK/Content/tkusercss.css is expanded as the application's Content/tkusercss.css file.

Remove previously deployed files

Uploading a changed AssetsTK folder does not by itself remove a file that was copied in an earlier expansion. Use one of the following cleanup methods.

Remove one known file

To delete a specific expanded file, include a marker file with .DELETE appended to the original file name and path.

For example, to delete the deployed file Content/obsolete.css, add this file to AssetsTK:

<ModelName>_AssetsTK/Content/obsolete.css.DELETE

During expansion, the copy logic detects the marker and deletes Content/obsolete.css from the application.

Reset known asset locations

For a broad reset, create an empty file named CleanAll.txt at the root of the AssetsTK folder:

<ModelName>_AssetsTK/CleanAll.txt

CleanAll.txt cleans known asset locations and names back to their default state. Use it when you need to start over after extensive asset changes.

Large file changes can cause a site restart and a log message such as shutDownMessage Change Notification for critical directories. Normal asset expansion changes as few files as possible to avoid this. Use CleanAll.txt when the required reset outweighs the risk of a restart.

Troubleshoot asset expansion

Check permissions

Asset expansion needs permission to create and update files. If expansion fails, ensure that the IIS_IUSRS group has sufficient rights in App_Data.

Read the expansion log

Look for ExtractForExpansionInSite.log in App_Data. It records file-creation failures. For example:

Problem expanding AssetsTK:Access to the path 'C:\inetpub\wwwroot\MTTK\App_Data\..\Content\Something.png' is denied.
Time: 11:19:12

This message means that the IIS user lacks access to the target location. Correct the relevant IIS-user permissions, then upload the model again.

Verify the deployed path

If a style change is not visible:

Confirm that the AssetsTK folder is beside the model file and has the exact required name.
Confirm that the asset's path inside AssetsTK matches its intended path below AppRoot. For example, Content/tkusercss.css must remain below a Content folder.
Check App_Data/ExtractForExpansionInSite.log for expansion errors.
Refresh the application after upload.
Check whether another theming mechanism overrides the result. In particular, CSS in tkusercss.css overrides corresponding values supplied through Theme as data.

Choose the right styling mechanism

AssetsTK deploys files; it does not define how the application should be styled. Choose the styling mechanism based on what you need to change.

Need	Use	Example
Set common Turnkey colors, sizes, and other supported CSS variables	`Content/tkusercss.css` deployed through AssetsTK	Set `--primary-color` for the application.
Make broad visual changes from SCSS source	A compiled `theme-user.css` deployed through AssetsTK	Change navigation-bar colors and component sizing in an SCSS theme.
Change themes at runtime from application data	Theme as data	Let a user select between stored CSS rule sets.
Style a control based on model data, including non-web clients	StylesInModel	Show a value with one style when it is positive and another when it is negative.

Contents